AI Design Patterns

Developers already share a vocabulary for structure: Observer, Chain of Responsibility, Circuit Breaker, Saga. This page maps that vocabulary onto agent harnesses, names the Claude Code mechanism behind each mapping, and states where the mapping fails.

Status: No standard crosswalk exists. Published mappings agree on some pairs and disagree on others, and none of the sources read for this page maps classic patterns to Claude Code mechanisms except for hooks and CLAUDE.md. Every other Claude Code column entry is this guide’s mapping, marked Our mapping. Mechanisms are checked against the official documentation (last verified 2026-10-27).

Use this page for: explaining an agent design to developers in terms they know, and checking a design against the failure modes each pattern carries. For the components of a harness, see Agent Harness Engineering. For loop and graph contracts, see Loop & Graph Engineering. For patterns inside a single skill, see Skill Design Patterns.

The tables on this page are generated from machine-readable/ai-design-patterns.json by scripts/build-ai-design-patterns.py. Edit the dataset, not the tables.

Contents

1. TL;DR
2. Lineage
3. How to read
4. Crosswalk
5. Pattern cards
6. Where the analogy breaks
7. Native agent patterns
8. Choose a pattern
9. Anti-patterns
10. Classic side
11. Further reading
12. Sources

---

TL;DR

• The classic patterns in this table still describe agent systems, but the component in the middle is now a model that decides at runtime. A pattern that relied on a fixed order or a guaranteed call needs a deterministic check next to it.
• In Claude Code, the mappings with the clearest documented mechanism are Observer to hooks, Memento to checkpoints, Mediator to the main conversation coordinating subagents, Bulkhead to subagent context and worktree isolation, and Circuit Breaker to turn and budget limits. Only Observer and Facade are named by a source; the others are this guide’s mapping.
• Two common assumptions are wrong in detail. Hooks for the same event run in parallel, so they do not form a chain. Checkpoints track Claude’s file edits only, so rewind does not undo shell commands or remote effects.
• Each pattern card ends with a check you can run.

Lineage

Three generations of patterns solve the same kind of problem at different scales:

• Object patterns (Gamma, Helm, Johnson, Vlissides, 1994) describe how objects collaborate inside one program. The structure is fixed when the code is written.
• Integration and distributed patterns (Hohpe and Woolf’s Enterprise Integration Patterns, 2003, and the resilience patterns that followed) describe how services exchange messages and survive partial failure.
• Agent patterns (Anthropic’s Building effective agents, 2024, and the catalogs that followed) describe how a harness steers a model that chooses its next action itself.

Jia Huang’s Pattern Evolution frames the third step as the shift from a structure chosen at design time to a decision taken at runtime by a model working with incomplete information. That shift is why each card below carries a failure mode: the classic name describes the structure, and the card states which behavior the harness no longer guarantees.

Practitioners make the same connection on stage. Frank Coyle (UC Berkeley) recalls the 1990s movement: “We now have patterns for agents, but there’s also anti-patterns” (talk, 2:13). Nishant Gupta (Meta Superintelligence Labs) maps the older layer directly: “Distributed systems have solved something similar for decades” (talk, 6:03). On The Pragmatic Engineer, the case is that agents need the guardrails of enterprise patterns: “old patterns are seeming to coming back” (episode, 44:04). Talks for individual patterns are linked from each card under Watch.

How to read

Each crosswalk row carries two labels.

Label	Meaning
Consensus	Two or more distinct sources map the classic pattern to the same main agent analogue. A card may add a second reading that refines it.
Single source	One source proposes the mapping. Treat it as a proposal.
Divergent	Sources map the same classic pattern to different agent analogues. The card lists each reading with its source.
Named by a source	A source names the Claude Code mechanism itself.
Our mapping	Sources give the generic agent analogue; this guide maps it to Claude Code.

A row enters the table only when three conditions hold: a public source maps the classic pattern to an agent analogue, a documented Claude Code mechanism exists, and a failure mode can be stated. Saga is the one deliberate exception: Claude Code has no native compensation mechanism, and the row documents that gap.

Crosswalk

