From e0c5c9102f991c14bccaaac2bdae0d3c503212ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Wed, 29 Jul 2026 16:48:09 +0200 Subject: [PATCH 1/4] Clarify the boundaries between Hooks, Contextual Prompts, Habit Hooks and User Reminders Co-Authored-By: Claude Opus 5 --- documents/patterns/contextual-prompts.md | 2 ++ documents/patterns/habit-hooks.md | 2 ++ documents/patterns/hooks.md | 2 ++ documents/patterns/reminders.md | 2 +- 4 files changed, 7 insertions(+), 1 deletion(-) diff --git a/documents/patterns/contextual-prompts.md b/documents/patterns/contextual-prompts.md index 3acc040..ac398b9 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 lives in the output of scripts you own. When the trigger comes from a tool you can't modify (a linter, 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..0af453d 100644 --- a/documents/patterns/habit-hooks.md +++ b/documents/patterns/habit-hooks.md @@ -17,6 +17,8 @@ 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 is 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. + ## Example ### Common Quality Checks and Their Prompts diff --git a/documents/patterns/hooks.md b/documents/patterns/hooks.md index 856b6c5..c98a5e0 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 pairs hooks with quality detectors to coach specific fixes. 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/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 From 256affd9f327f3cb32eab5e7fd69e08068fb4dd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Wed, 29 Jul 2026 16:48:32 +0200 Subject: [PATCH 2/4] Link the Habit Hooks open-source implementation Co-Authored-By: Claude Opus 5 --- documents/patterns/habit-hooks.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documents/patterns/habit-hooks.md b/documents/patterns/habit-hooks.md index 0af453d..1120c67 100644 --- a/documents/patterns/habit-hooks.md +++ b/documents/patterns/habit-hooks.md @@ -19,6 +19,8 @@ This approach reduces context bloat while improving compliance by providing prec Habit Hooks is 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 From cd5a828c0ef1adcb3e02e11a0f4e2dd889909003 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Wed, 29 Jul 2026 16:48:32 +0200 Subject: [PATCH 3/4] List Claude Code Workflows among Orchestrator's tools Co-Authored-By: Claude Opus 5 --- documents/patterns/orchestrator.md | 1 + 1 file changed, 1 insertion(+) 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 From cdb7d8da4efc74a18901fe235419fb1e54029f98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Thu, 30 Jul 2026 20:21:30 +0200 Subject: [PATCH 4/4] Apply review wording fixes to the pattern boundary lines Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_012EjEPvjHK2SVy9jjzwMSRm --- documents/patterns/contextual-prompts.md | 2 +- documents/patterns/habit-hooks.md | 2 +- documents/patterns/hooks.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/patterns/contextual-prompts.md b/documents/patterns/contextual-prompts.md index ac398b9..e41fb82 100644 --- a/documents/patterns/contextual-prompts.md +++ b/documents/patterns/contextual-prompts.md @@ -14,7 +14,7 @@ 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 lives in the output of scripts you own. When the trigger comes from a tool you can't modify (a linter, a test runner), see Habit Hooks, which delivers the same just-in-time guidance through agent lifecycle Hooks. +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 diff --git a/documents/patterns/habit-hooks.md b/documents/patterns/habit-hooks.md index 1120c67..7a87df8 100644 --- a/documents/patterns/habit-hooks.md +++ b/documents/patterns/habit-hooks.md @@ -17,7 +17,7 @@ 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 is 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. +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/ diff --git a/documents/patterns/hooks.md b/documents/patterns/hooks.md index c98a5e0..ac51197 100644 --- a/documents/patterns/hooks.md +++ b/documents/patterns/hooks.md @@ -33,7 +33,7 @@ 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 pairs hooks with quality detectors to coach specific fixes. When the guidance belongs in a script you own, you may not need hooks at all — see Contextual Prompts. +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