1---2name: agent-patterns3description: Multi-agent design patterns for Claude Code and AI development systems. Covers custom subagents, built-in subagents (Explore/Plan/General-purpose), fungible vs specialized agents, delegation, orchestration, batch workflows, context hygiene, and failure recovery. Use when: designing multi-agent systems, creating custom subagents, delegating bulk operations, orchestrating parallel work, choosing between fungible and specialized agents, configuring agent frontmatter, or debugging agent coordination issues.4license: MIT5---6
7# Agent Patterns
8
9Multi-agent design, delegation, and orchestration in Claude Code and AI-assisted development. Default to fungible agents for large-scale software dev; use specialized agents only for peer review or discourse-based workflows.
10
11Subagents in Claude Code are specialized AI assistants that run in isolated context windows with custom system prompts, specific tool access, and independent permissions. They preserve main conversation context by keeping exploration, test runs, and verbose operations out of the primary thread.
12
13Key constraint: subagents cannot spawn other subagents. Multi-step orchestration requires chaining subagents from the main conversation.
14
15## Quick Reference
16
17| Pattern | Description | When to Use |
18| ------------------------- | ------------------------------------------------- | -------------------------------------------- |
19| Fungible swarm | Identical agents pick tasks from a shared board | Large-scale software dev, resilient systems |
20| Sequential pipeline | Each agent builds on previous output | Multi-step workflows with clear dependencies |
21| Hierarchical | Manager decomposes, workers execute in parallel | Complex tasks with independent subtasks |
22| Peer collaboration | Agents iterate until consensus | Code review, quality-critical outputs |
23| Orchestrator delegation | Main conversation chains subagents | Multi-phase workflows, parallel specialists |
24| Two-stage review | Spec compliance check, then code quality check | High-stakes code, complex requirements |
25| Question-first delegation | Agent asks clarifying questions before proceeding | Ambiguous tasks, expensive-to-redo work |
26| Review loop enforcement | Fix-review cycle with max iteration escalation | Any review workflow needing convergence |
27
28| Built-in Subagent | Model | Tools | Purpose |
29| ----------------- | -------- | --------- | ------------------------------------------------- |
30| Explore | Haiku | Read-only | File discovery, code search, codebase exploration |
31| Plan | Inherits | Read-only | Codebase research during plan mode |
32| General-purpose | Inherits | All tools | Complex research, multi-step operations |
33| Bash | Inherits | Terminal | Running terminal commands in separate context |
34| Claude Code Guide | Haiku | Read-only | Answering questions about Claude Code features |
35
36| Configuration | Value |
37| ------------------------ | --------------------------------------------------------------------------------- |
38| Custom agent location | `.claude/agents/*.md` (project), `~/.claude/agents/*.md` (user) |
39| CLI agents | `--agents '{...}'` (session only, JSON format) |
40| Plugin agents | Plugin `agents/` directory (lowest priority) |
41| Required fields | `name`, `description` |
42| Optional fields | `tools`, `disallowedTools`, `model`, `permissionMode`, `skills`, `hooks`, `color` |
43| Model values | `sonnet`, `opus`, `haiku`, `inherit` (default) |
44| Permission modes | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
45| Nesting limit | Subagents cannot spawn other subagents (one level only) |
46| Foreground vs background | Foreground blocks main conversation; background runs concurrently |
47| Batch size | 5-8 items per agent (standard tasks) |
48| Parallel agents | 2-4 simultaneously |
49
50## When to Use Subagents vs Main Conversation
51
52| Use Subagents When | Use Main Conversation When |
53| --------------------------------------------------------------- | ---------------------------------------------------------- |
54| Task produces verbose output (test suites, logs, API responses) | Task needs frequent back-and-forth or iterative refinement |
55| Enforcing specific tool restrictions or permissions | Multiple phases share significant context |
56| Work is self-contained and can return a summary | Making a quick, targeted change |
57| Parallel independent research paths | Latency matters (subagents start fresh and gather context) |
58
59## Tool Access Patterns
60
61| Agent Role | Recommended Tools | Rationale |
62| ------------------ | --------------------------------------- | --------------------------------------------- |
63| Read-only reviewer | `Read, Grep, Glob` | Cannot modify code; safe for audits |
64| File creator | `Read, Write, Edit, Glob, Grep` | NO Bash; avoids heredoc approval spam |
65| Script runner | `Read, Write, Edit, Glob, Grep, Bash` | Full access for build/deploy tasks |
66| Research agent | `Read, Grep, Glob, WebFetch, WebSearch` | External data access for documentation lookup |
67
68Subagents inherit all tools by default (including MCP tools). Use `tools` as an allowlist or `disallowedTools` as a denylist to restrict access. MCP tools are not available in background subagents.
69
70## Common Mistakes
71
72| Mistake | Correct Pattern |
73| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
74| Expecting subagents to spawn sub-subagents | Subagents cannot nest; chain subagents from the main conversation instead |
75| Giving Bash tool to agents that only create files | Use Write and Edit tools only; Bash causes approval spam from heredoc usage |
76| Omitting `disallowedTools` for sensitive operations | Use `disallowedTools` to explicitly deny dangerous tools even when inheriting |
77| Spawning too many agents (5+) for a small task | Start with 2-3 agents; coordination overhead outweighs benefit at higher counts |
78| Burying critical instructions past line 300 of agent prompt | Put critical rules immediately after frontmatter; models deprioritize late instructions |
79| Using specialized agents for large-scale software dev | Use fungible agents with a shared task board; specialized agents create single points of failure |
80| Not including "FIX issues found" in delegation prompts | Without explicit action directive, agents only report problems without making changes |
81| Setting model to Haiku for content generation | Default to Sonnet; Haiku only for script execution, fast lookups, or pass/fail checks |
82| Not writing clear descriptions for custom agents | Claude uses the `description` field to decide when to auto-delegate; vague descriptions prevent delegation |
83| Using MCP tools in background subagents | MCP tools are not available in background subagents; run in foreground instead |
84| Not preloading skills into subagents | Subagents do not inherit skills from the parent; list them explicitly in the `skills` field |
85
86## Delegation
87
88- **Explore codebase before designing agent prompts**: Claude auto-delegates to the built-in Explore subagent (Haiku, read-only) for file discovery and code search; supports quick, medium, and very thorough modes
89- **Plan multi-agent architecture for complex projects**: Use plan mode; Claude delegates research to the Plan subagent before presenting a plan
90- **Execute batch operations across many files**: Chain General-purpose subagents from the main conversation with identical prompts and non-overlapping item lists
91- **Isolate high-volume operations**: Delegate test runs, log processing, or doc fetching to subagents to keep verbose output out of your main context
92- **Run parallel research**: Spawn multiple subagents simultaneously for independent investigations; Claude synthesizes findings when all complete
93- **Resume interrupted work**: Ask Claude to continue a previous subagent; resumed agents retain full conversation history including tool calls and reasoning
94
95> For project-level workflow sequencing, phase-gate validation, goal decomposition, and capability scoring, use the `orchestration` skill.
96
97## References
98
99- [Agent types and design patterns](references/agent-types.md)
100- [Delegation patterns and batch workflows](references/delegation-patterns.md)
101- [Sub-agent configuration and prompt engineering](references/sub-agent-configuration.md)
102- [Communication and orchestration patterns](references/orchestration.md)
103- [Troubleshooting and anti-patterns](references/troubleshooting.md)
oakoss