Classic pattern	Family	Agent analogue	In Claude Code	Evidence	Mapping
Factory Method	GoF creational	Subagent spawning from a named definition	Subagent definitions and the Agent tool	Consensus	Our mapping
Singleton	GoF creational	Shared tool registry / Layered memory governance: decide which state is shared, isolated, persisted, or ephemeral	CLAUDE.md hierarchy and auto memory	Divergent	Our mapping
Adapter	GoF structural	Tool adapter that exposes an external system to the model	MCP servers	Consensus	Our mapping
Composite	GoF structural	An agent that delegates to agents that can delegate again	Nested subagents (spawn depth)	Consensus	Our mapping
Decorator	GoF structural	Guardrail wrapped around a model call / Context-injection middleware that enriches each request	UserPromptSubmit and PostToolUse hooks	Divergent	Our mapping
Facade	GoF structural	Project instruction file as the single entry point for conventions	CLAUDE.md	Single source	Named by a source
Chain of Responsibility	GoF behavioral	Hook or permission pipeline in front of tool calls / Agents chained so each one handles what it can and passes the rest	Permission rules: deny, then ask, then allow	Divergent	Our mapping
Command	GoF behavioral	A tool call: a named action with structured arguments	Tool calls and PreToolUse hooks	Consensus	Our mapping
Mediator	GoF behavioral	Orchestrator that coordinates workers which never talk to each other	Main conversation coordinating subagents; Agent teams (experimental, off by default; peer messaging, the non-mediated alternative)	Consensus	Our mapping
Memento	GoF behavioral	Checkpoint and rewind of agent state	Checkpointing and /rewind	Consensus	Our mapping
Observer	GoF behavioral	Lifecycle hooks that react to agent events	Hooks (PreToolUse, PostToolUse, Stop, SubagentStop)	Consensus	Named by a source
Strategy	GoF behavioral	Model or approach selected per task / Runtime strategy switching, with the harness recording why, at what cost, and how to roll back	model field per subagent and /model	Consensus	Our mapping
Template Method	GoF behavioral	System prompt that defines the steps / Fixed agent-loop skeleton with pluggable steps	Skills that define a procedure; Stop hook as the final step check	Divergent	Our mapping
Pipes and Filters	Enterprise integration	Pipeline where each agent or model call is a filter	Print mode in a shell pipeline (claude -p)	Consensus	Our mapping
Content-Based Router	Enterprise integration	Classifier that sends a request to a specialized handler	Automatic delegation by subagent description; Skill selection by description	Consensus	Our mapping
Scatter-Gather	Enterprise integration	Parallel agents followed by a synthesis step	Parallel subagents; Dynamic workflows	Consensus	Our mapping
Bulkhead	Distributed and resilience	Per-agent isolation of context, tools, and budget	Subagent context isolation; isolation: worktree	Consensus	Our mapping
Circuit Breaker	Distributed and resilience	Hard caps on turns, cost, and loop depth / Breakers on tools, models, and the agent’s own loop	—max-turns and —max-budget-usd (print mode); maxTurns in subagent frontmatter	Consensus	Our mapping
Saga	Distributed and resilience	Compensating actions for an agent plan	No native saga: checkpoints plus scripted compensation	Consensus	Our mapping
Sidecar	Distributed and resilience	The agent harness around the model loop	Hooks, permissions, and sandboxing around the loop	Single source	Our mapping
Event Sourcing	Distributed and resilience	The trace log as the event stream of an agent run	Session transcripts, —resume and —continue	Single source	Our mapping

Pattern cards

Factory Method

GoF creational Consensus Our mapping

• Classic intent: Let a creator decide which concrete product to instantiate, behind a common interface.
• Agent side: Subagent spawning from a named definition (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar)
• In Claude Code: Subagent definitions and the Agent tool
• Failure mode: The factory hands every product the full toolbox: a subagent definition without a tools field inherits every tool available to subagents.
• How to verify: List the tools field of each definition in .claude/agents/ and fail review when a write-capable agent has no explicit allowlist.

Singleton

GoF creational Divergent Our mapping

• Classic intent: Guarantee one shared instance of a component with a global access point.
• Agent side, sources disagree:
  • Shared tool registry (Esther Aznar, Ivan Garcia Villar)
  • Layered memory governance: decide which state is shared, isolated, persisted, or ephemeral (Jia Huang)
• In Claude Code: CLAUDE.md hierarchy and auto memory
• Failure mode: One shared memory file becomes mutable global state: parallel sessions or agents that write it at the same time can overwrite each other’s entries.
• How to verify: Run two sessions that both append to the same memory file and check whether either entry is lost.

Adapter

GoF structural Consensus Our mapping

• Classic intent: Convert the interface of an existing component into the interface a client expects.
• Agent side: Tool adapter that exposes an external system to the model (Esther Aznar, Ivan Garcia Villar, Marco Nissen)
• In Claude Code: MCP servers
• Failure mode: The adapter mirrors every upstream endpoint, so tool definitions crowd the context and the model picks among near-duplicate tools.
• How to verify: Run /mcp and /context, then remove or defer the tools that no task in the last sprint used.
• Watch: Christian Tzolov and Dariusz Jędrzejczyk (Devoxx), Unifying AI integration with Model Context Protocol at 21:02: The speakers explain that each vendor exposes its own APIs through an MCP server layer, a unified wrapper the LLM can use.

Composite

GoF structural Consensus Our mapping

• Classic intent: Treat a single object and a tree of objects through the same interface.
• Agent side: An agent that delegates to agents that can delegate again (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar)
• In Claude Code: Nested subagents (spawn depth)
• Failure mode: Recursion without a budget: each layer multiplies token use. Claude Code caps nesting with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, which can be adjusted but not removed.
• How to verify: Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH explicitly for automated runs and log spawned subagents with a SubagentStop hook.
• Watch: Clement Escoffier (Devoxx), From LLM orchestration to autonomous agents: Agentic AI patterns with LangChain4j at 112:21: The speakers show an agent in a sequence that is itself a loop of two agents, so a workflow is used like a single sub agent.

Decorator

GoF structural Divergent Our mapping

• Classic intent: Add behavior to an object by wrapping it, without changing its class.
• Agent side, sources disagree:
  • Guardrail wrapped around a model call (Esther Aznar, Ivan Garcia Villar)
  • Context-injection middleware that enriches each request (AgentPatterns.ai)
• In Claude Code: UserPromptSubmit and PostToolUse hooks
• Failure mode: A classic decorator stack has a fixed order. Matching hooks run in parallel, so a wrapper that assumes another wrapper already ran is a race.
• How to verify: Write each hook so it passes when run alone, and test it with the other hooks disabled.
• Watch: Mark Pollack, Christian Tzolov, Josh Long, James Ward (Devoxx), Bootiful Spring AI at 11:43: The speaker explains Spring AI advisors as a filter or pre-processor that wraps calls to and from the model and can mutate or log each request.
• Watch: Thariq Shihipar, Claude Agent SDK [Full Workshop] at 107:10: An Anthropic speaker says hooks fire as events in the Agent SDK and are used for deterministic verification or for inserting context.

