Claude Code Subagents

Spawn specialized subagents for planning, coding, and reviewing within one session.

Claude CodeAdvanced

Why

Stack Overflow's 2025 Developer Survey reports 9.7% of developers use Claude Code, and JetBrains' January 2026 AI Pulse found 18% of professional developers use it at work, up 1.5x since September 2025. Subagents let one Claude Code session delegate focused subtasks to separate contexts (planner, coder, reviewer), keeping the main context clean and parallelizing work.

This is the built-in version of multi-agent orchestration without external drivers.

When

Use subagents for big features that decompose into independent steps, or when you want a reviewer to gate the coder inside one session. Skip for one-shot tasks.

How

1. In a session, ask Claude to spawn a subagent: "use a planner subagent to break this down". 2. Define the subagent's role and scope in the prompt. 3. The subagent runs in its own context and returns a result to the main agent. 4. Chain: planner → coder → reviewer, each as a subagent. 5. Review the merged result and run the gate.

Example

> Use a planner subagent to decompose "add /books hub" into steps with file targets. [planner returns 5 steps] > For each step, use a coder subagent scoped to that file, then a reviewer subagent. > Merge approved steps and run npm test. Each subagent starts with a clean context, avoiding cross-contamination.

Common Problems

⚠Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.
⚠"Error: ENOTFOUND api.anthropic.com" → check `echo $ANTHROPIC_API_KEY` is set and network/proxy allows api.anthropic.com:443.
⚠Error: Rate limit: "429 Too Many Requests" → run `/cost` to check usage, `/compact` to shrink context, or wait for quota reset.

Best Practices

✓Give each subagent a clear role, scope, and output format.
✓Keep the main agent as the orchestrator; it merges and gates subagent results.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Claude Code Subagents?

Spawn specialized subagents for planning, coding, and reviewing within one session. It helps developers quickly grasp the core value and use cases of Claude Code Subagents.

How do I get started with Claude Code Subagents?

To get started with Claude Code Subagents, focus on these points first: In a session, ask Claude to spawn a subagent: "use a planner subagent to break this down".

What are common mistakes with Claude Code Subagents?

Common mistakes when using Claude Code Subagents include: Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.; "Error: ENOTFOUND api.anthropic.com" → check `echo $ANTHROPIC_API_KEY` is set and network/proxy allows api.anthropic.com:443.; Error: Rate limit: "429 Too Many Requests" → run `/cost` to check usage, `/compact` to shrink context, or wait for quota reset..

What are the best practices for Claude Code Subagents?

Best practices for Claude Code Subagents include: Give each subagent a clear role, scope, and output format.; Keep the main agent as the orchestrator; it merges and gates subagent results.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Claude Code Subagents?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.