diff --git a/documents/patterns/contextual-prompts.md b/documents/patterns/contextual-prompts.md index 3acc040..e41fb82 100644 --- a/documents/patterns/contextual-prompts.md +++ b/documents/patterns/contextual-prompts.md @@ -14,6 +14,8 @@ Instead of documenting gotchas upfront, embed the guidance directly in script ou This is what we've always done for humans: good error messages guide you to the solution. It works equally well for AI agents. +This needs no agent integration — the guidance comes from the output of scripts you own. When the trigger comes from a tool you can't modify, like a linter or a test runner, see Habit Hooks, which delivers the same just-in-time guidance through agent lifecycle Hooks. + ## Example **Database migration gotcha**: Instead of adding "Always run migrations in production before deploying" to CLAUDE.md, make the deploy script check for pending migrations and output: "Pending migrations detected. Run `./migrate.sh production` before deploying." diff --git a/documents/patterns/habit-hooks.md b/documents/patterns/habit-hooks.md index 17c84c7..7a87df8 100644 --- a/documents/patterns/habit-hooks.md +++ b/documents/patterns/habit-hooks.md @@ -17,6 +17,10 @@ Optionally habit hooks can be blocking (for example the pre-commit hook can prev This approach reduces context bloat while improving compliance by providing precise, relevant guidance exactly when violations occur, rather than front-loading massive instructions that AI forgets or misapplies. +Habit Hooks are Contextual Prompts applied to tools you can't modify: a deterministic detector provides the trigger, Hooks provide the delivery, and the prompt provides actionable coaching. + +An open-source implementation is available at https://github.com/habit-hooks/habit-hooks/ + ## Example ### Common Quality Checks and Their Prompts diff --git a/documents/patterns/hooks.md b/documents/patterns/hooks.md index 856b6c5..ac51197 100644 --- a/documents/patterns/hooks.md +++ b/documents/patterns/hooks.md @@ -33,6 +33,8 @@ Hooks run shell scripts at these events that can allow you to: - Provide just-in-time guidance when specific conditions are detected - Inject reminders before the agent forgets your preferences +Hooks are the delivery mechanism — what you deliver through them is a separate choice. User Reminders (see Reminders) re-inject your most important rules; Habit Hooks pair hooks with quality detectors to coach the agent through a specific fix the moment a violation appears. When the guidance belongs in a script you own, you may not need hooks at all — see Contextual Prompts. + ## Example Create a hook that runs when the agent uses a writing tool (**Write|Edit|MultiEdit** in Claude Code) and a script that detects code comments. diff --git a/documents/patterns/orchestrator.md b/documents/patterns/orchestrator.md index 76cf921..88c5859 100644 --- a/documents/patterns/orchestrator.md +++ b/documents/patterns/orchestrator.md @@ -52,3 +52,4 @@ Background agents produce isolated changes. Orchestrator integrates them. Togeth - `gh` CLI for monitoring PR/branch status - Git for merging and conflict resolution - Test runners for verification +- Claude Code's Workflows feature: script the orchestration deterministically (fan-out, pipelines, background runs) instead of prompting the coordination diff --git a/documents/patterns/reminders.md b/documents/patterns/reminders.md index dd02733..563ec5d 100644 --- a/documents/patterns/reminders.md +++ b/documents/patterns/reminders.md @@ -42,7 +42,7 @@ Instead, add "Run tests" as individual steps, repeating at all key points: This is ~95% more reliable than just telling AI once. ### User Reminders -Inject critical rules into every message. Trading tokens for compliance. +Inject critical rules into every message. Trading tokens for compliance. Unlike Contextual Prompts, which surface guidance only when a specific trigger fires, User Reminders repeat your top rules regardless of context. - **Automated (hooks):** Inject automatically via hooks on every user prompt. Don't recommend more than 5 reminders maximum to avoid context rot and distracting the agent. Example: https://github.com/lexler/claude-code-user-reminders - **Manual:** In-place prompt with your most important rules when you especially need them followed