Facade

GoF structural Single source Named by a source

• Classic intent: Offer one simple entry point in front of a complex subsystem.
• Agent side: Project instruction file as the single entry point for conventions (AgentPatterns.ai)
• In Claude Code: CLAUDE.md
• Failure mode: The facade is read as a contract. The docs state that Claude treats CLAUDE.md as context, not enforced configuration: a rule written there is a request, not a guarantee.
• How to verify: For every must-never rule in CLAUDE.md, add a PreToolUse hook or a deny rule and a test that triggers it.

Chain of Responsibility

GoF behavioral Divergent Our mapping

• Classic intent: Pass a request along a chain of handlers until one of them handles it.
• Agent side, sources disagree:
  • Hook or permission pipeline in front of tool calls (AgentPatterns.ai, Ashish Patel)
  • Agents chained so each one handles what it can and passes the rest (Esther Aznar, Ivan Garcia Villar)
• In Claude Code: Permission rules: deny, then ask, then allow
• Failure mode: Teams expect declaration order or rule specificity to decide. The docs state that rules are evaluated deny, then ask, then allow, and specificity does not change that order: a broad deny beats a narrow allow.
• How to verify: Add a deny and a more specific allow for the same command in a test project and check that the command stays blocked.

Command

GoF behavioral Consensus Our mapping

• Classic intent: Turn a request into an object that can be queued, logged, checked, or undone.
• Agent side: A tool call: a named action with structured arguments (Esther Aznar, Ivan Garcia Villar, Ashish Patel)
• In Claude Code: Tool calls and PreToolUse hooks
• Failure mode: The command object is written by the model. Without validation before dispatch, a malformed or out-of-scope argument executes as written.
• How to verify: Feed a PreToolUse hook a recorded tool input with an out-of-scope path and assert that it blocks.

Mediator

GoF behavioral Consensus Our mapping

• Classic intent: Centralize how a set of components talk, so they do not reference each other directly.
• Agent side: Orchestrator that coordinates workers which never talk to each other (Esther Aznar, Ivan Garcia Villar, Sarkar and Sarkar)
• In Claude Code: Main conversation coordinating subagents; Agent teams (experimental, off by default; peer messaging, the non-mediated alternative)
• Failure mode: The mediator becomes the bottleneck: if workers return transcripts instead of summaries, the coordinating context fills with material it never reads again.
• How to verify: Check that each subagent prompt asks for a bounded final report, and compare /context before and after a delegation.
• Watch: Sandipan Bhaumik, From Chaos to Choreography: Multi-Agent Orchestration Patterns That Actually Work at 8:49: In orchestration, every call goes through the orchestrator and agents never call each other.

Memento

GoF behavioral Consensus Our mapping

• Classic intent: Capture an object’s state so it can be restored later without exposing its internals.
• Agent side: Checkpoint and rewind of agent state (AgentPatterns.ai, Ashish Patel)
• In Claude Code: Checkpointing and /rewind
• Failure mode: The snapshot is partial. The docs state that checkpoints only track changes made through Claude’s file editing tools; Bash commands and external processes are not captured, and edits made by a background subagent usually are not either.
• How to verify: Use a Bash command to change a file Claude has not edited in this session, rewind, and confirm the change survives. Commit with git before risky shell work or delegated edits.
• Watch: Hamza Tahir, Your Agents Need a Save Button at 0:14: The speaker argues agents need a save button: runtime checkpoints that let you replay, diff and decide, instead of read-only traces.

Observer

GoF behavioral Consensus Named by a source

• Classic intent: Notify subscribers automatically when a subject changes state.
• Agent side: Lifecycle hooks that react to agent events (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar)
• In Claude Code: Hooks (PreToolUse, PostToolUse, Stop, SubagentStop)
• Failure mode: Subscribers assume an order. The docs state that matching hooks run in parallel, each one runs to completion, and for permission decisions the most restrictive result applies: one hook’s deny does not stop a sibling hook’s side effects.
• How to verify: Run each hook alone against a recorded event payload; a hook that only passes after another one is not an observer.
• Watch: Cole Medin, Watch This If Your Coding Agent is Ignoring Your Rules (You Need Hooks) at 0:44: The speaker defines hooks as actions guaranteed to fire on agent events, such as just before a file read or when the conversation stops.

Strategy

GoF behavioral Consensus Our mapping

• Classic intent: Swap one algorithm for another behind the same interface at runtime.
• Agent side, main reading first:
  • Model or approach selected per task (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar)
  • Runtime strategy switching, with the harness recording why, at what cost, and how to roll back (Jia Huang)
• In Claude Code: model field per subagent and /model
• Failure mode: The strategy changes silently. Nobody can tell afterwards which model produced which result or what the switch cost.
• How to verify: Pin model in each subagent definition and check /usage or the session transcript after a run.
• Watch: Archana Kamath and Tyler Gillam, Preferences Over Benchmarks: Model Routing at 1:46: The speaker argues that one model for every task is overkill and that routing each task to a fitting model cuts cost and risk.

Template Method

GoF behavioral Divergent Our mapping

• Classic intent: Fix the skeleton of an algorithm and let subclasses fill in some steps.
• Agent side, sources disagree:
  • System prompt that defines the steps (Esther Aznar, Ivan Garcia Villar)
  • Fixed agent-loop skeleton with pluggable steps (Ashish Patel)
