Claude Code Subagents — When to Spawn Them and How to Write Custom Ones

If you're using Claude Code on a single thread of work, you don't need subagents. The moment you have three independent research questions, or want a fresh pair of eyes on a decision, or need to scope a refactor without polluting your main session — that's where subagents earn their place.

This is the practical guide: when to spawn, how to brief, and what to actually build.

Subagents vs Agents — same thing

In Claude Code, "agent" and "subagent" refer to the same primitive: an isolated work thread spawned from your main session via the Agent tool. The "sub" comes from the parent-child relationship — your main session is the parent, the spawned thread is the sub.

Three things define them:

1. Isolated context. The subagent cannot see your conversation. You brief it like a colleague who just walked into the room.
2. Parallel execution. Multiple subagents in one message run concurrently.
3. Contained output. All the subagent's reasoning happens in its context. Only the final message comes back.

That last point is the unlock most people miss. Without subagents, every "let me search the codebase" burns your main context. With subagents, you delegate the search and only see the conclusion.

When a subagent is the right tool

Parallel research. You're debugging an issue and have three hypotheses. Spawn three subagents, one per hypothesis. They run concurrently. You get three reports in the time it would take to investigate one sequentially.

Verbose work you don't need to read. Searching the codebase for every reference to getSession(). Scanning 5MB of logs for an error pattern. Scoping a 50-file refactor. The output is large but only the summary matters — subagent territory.

Independent second opinion. Your main session has been reasoning about a problem for an hour. You want a fresh perspective that didn't see your reasoning. Spawn a code-reviewer subagent — it sees the diff, not your justifications.

Building agentic workflows. Your final product is a multi-step pipeline (research → write → review). Subagents in Claude Code are the fastest way to prototype the orchestration before porting to the API.

When NOT to use a subagent

• Single step the main session can do. Read one file, run one command, grep one term. Subagent overhead isn't worth it.
• You need the result in your working tree. Subagents return a message, not file edits. Use a Skill if you need code written.
• Task depends heavily on conversation context. A subagent that doesn't know what you've been working on can't help. Brief it explicitly or skip the spawn.

How to brief a subagent

The single most important thing about subagents is the prompt. The subagent has no context. It cannot ask you questions. It cannot see your files unless told to. A vague prompt produces a vague result.

Write the brief like an email to a smart colleague who just walked in:

Audit migration 0042_user_schema.sql for safety.

Context: we're adding a NOT NULL column to a 50M-row table.
The migration backfills via a default value before flipping
NULL constraints.

Specifically check:
1. Does the backfill block writes on the table?
2. Is the constraint flip safe under concurrent inserts?
3. Is there a rollback path if step 2 fails?

Report a verdict (SAFE / NOT SAFE / NEEDS CHANGES) with
specific risks. Under 250 words.

What works:

• Goal stated up front
• Necessary context provided (the table size, what the migration does)
• Scope of investigation listed
• Output format constrained

What doesn't work:

• "Review this migration for me" — too vague, subagent has no idea what to check
• "Based on your findings, fix the issue" — pushes synthesis onto the subagent instead of you
• 30-line wall of context with no clear ask

Running subagents in parallel

The biggest leverage from subagents is parallel execution. Sequential spawning wastes the model.

Bad (sequential):
  message 1: spawn subagent A, wait for result
  message 2: spawn subagent B, wait for result
  message 3: spawn subagent C, wait for result

Good (parallel):
  message 1: spawn A, B, C in one message
  all three run concurrently
  three results return at once

If you have three independent questions, spawn three subagents in one message. They run concurrently. Your wall-clock time drops 3×.

Writing a custom Claude Code Subagent

The unlock is custom subagents — specialists you define once, summon forever.

A subagent is one Markdown file under .claude/agents/ (project-scoped) or ~/.claude/agents/ (user-scoped). Frontmatter on top, system prompt below.

---
name: dependency-auditor
description: Use this subagent to scan project dependencies for outdated packages, security vulnerabilities (CVEs), and propose prioritized updates. Supports npm, pnpm, bun, pip, cargo, and go modules.
allowed-tools: Read, Bash, Grep
---
 
You are a senior security engineer auditing project dependencies.
 
For the current repo:
1. Detect the package manager (look for package.json, pnpm-lock,
   Cargo.toml, requirements.txt, go.mod)
2. Run the native audit command (npm audit, pnpm audit, etc.)
3. Cross-check critical/high CVEs against advisory databases
4. Identify packages that are 2+ major versions behind
 
Report:
- CRITICAL CVEs (must fix now): [list with CVE ID + package + fix version]
- OUTDATED majors (worth updating): [list]
- Estimated update effort
Verdict: SAFE / NEEDS UPDATES / URGENT FIXES
 
Under 400 words.

Save it. Next time you want a security audit, ask Claude "audit my dependencies" and it routes to this subagent via the Agent tool with subagent_type: "dependency-auditor".

The description field is the routing signal. Write it as a trigger sentence ("Use this subagent when…"), not a description ("This subagent audits…"). Triggers route; descriptions don't.

Patterns that ship value

After building a stack of custom subagents, the ones that consistently get invoked share traits.

Single clear job. dependency-auditor is for deps. pricing-coach is for pricing. Avoid general-helper — no one remembers when to invoke it.

Self-contained. The subagent reads the repo, runs commands, returns a verdict. It does not depend on conversation context.

Concise output. 200-500 words of conclusions. Not a 3000-word log of the reasoning. The user wants the verdict, not the journey.

Parallel-friendly. Stateless subagents are easier to spawn 5 at a time than stateful ones. Design accordingly.

Anti-patterns to skip

Don't write a subagent for one-off work. If you'll use it once, just write the prompt inline. Subagents pay off across reuse.

Don't write subagents that wrap a single tool call. "subagent that runs npm test" is overkill — that's a Skill or just a Bash call.

Don't write subagents that require deep conversation context. They cannot have it. If the work depends on the conversation, it stays in the main session.

Don't nest subagents 3 levels deep. One level is fine. Two is rare. Three usually means the work should be restructured.

A first subagent to try

Build branch-readiness. Everyone has branches that should ship but aren't sure they're ready.

---
name: branch-readiness
description: Use this subagent to audit what's left before the current branch can ship. Checks git state, test coverage of changes, feature flag wiring, and CI-relevant file changes. Returns a punch list.
allowed-tools: Bash, Read, Grep
---
 
Audit the current branch for ship-readiness.
 
Run:
- git status (uncommitted changes)
- git log main..HEAD (changes since main)
- ls .github/workflows/ or .gitlab-ci.yml
 
For each modified file:
- Check if tests exist for it
- Check if a feature flag wraps the change
 
Report:
DONE: [list]
MISSING: [list]
RISKS: [list]
Verdict: SHIP / NOT YET / NEEDS REVIEW
 
Under 300 words.

Save it. Ask Claude "is this branch ready to ship?" and watch it audit your branch in 30 seconds.

That's the whole loop: codify a senior teammate's checklist, summon it on demand, parallelize it when needed.

Related: Claude Code Agents — how they work and when to use them · Claude Code Skills — workflows you reuse · Claude Code Plan Mode — shortcut and full guide · Claude Code MCP — connect servers and add tools