Sub-Agent Design in Claude Code

Problem: Big coding tasks need more than one kind of expert, but a single Claude session starts thrashing when you ask it to be all of them at once.

Quick Win: Paste this prompt on any review that needs more than one angle:

Create sub-agents and analyze this from these perspectives:
- Senior engineer: Review architecture decisions
- Security expert: Identify vulnerabilities
- Performance reviewer: Find optimization opportunities

You'll get three specialist reads in parallel, back in a couple of minutes.

Why One Context Fails

Ask Claude to review code, tune performance, and check security in the same breath and the answers turn generic. Every angle fights for room in the same context window. Everything ends up shallow.

Sub-agents fix this by giving each view its own context. Each agent stays on its lane, picks its own tools, and works its own method. You pull the findings back together at the end.

Claude Code gives you two ways to run them:

1. Task Tool: The built-in tool spawns isolated sub-agents, each with its own context window.
2. Prompting for Perspectives: A single prompt that asks for several expert viewpoints in one pass.

Task spawns real parallel work. Perspective prompts fake it inside one session. Either way, analysis quality jumps.

1. Find the Parallelizable Tasks

Good candidates for a sub-agent split:

• Code review from several angles
• Research across different technologies
• Documentation review for different audiences
• Performance analysis across different metrics

Skip sub-agents when work is serial:

• File edits that depend on each other
• Sequential build steps
• Database migrations

2. Design Specialist Roles

Pick the viewpoints that match your domain. A few prompt templates that pull their weight:

Code Quality Review:

Analyze this codebase using sub-agents with these specialist roles:
- Factual reviewer: Check technical accuracy against documentation
- Senior engineer: Review architecture decisions and patterns
- Security expert: Identify vulnerabilities and attack vectors
- Consistency reviewer: Check coding standards compliance
- Redundancy checker: Find duplicate logic to consolidate

User Experience Analysis:

Create sub-agents for UX review of this feature:
- Creative thinker: Suggest innovative interaction solutions
- Beginner user: Test ease of use and onboarding friction
- Designer: Evaluate visual hierarchy and spacing
- Marketing analyst: Assess conversion potential
- Accessibility auditor: Check WCAG compliance

3. Orchestrate the Analysis

Each sub-agent picks its own tools. Security agents reach for vulnerability scanners. Performance reviewers pull in profiling tools. Architects look at structure. One agent alone can't cover all three the same way.

Plan Mode for Safe Reads

Before turning specialist sub-agents loose on critical code, drop into plan mode. Hit Shift+Tab twice inside Claude Code. That keeps the run read-only while they work.

Then ask for the multi-angle review:

Use sub-agents to validate this API design from:
- Backend perspective: Data flow and scalability
- Frontend perspective: Consumption patterns and DX
- Security perspective: Authentication and authorization gaps

Plan mode earns its keep when a sub-agent might otherwise try to fix things on its own.

The Consolidation Pattern

Once the sub-agents are done, bring the outputs together:

1. Individual Reports: Each agent writes up its own findings.
2. Conflict Resolution: Pick a winner when two recommendations disagree.
3. Priority Ranking: Sort fixes by impact.
4. Action Plan: Lay out the steps to implement.

Common Mistakes

Mistake: Spawning sub-agents for tiny tasks.

Typos, one-line patches, quick renames. The coordination overhead wipes out the win. Skip the agents.

Better: Save the specialist crew for gnarly, multi-faceted problems:

Use sub-agents to redesign this authentication system:
- Security expert: Audit current vulnerabilities
- UX designer: Simplify the login flow
- Performance engineer: Optimize token handling

Mistake: Stacking roles that mostly overlap.

"Security expert, penetration tester, vulnerability scanner, security architect" is the same viewpoint wearing four hats.

Better: Pick roles that cover different sides of the problem and don't step on each other.

Background Execution

Any sub-agent can run in the background now. Press Ctrl+B while it's working:

You: Audit our authentication module for security issues
Claude: I'll spawn a sub-agent to analyze the auth module...
[Sub-agent starts]
You: [Press Ctrl+B]
You: While that runs, let's optimize the database queries...

Track the background run with /tasks. When it finishes, it wakes the main agent and hands over the results.

Blocking specialists turn into parallel ones. Full async coverage lives in the Background Agents guide.

Cost Win

Sub-agents stretch Claude Sonnet without paying for Opus. Parallel analysis gets you close to Opus-level output at Sonnet prices.

Where the savings come from:

• Several expert takes in one session
• Parallel work trims total runtime
• Specialist context avoids the shallow generalist read
• Better output than a single premium model
• Background execution kills the waiting

Role Rotation

On longer projects, rotate the specialist lineup across components.

Week 1 - Core Architecture:

Analyze the database design using sub-agents:
- Data architect: Schema optimization and normalization
- Security expert: Access control and encryption
- Performance optimizer: Query patterns and indexing

Week 2 - API Layer:

Review API endpoints with these specialist sub-agents:
- Backend engineer: Implementation quality and patterns
- Documentation writer: API clarity and examples
- Integration specialist: Third-party compatibility

Iterative Refinement

Sub-agents are a natural fit for progressive passes:

1. Broad perspectives on the first look
2. Specialist deep dive on the second
3. User-focused review on the third

The result is more complete, more user-centered, and catches things a lone agent misses.

Where Sub-Agents Pay Off

• Architecture Reviews: Several technical lenses at once
• Documentation Audits: Different audiences read different things
• Code Quality Gates: Many quality dimensions in one pass
• Product Strategy: Cross-functional read
• Competitive Analysis: Different market angles

Start with code reviews. Move out into strategic work once you get the "itch for parallelism."

Next Steps

• Execution patterns: When to go parallel, sequential, or background.
• Foundation: Agent Fundamentals covers the basics.
• Implementation: Custom Agents for specialized scenarios.
• Coordination: Task Distribution for big multi-agent projects.
• Optimization: Planning Modes for safe sub-agent runs.
• Context Management: Keep quality high across a whole crew.

Try it on your next code review. The specialist split is the kind of thing you notice the first time.