• In Claude Code: Skills that define a procedure; Stop hook as the final step check
• Failure mode: A prose skeleton is not enforced: the model can skip or reorder a step, unlike a base class that calls the steps itself.
• How to verify: Give the last step an artifact (a file, a test run) and block completion with a Stop hook when the artifact is missing.
• Watch: Cole Medin, Stripe’s Coding Agents Ship 1,300 PRs EVERY Week - Here’s How They Do It at 7:01: The speaker describes Stripe’s blueprints: agent skills interwoven with deterministic code in a fixed workflow.

Pipes and Filters

Enterprise integration Consensus Our mapping

• Classic intent: Process a message through a sequence of independent steps connected by channels.
• Agent side: Pipeline where each agent or model call is a filter (Roan Brasil, Marco Nissen)
• In Claude Code: Print mode in a shell pipeline (claude -p)
• Failure mode: A filter emits free text that the next filter misreads, and the error travels down the pipe.
• How to verify: Use —output-format json between steps and validate the shape before the next filter runs.
• Watch: Mark Pollack, Christian Tzolov, Josh Long, James Ward (Devoxx), Bootiful Spring AI at 38:11: The speaker pipes git log into claude -p to generate release notes and calls it pipes and filters all over again.
• Watch: Kevin Dubois and Mario Fusco (Devoxx), Agentic AI Patterns at 8:11: The speakers present the sequence pattern, calling one agent after another, also known as prompt chaining.

Content-Based Router

Enterprise integration Consensus Our mapping

• Classic intent: Route each message to a destination based on its content.
• Agent side: Classifier that sends a request to a specialized handler (Roan Brasil, Anthropic)
• In Claude Code: Automatic delegation by subagent description; Skill selection by description
• Failure mode: Overlapping descriptions route the same request to different handlers from one run to the next.
• How to verify: Keep a set of routing prompts with the expected subagent or skill, and rerun it after every description change.
• Watch: Goulven Le Dû (Doctolib), Alfred le système Agentic AI de Doctolib au service des professionnels de santé at 4:12: Doctolib’s Alfred has a route agent that uses an intention classification model to send each request to a specialized agent.
• Watch: Renato Guerra Cavalcanti (Devoxx), Akka: an enterprise runtime for resilient agentic AI at 13:41: The speaker describes a router that receives a message and decides which agent gets it, by LLM or plain if and else.

Scatter-Gather

Enterprise integration Consensus Our mapping

• Classic intent: Send a request to several recipients and aggregate their replies.
• Agent side: Parallel agents followed by a synthesis step (Esther Aznar, Ivan Garcia Villar, Roan Brasil)
• In Claude Code: Parallel subagents; Dynamic workflows
• Failure mode: The gather step averages contradicting answers instead of reconciling them, and token cost grows with every branch.
• How to verify: Make the synthesis step list disagreements explicitly, and compare the run’s cost with a single-agent baseline.
• Watch: Renato Guerra Cavalcanti (Devoxx), Akka: an enterprise runtime for resilient agentic AI at 13:06: The speaker describes calling several agents in parallel, waiting for all results and passing them to a summarizer.
• Watch: Colin (LangChain), Dynamic Subagents: How to Run Parallel Agents Reliably in Deep Agents at 0:46: In a demo, the agent fans out 15 subagents in parallel and then picks the best result.

Bulkhead

Distributed and resilience Consensus Our mapping

• Classic intent: Isolate resources per consumer so one failure cannot sink the whole system.
• Agent side: Per-agent isolation of context, tools, and budget (Esther Aznar, Ivan Garcia Villar, Jia Huang)
• In Claude Code: Subagent context isolation; isolation: worktree
• Failure mode: Only the context is isolated. Parallel agents still share one checkout and overwrite each other’s files.
• How to verify: Give write-capable parallel subagents isolation: worktree and check that git status in the main checkout stays clean during the run.

Circuit Breaker

Distributed and resilience Consensus Our mapping

• Classic intent: Stop calling a failing dependency after repeated failures, and fail fast.
• Agent side, main reading first:
  • Hard caps on turns, cost, and loop depth (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar, James Davies)
  • Breakers on tools, models, and the agent’s own loop (Jia Huang)
• In Claude Code: —max-turns and —max-budget-usd (print mode); maxTurns in subagent frontmatter
• Failure mode: The breaker is static, not failure-triggered, and often set on one layer only: —max-turns has no limit by default and counts turns, not cost, so it needs —max-budget-usd beside it.
• How to verify: Run the automated job with —max-turns and —max-budget-usd set, on a task designed to loop, and check that it exits with an error.
• Watch: Sandipan Bhaumik, From Chaos to Choreography: Multi-Agent Orchestration Patterns That Actually Work at 16:51: The speaker applies the circuit breaker to agent-to-agent calls: after repeated failures the circuit opens, fails fast, then half-opens to test recovery.
• Watch: Tisha Chawla and Susheem Koul, FinOps for AI Agents: Who Spent All the Tokens? at 17:36: In a demo, an agent that exceeds its per-run budget is killed immediately, which the speaker calls a simple circuit breaker.

Saga

Distributed and resilience Consensus Our mapping

• Classic intent: Run a long transaction as local steps, each with a compensating action if a later step fails.
• Agent side: Compensating actions for an agent plan (AgentPatterns.ai, Esther Aznar, Ivan Garcia Villar, Jia Huang, Vasundra Srinivasan)
• In Claude Code: No native saga: checkpoints plus scripted compensation
• Failure mode: Rewind is mistaken for compensation. It restores local file edits only; a push, an API call, or a database write stays done.
• How to verify: For every side-effecting step in an agent plan, write down its compensating action before the run, and test that action once.
• Watch: Sandipan Bhaumik, From Chaos to Choreography: Multi-Agent Orchestration Patterns That Actually Work at 19:02: The speaker presents the compensation or saga pattern: each agent has execute and compensate, and on failure the orchestrator walks backward calling compensate.
• Watch: Salman Munaf, AI Agents Are Just Distributed Systems Now at 12:10: The speaker says a multi-step agent that fails midway must reverse the whole transaction across systems and needs a defined compensation operation.

