Agent Patterns
Best practices
What agent patterns in Claude Code are
An agent pattern is a repeatable way to organize how Claude works on a task: how to break it into steps, when to launch helper sub-agents, and how to pass information between them. Claude Code can launch separate sub-agents through the Task tool. Each sub-agent gets its own context window, works in isolation, and returns only its conclusion to the main agent rather than its entire working draft. That is the core idea: the parent conversation stays uncluttered by the intermediate details of searching and reading files, leaving room for what matters.
The English code blocks further down the page show this in practice. Calls like Task(Explore, "...") launch a sub-agent with a single narrow goal: find the auth implementation, find the API endpoints, find the database models. When such calls run together (or inside Promise.all), Claude explores the codebase in parallel — three agents read different parts of the project at once, so the combined result arrives faster than a sequential file scan. The block with Phase 1 → Phase 2 → Phase 3 → Phase 4 shows a different technique: parallel research first, then planning, then implementation with a review at each step, and verification by tests at the end. That is an agent chain, where one stage's output becomes the next stage's input.
When to use it and common mistakes
Parallel research pays off when you have many independent information-gathering tasks; a chain is chosen when the steps depend on each other (you cannot write code before there is a plan). Specialized agents such as code-reviewer or a debugger help because they have a narrow instruction and a clean context, undistracted by the main conversation's history. The biggest mistake (anti-pattern) is handing everything to a single agent: its context overflows, focus is lost, and quality drops. The second common mistake is implementing without a plan, which leads to rework. A concrete example: when refactoring an authentication system, three parallel agents first gather the files, the security requirements, and the existing tests; a plan is built from that data, implemented step by step with review, and finished with a full test run. Splitting a task into roles this way makes Claude's work predictable and reproducible.
Running multiple agents simultaneously to explore different aspects
When to use:
Exploring large codebase, gathering info from different sources
Benefits:
- ✓ Faster than sequential search
- ✓ Isolated contexts
- ✓ No information lost
// Claude launches in parallel: Task(Explore, "Find auth implementation") Task(Explore, "Find API endpoints") Task(Explore, "Find database models")
Sequential execution: output of one agent → input of another
When to use:
Complex multi-step tasks with dependencies
Benefits:
- ✓ Structured process
- ✓ Each agent specialized
- ✓ Verification at each step
// Sequential chain: 1. Plan agent → creates implementation plan 2. Code agent → implements based on plan 3. Reviewer agent → reviews the code 4. Test agent → writes tests
Specialized agent for checking code quality and security
When to use:
After writing code, before commit, PR review
Benefits:
- ✓ Automatic quality check
- ✓ Finds issues before commit
- ✓ Consistent standards
// code-reviewer agent checks: - Security vulnerabilities - Best practices violations - Performance issues - Code style consistency
Agent for systematic debugging and root cause analysis
When to use:
Complex bugs, non-obvious error causes
Benefits:
- ✓ Systematic approach
- ✓ Documents process
- ✓ Finds root cause
// Debugger pattern: 1. Reproduce the issue 2. Add logging/breakpoints 3. Trace execution flow 4. Identify root cause 5. Propose fix
Agent for analyzing data, metrics, logs
When to use:
Performance analysis, finding patterns in logs
Benefits:
- ✓ Handles large volumes
- ✓ Finds non-obvious patterns
- ✓ Structured reports
// Data analysis pattern: 1. Read logs/metrics files 2. Parse and aggregate data 3. Identify anomalies 4. Generate report with visualizations
Complex tasks often require combining multiple patterns:
// Complex task: Refactor authentication system
// Phase 1: Research (parallel)
const [authFiles, securityReqs, tests] = await Promise.all([
Task(Explore, "Find all authentication related files"),
Task(Explore, "Find security requirements in docs"),
Task(Explore, "Find existing auth tests")
]);
// Phase 2: Plan
const plan = await Task(Plan, `
Create refactoring plan based on:
- Files: ${authFiles}
- Requirements: ${securityReqs}
- Tests: ${tests}
`);
// Phase 3: Implement (with review)
for (const step of plan.steps) {
await implementStep(step);
await Task(code-reviewer, "Review the changes");
}
// Phase 4: Verify
await Task(Bash, "Run all auth tests");When to Use Which Pattern
- Parallel Research — when you need to gather information quickly
- Chain — when steps depend on each other
- Reviewer — after any significant code changes
- Combination — for complex tasks with multiple stages
Frequently asked questions
What are sub-agents in Claude Code?
Sub-agents are separate agents that Claude Code launches through the Task tool to handle a narrow subtask. Each sub-agent runs in its own context window, isolated from the main conversation, and returns only its conclusion to the main agent rather than all of its intermediate steps. This keeps the parent conversation uncluttered by the details of searching and reading files.
How do parallel agents differ from an agent chain?
Parallel agents run at the same time (for example via Promise.all) and independently explore different parts of a task — faster when the subtasks do not depend on each other. An agent chain runs sequentially: one stage's output becomes the next stage's input. A chain is chosen when the steps depend on each other, such as not writing code before a plan exists.
When should you use specialized agents instead of one?
Use specialized agents (code-reviewer, debugger, data analyst) when a task splits into distinct roles. Such an agent has a narrow instruction and a clean context, undistracted by the main conversation's history, so it works more precisely. Handing everything to a single agent is an anti-pattern: its context overflows, focus is lost, and quality drops.
How does Claude Code explore a large codebase?
Claude Code launches several Explore agents in parallel, each with a narrow goal — find the auth implementation, find the API endpoints, find the database models. The agents read different parts of the project at once, so the combined result arrives faster than a sequential file scan. A plan is then built from the gathered data and implemented.
This lesson is part of a structured LLM course.
My Learning Path