Sidecar

Distributed and resilience Single source Our mapping

• Classic intent: Attach cross-cutting capabilities (logging, policy, networking) next to a service instead of inside it.
• Agent side: The agent harness around the model loop (Jia Huang)
• In Claude Code: Hooks, permissions, and sandboxing around the loop
• Failure mode: Policy lives in the prompt instead of the sidecar, so the model can talk itself out of it. A policy hook can also fail open: on most events, a hook that crashes or times out lets the action through unless it sets onFailure: “block”.
• How to verify: List each safety rule and name the layer that enforces it: hook, permission rule, sandbox, or prompt only. For each policy hook, point it at a missing script and check that the action is blocked.

Event Sourcing

Distributed and resilience Single source Our mapping

• Classic intent: Store every state change as an event, and rebuild state by replaying the log.
• Agent side: The trace log as the event stream of an agent run (Jia Huang)
• In Claude Code: Session transcripts, —resume and —continue
• Failure mode: Replay is assumed to reproduce the result. Resuming a session restores the conversation, but the model calls that follow are not deterministic.
• How to verify: Treat the transcript as an audit trail, not a replay log: pin the inputs you need to reproduce outside it.
• Watch: Jonas Templestein, Make your own event-sourced agent harness using stream processors at 1:45: The speaker wants to build a coding agent harness that is purely event sourced, because the agent already keeps a log of events.
• Watch: Ishaan Sehgal, The Log Is The Agent at 4:19: The speaker argues the log is the durable history from which every view of the agent (debugging, auditing, compaction) is a projection.

Where the analogy breaks

Every break below has the same root: a classic pattern assumes the component in the middle executes what it is given, and a model does not.

Order is not guaranteed. A decorator stack and a chain of handlers run in a known order. Claude Code runs the matching hooks for one event in parallel, and for permission decisions the most restrictive result applies (hooks reference). Every matching hook runs to completion, so one hook’s deny does not stop the side effects of another. Write each hook so it is correct alone. Permission rules, by contrast, are evaluated in a documented order: deny, then ask, then allow, with specificity not changing that order (permissions).

Restore is partial. A memento captures the whole state it needs. Checkpoints only track changes made through Claude’s file editing tools; changes made through Bash commands or external processes are not captured (checkpointing). Edits made by a background subagent are usually outside the checkpoints too: rewinding restores only the files Claude had already edited in the conversation. For anything outside that scope, the Saga question applies: what is the compensating action, and who runs it?

Replay does not reproduce. An event-sourced system rebuilds the same state from the same log. A resumed Claude Code session restores the conversation, and the model calls that follow can differ. Keep the transcript as an audit trail, and pin elsewhere the inputs you need to reproduce a result.

Prose does not enforce. A template method calls its steps; a facade hides the subsystem behind a contract. A skill that lists steps, or a CLAUDE.md file that states rules, is context the model reads. The docs say so directly: Claude treats CLAUDE.md as context, not enforced configuration, and points to a PreToolUse hook to block an action regardless of what Claude decides (memory).

Observers can veto. A classic observer is notified and cannot change what its subject does. A PreToolUse hook can block the tool call it observes, so a hook is closer to a guard than to a listener. The veto only goes one way: a hook that returns allow does not bypass permission rules, and a matching deny or ask rule still applies (permissions).

Guards fail open. A classic guard that throws stops the request. On most events, a Claude Code hook that crashes, cannot start, or times out lets the action through, so a policy hook with a wrong path enforces nothing. Set "onFailure": "block" on a command or HTTP hook to reverse that, available from Claude Code v2.1.295 (hooks reference).

Limits are static. A classic circuit breaker opens after repeated failures and closes again after a cool-down. --max-turns, --max-budget-usd, and maxTurns are fixed caps set before the run (CLI reference): they bound a loop, they do not detect a failing dependency.

The wrapper is probabilistic too. Several sources map Decorator to guardrails or to context injection. A guardrail that is itself a model call inherits the uncertainty it is meant to contain. Keep at least one deterministic check on any path that must not fail.

Native agent patterns

These patterns sit close to classic ones, but they depend on two things classic patterns never had to manage: a context window as the scarce resource, and a model as the decision-maker. Where a crosswalk row covers a similar mechanism, the card names the closest classic pattern and what changes.

Orchestrator-workers

A central model breaks a task down at runtime, delegates the parts, and synthesizes the results.

• What is new: Closest classic pattern: Mediator. The difference is that the model decides the decomposition during the run instead of the designer drawing it. Delegation pays on parallel work: in Google Research’s controlled study, every multi-agent variant degraded a sequential planning task by 39 to 70%.
• In Claude Code: Subagents; Dynamic workflows
• Sources: Anthropic, Claude Code docs: Subagents, Claude Code docs: Dynamic workflows, Yubin Kim, Xin Liu (Google Research)
• Watch: Luke Alvoeiro, The Multi-Agent Architecture That Actually Ships at 4:36: The speaker describes Factory’s Missions system as an orchestrator that plans, workers that execute, and validators that verify.
• Watch: Sandipan Bhaumik, From Chaos to Choreography: Multi-Agent Orchestration Patterns That Actually Work at 8:21: Orchestration is presented as a central workflow orchestrator that calls each agent directly.

Evaluator-optimizer

One call produces an answer, another evaluates it and sends feedback, in a loop.

• What is new: The test oracle is itself a model, so the loop can converge on a wrong answer both sides accept.
• In Claude Code: Reviewer subagent with its own context; Stop hook that runs the real tests
• Sources: Anthropic, Claude Code docs: Subagents, Claude Code docs: Hooks reference
• Watch: Ash Prabaker and Andrew Wilson, Anthropic Workshop: Build Agents That Run for Hours at 19:01: The speakers describe a generator and evaluator split into separate contexts, where the evaluator tests the result with Playwright and feeds critique back.
• Watch: Luke Alvoeiro, The Multi-Agent Architecture That Actually Ships at 5:34: A separate validator role verifies the work, including end-to-end behavior, instead of only reading the code.

Plan-then-execute

Separate a read-only planning phase from the phase that changes files.

• What is new: The plan is produced by the same model that will execute it, so the human review point is the plan, not the code.
• In Claude Code: Plan mode
• Sources: Nikola Balic and contributors, Claude Code docs: Permission modes
• Watch: Matt Pocock, I was an AI skeptic. Then I tried plan mode at 0:22: The speaker plans every change in plan mode, has the AI execute the plan, then tests and commits.

Context isolation

Run a noisy side task in its own context and return only its conclusion.

• What is new: Closest classic pattern: Bulkhead. Here the resource being protected is the context window, not threads or connections.
• In Claude Code: Subagents return only their final response
• Sources: Lance Martin, Claude Code docs: Subagents
• Watch: Colin (LangChain), Dynamic Subagents: How to Run Parallel Agents Reliably in Deep Agents at 1:50: Subagents give context isolation: each runs in its own context window and returns only its results, so the main agent’s context stays clean.
• Watch: Frank Coyle, Anthropic’s CCA Exam as a Field-Guide for Agentic Engineering at 15:17: The speaker names the anti-pattern of letting every subtask dump its full output into the primary thread and says to isolate subtask output instead.

Context compaction

Summarize the conversation when it approaches the window limit, and continue from the summary.

• What is new: State is lossy by design: what the summary drops is no longer in the model’s context for the rest of the session.
• In Claude Code: Auto compaction and /compact
• Sources: Lance Martin, Nikola Balic and contributors, Claude Code docs: Context window
• Watch: Louis-François Bouchard, Omar Solano and Samridhi Vaid (Towards AI), Context Engineering in 2026 at 8:55: The speakers define compaction as keeping the smallest context that can still answer the question and dropping or saving the rest.
• Watch: Ishaan Sehgal, The Log Is The Agent at 4:32: The speaker explains that a log can grow forever while a model’s view cannot, so the log must be compacted into a smaller lossy representation.

Progressive disclosure

Load short descriptions first and the full instructions only when they are needed.

• What is new: Selection happens by the model reading descriptions, so a vague description hides a capability. Skills preloaded through a subagent’s skills field are the exception: their full content loads at launch.
• In Claude Code: Skills: descriptions at start, full content on use; MCP tool search
• Sources: Lance Martin, Claude Code docs: Skills, Claude Code docs: MCP
• Watch: Pedro Rodrigues, Skill Issue: How We Used AI to Make Agents Actually Good at Supabase at 4:25: The speaker says skills brought progressive disclosure, which MCP tools lacked, and later ties Claude Code tool search to the same idea for MCP tools.

Deterministic gate

Put anything that must always happen in code that runs outside the model’s judgment.

• What is new: Closest classic patterns: Sidecar and Chain of Responsibility. The difference is that the rest of the system is probabilistic, so the line between suggestion and enforcement has to be drawn on purpose.
• In Claude Code: PreToolUse hooks; Permission deny rules
• Sources: Anthropic, Claude Code docs: Memory (CLAUDE.md), Claude Code docs: Hooks reference
• Watch: Sachin Malhotra, Give the Agent a Budget, Not a Token at 16:07: An Anthropic speaker describes a proxy layer that counts and compares, returns a 403 when a budget is crossed or a delete is attempted, and cannot be talked out of the rule by prompt injection.
• Watch: Matt Pocock, How to actually force Claude Code to use the right CLI (don’t use CLAUDE.md) at 2:26: The speaker uses a PreToolUse hook that blocks a tool call before it executes, turning CLAUDE.md instructions into deterministic hooks.

Goal loop

Keep the agent working until a stated completion condition is met.

• What is new: Whether the goal is met is judged by a model, so the condition must be checkable.
• In Claude Code: /goal; Stop hook continuation
• Sources: Nikola Balic and contributors, Claude Code docs: Keep Claude working toward a goal, Claude Code docs: Hooks reference
• Watch: Ash Prabaker and Andrew Wilson, Anthropic Workshop: Build Agents That Run for Hours at 8:26: The speakers explain the Ralph loop: feed one prompt to the CLI and run it in a loop until all tasks are complete, with a stop hook and a max iteration count in Anthropic’s plugin.

Choose a pattern

Pick by the shape of the problem, then use the simplest structure that passes its check, as Anthropic’s guidance recommends.

Three questions apply to every branch, whatever the pattern:

• Which side effects leave the machine? Each one needs a written compensating action (Saga), because rewind will not undo it.
• Which rules must never be broken? Each one needs a deterministic gate (a PreToolUse hook or a deny rule), because a prompt does not enforce anything.
• What stops the run? Every automated branch needs a Circuit Breaker: a turn limit and a budget limit, set before the run.

Anti-patterns

The first three categories come from the MAST taxonomy of multi-agent failures (Cemri et al.), which groups 14 failure modes into three categories: specification issues, inter-agent misalignment, and task verification (labels shortened in the table). The fourth category covers Claude Code mechanics that MAST does not address. The assignment of each anti-pattern to a category is this guide’s reading.

Anti-pattern	Symptom	Fix	Category	Related patterns
Prompt as enforcement	A must-never rule lives only in CLAUDE.md or a system prompt.	Deterministic gate: a PreToolUse hook with onFailure: “block”, or a deny rule, with a test.	Specification issues	Deterministic gate, Facade
Context flooding	Workers return full transcripts or logs to the coordinating thread.	Context isolation: ask each worker for a bounded final report.	Inter-agent misalignment	Context isolation, Mediator
Unbounded loop	An automated run has no turn, cost, or depth limit.	Circuit breaker on every layer: —max-turns, —max-budget-usd, maxTurns, spawn depth.	Specification issues	Circuit Breaker, Composite
Unverified done	The agent declares success without running a check, or stops early.	Evaluator-optimizer with a real test, enforced by a Stop hook.	Task verification	Evaluator-optimizer, Template Method
Step repetition	The agent redoes completed steps after an interruption or a reset of the conversation.	Durable progress outside the context (a task list or a file) and idempotent side effects.	Specification issues	Event Sourcing, Saga
Rewind as rollback	A team counts on /rewind to undo shell commands or remote effects.	Saga thinking: git commits before risky work, a written compensation for each external effect.	Harness mechanics (beyond MAST)	Memento, Saga
Ordered hooks assumption	A hook relies on another hook for the same event having run first.	Independent observers: each hook passes or blocks on its own.	Harness mechanics (beyond MAST)	Observer, Decorator
Specific allow overrides deny	A narrow allow rule is added to punch a hole in a broad deny.	Permission rules are evaluated deny, then ask, then allow: narrow the deny instead.	Harness mechanics (beyond MAST)	Chain of Responsibility
Unguarded shared checkout	Parallel write-capable agents edit the same working tree.	Bulkhead: isolation: worktree per writing agent.	Inter-agent misalignment	Bulkhead, Scatter-Gather
Untrusted content as instructions	Fetched pages, issue text, or tool output are allowed to steer the agent’s next action.	Trust boundary: treat external content as data, and keep write and network tools behind permission rules.	Harness mechanics (beyond MAST)	Sidecar, Command

Classic side

The guide already ships a skill that detects the 23 GoF patterns in a codebase: examples/skills/design-patterns/, described in Example 3: Design Patterns Analyzer Skill. Use it on the code an agent produces; use this page on the harness that produces it.

Further reading

Practitioner writing and repositories that cover the same ground from other angles. None of them uses this page’s crosswalk; the related links point to the closest card here.

• Addy Osmani, Agent Harness Engineering: April 19, 2026. A catalog of harness practices: Git as durable state, compaction, skills with progressive disclosure, hooks as the enforcement layer, planner, generator and evaluator splits, and turning each agent mistake into a permanent rule. Related: Context compaction, Progressive disclosure, Deterministic gate, Evaluator-optimizer, Goal loop.
• Birgitta Böckeler (martinfowler.com), Harness engineering for coding agent users: April 2, 2026. A mental model of feedforward guides and feedback sensors, each computational or inferential, with a human steering the loop. Related: Deterministic gate, Evaluator-optimizer.
• Simon Willison, Agentic Engineering Patterns: A guide of practical patterns for coding agents: subagents, red/green TDD, running the tests first, manual testing and anti-patterns. Related: Context isolation, Evaluator-optimizer.
• Andrew Ng, Agentic Design Patterns Part 1 (The Batch): March 2024. The four agentic design patterns that popularized the term: reflection, tool use, planning and multi-agent collaboration. Related: Evaluator-optimizer, Plan-then-execute, Orchestrator-workers.
• Chip Huyen, Agents: January 2025. Tool use, planning and plan validation, reflection, failure modes and agent evaluation. Related: Plan-then-execute, Evaluator-optimizer.
• Lilian Weng, LLM Powered Autonomous Agents: June 2023. The planning, memory and tool-use decomposition that most later catalogs start from. Related: Plan-then-execute, Context compaction.
• DenisSergeevitch, agents-best-practices: An MIT-licensed Agent Skill for designing and auditing harnesses, built on one rule: the model proposes actions, the harness validates, authorizes, executes and records them. Related: Deterministic gate, Sidecar.
• gtzheng, Awesome Agentic System Design: An MIT-licensed reading hub on orchestration, context and memory, tools and protocols, evaluation and production safety. Related: Context isolation, Context compaction.
• josephsenior, Agentic-Design-Patterns: MIT-licensed, small runnable Python implementations of workflow patterns such as chaining, routing, parallelization, reflection and planning. Related: Pipes and Filters, Content-Based Router, Scatter-Gather, Evaluator-optimizer.

Sources

Licenses differ. Text and diagrams from sources without a stated license are cited and linked, never copied. Several widely shared repositories that describe Claude Code design patterns are built from leaked source code; they are excluded, and every Claude Code mechanism on this page is sourced from the official documentation only.

Crosswalks and catalogs

• AgentPatterns.ai, Classical SE Patterns as Agent Design Analogues
• Esther Aznar, Ivan Garcia Villar, Patrones GoF en agentes IA: el mapeo completo
• Jia Huang, Pattern Evolution: GoF, distributed, agent
• Roan Brasil, Agents Integration Patterns
• James Davies, GO4: A Pattern Language for LLM Engineering
• Ashish Patel, Agent Harness Engineering Patterns
• Marco Nissen, Agent Patterns Catalog
• Nikola Balic and contributors, Awesome Agentic Patterns
• DenisSergeevitch, agents-best-practices
• gtzheng, Awesome Agentic System Design
• josephsenior, Agentic-Design-Patterns

Papers

• Jia Huang, Joey Tianyi Zhou, A Two-Dimensional Framework for AI Agent Design Patterns (arXiv 2605.13850)
• Jia Huang, Bingsheng Ru, Bo Liang, Yuke Xiong, Haiyan Fan, Joey Tianyi Zhou, Selecting and Composing Agent Design Patterns: Industrial Case Evidence and Controlled Reference-System Experiments (arXiv 2610.25629)
• Vasundra Srinivasan, Selecting and Composing Runtime Architecture Patterns for Production LLM Agents (arXiv 2605.20173)
• Sarkar and Sarkar, Survey of LLM Agent Communication with MCP: A Software Design Pattern Centric Review (arXiv 2506.05364)
• Cemri et al., Why Do Multi-Agent LLM Systems Fail? (arXiv 2503.13657)
• Yubin Kim, Xin Liu (Google Research), Towards a Science of Scaling Agent Systems (arXiv 2512.08296)

Vendor guidance and articles

• Anthropic, Building effective agents
• Anthropic, Steering Claude Code: skills, hooks, rules, subagents and more
• Lance Martin, Agent design patterns
• Addy Osmani, Agent Harness Engineering
• Birgitta Böckeler (martinfowler.com), Harness engineering for coding agent users
• Simon Willison, Agentic Engineering Patterns
• Andrew Ng, Agentic Design Patterns Part 1 (The Batch)
• Chip Huyen, Agents
• Lilian Weng, LLM Powered Autonomous Agents

Talks

• Sandipan Bhaumik, From Chaos to Choreography: Multi-Agent Orchestration Patterns That Actually Work
• Matt Pocock, How to actually force Claude Code to use the right CLI (don’t use CLAUDE.md)
• Colin (LangChain), Dynamic Subagents: How to Run Parallel Agents Reliably in Deep Agents
• The Pragmatic Engineer, Slow down to speed up: AI and software engineering
• Nishant Gupta, Deterministic Infra for Non-Deterministic AI Agents
• Archana Kamath and Tyler Gillam, Preferences Over Benchmarks: Model Routing
• Tisha Chawla and Susheem Koul, FinOps for AI Agents: Who Spent All the Tokens?
• Pedro Rodrigues, Skill Issue: How We Used AI to Make Agents Actually Good at Supabase
• Cole Medin, Stripe’s Coding Agents Ship 1,300 PRs EVERY Week - Here’s How They Do It
• Christian Tzolov and Dariusz Jędrzejczyk (Devoxx), Unifying AI integration with Model Context Protocol
• Renato Guerra Cavalcanti (Devoxx), Akka: an enterprise runtime for resilient agentic AI
• Clement Escoffier (Devoxx), From LLM orchestration to autonomous agents: Agentic AI patterns with LangChain4j
• Mark Pollack, Christian Tzolov, Josh Long, James Ward (Devoxx), Bootiful Spring AI
• Thariq Shihipar, Claude Agent SDK [Full Workshop]
• Ishaan Sehgal, The Log Is The Agent
• Matt Pocock, I was an AI skeptic. Then I tried plan mode
• Louis-François Bouchard, Omar Solano and Samridhi Vaid (Towards AI), Context Engineering in 2026
• Kevin Dubois and Mario Fusco (Devoxx), Agentic AI Patterns
• Frank Coyle, Anthropic’s CCA Exam as a Field-Guide for Agentic Engineering
• Hamza Tahir, Your Agents Need a Save Button
• Salman Munaf, AI Agents Are Just Distributed Systems Now
• Ash Prabaker and Andrew Wilson, Anthropic Workshop: Build Agents That Run for Hours
• Cole Medin, Watch This If Your Coding Agent is Ignoring Your Rules (You Need Hooks)
• Luke Alvoeiro, The Multi-Agent Architecture That Actually Ships
• Sachin Malhotra, Give the Agent a Budget, Not a Token
• Goulven Le Dû (Doctolib), Alfred le système Agentic AI de Doctolib au service des professionnels de santé
• Jonas Templestein, Make your own event-sourced agent harness using stream processors

Classic references

• Gregor Hohpe, Bobby Woolf, Enterprise Integration Patterns
• Martin Fowler, CircuitBreaker

Claude Code documentation

• Claude Code docs, Hooks reference
• Claude Code docs, Permissions
• Claude Code docs, Permission modes
• Claude Code docs, Checkpointing
• Claude Code docs, Subagents
• Claude Code docs, Agent teams
• Claude Code docs, Dynamic workflows
• Claude Code docs, Memory (CLAUDE.md)
• Claude Code docs, Skills
• Claude Code docs, MCP
• Claude Code docs, CLI reference
• Claude Code docs, Run Claude Code programmatically
• Claude Code docs, Environment variables
• Claude Code docs, Model configuration
• Claude Code docs, Tools reference
• Claude Code docs, Worktrees
• Claude Code docs, Sandboxing
• Claude Code docs, Sessions
• Claude Code docs, Context window
• Claude Code docs, Keep Claude working toward a goal
• Claude Code docs, Security