There’s a specific kind of frustration that hits somewhere around session hour two. You’re deep into a feature, the context window is bloated with half-explored tangents, and Claude starts giving you slightly off answers – not wrong exactly, just… drifting. Responses slow down. The model loses the thread.
I’ve been there more times than I’d like to admit. And for a long time, my fix was just to start a new session and re-explain everything. That works, but it’s a band-aid.
Subagents are the actual fix.
What a Subagent Actually Is
Here’s the one sentence version: a subagent is a separate Claude instance with its own clean context window that does a specific job and hands you back only the result.
The longer version matters more for understanding when to use them.
When Claude Code spawns a subagent, that agent starts completely fresh. No conversation history, no accumulated context, no half-remembered decisions from forty minutes ago. It gets a task, works independently – reading files, exploring code, running checks – and returns a summary to your main session. Not the raw output. The summary.
Your main session never sees the noise. It just gets the answer.
Multiple subagents can run at the same time. Each one can have different tool permissions – a research agent might be read-only while an implementation agent has full edit and bash access. And when they’re done, they’re gone. No residue.
Claude Code ships with a few built-in types: general-purpose agents for complex multi-step tasks, plan agents that scan codebases before proposing implementation strategies, and explore agents for fast read-only code search. You can also define your own.
The Problem They Actually Solve
Context window bloat is the quiet performance killer in long Claude Code sessions. Every file you open, every direction you explore and abandon, every clarification you ask for – it all stays in memory. Token costs compound. Response quality gradually degrades. The model starts making mistakes it wouldn’t have made at the top of the session.
The standard advice is to keep sessions short and focused. That’s good advice. It’s also impractical when you’re building something real.
Subagents give you a different option. Instead of cramming exploratory work into your main session, you delegate it. The subagent does the exploration, absorbs all the verbose output, and returns what matters. Your main context stays clean.
This becomes especially valuable when you’re working in a large codebase – a TypeScript monorepo, a microservices backend, anything where understanding one corner of the system requires reading a dozen files that have nothing to do with what you’re actually building.
When Delegation Is Worth It
The overhead of spawning a subagent is real. It costs tokens. It adds a layer of indirection. For simple tasks, it’s not worth it. But for certain categories of work, the tradeoff is clearly in your favor.
Research-heavy exploration. You need to understand how the existing auth service handles token expiry before you touch it. Delegate it, get back a synthesized summary, and start from clarity rather than noise.
Independent parallel tasks. You need to update the same error handling pattern across six files. Those files don’t depend on each other. Three subagents working simultaneously finish faster than one working sequentially.
Unbiased verification. You’ve been inside an implementation for an hour. A fresh subagent with read-only access reviews what’s actually there – not what you think is there.
Multi-stage pipelines. Design phase, implementation phase, test phase. When stages have clear handoffs and each benefits from focused context, chaining subagents produces cleaner results than doing everything in one conversation.
Rule of thumb: If gathering the context for a task requires reading ten or more files, or if you have three or more independent pieces of work – that’s a signal to delegate.
When to Skip Them
Sequential dependent work. If step two genuinely needs the full output of step one, a relay of subagents passing state through files is usually more friction than just doing it in one session.
Same-file edits. Two subagents editing the same file in parallel is a conflict waiting to happen. Keep tightly coupled changes in one context.
Small quick tasks. A focused question, a one-line fix, a fast lookup – delegation overhead isn’t worth it. Just ask.
Too many custom agents. Claude’s automatic delegation gets less reliable when choosing from a sprawling list. A handful of well-scoped agents outperforms a roster of twenty vague ones.
Tasks that need agents to coordinate. Subagents can’t talk to each other. For that you need agent teams – heavier, more expensive, but necessary for certain architectures.
How to Invoke Subagents
Just Ask
The simplest approach is conversational. Claude Code understands natural language across every interface – terminal, VS Code, JetBrains, desktop, web. Natural language that works reliably:
- “Use a subagent to explore how authentication works in this codebase”
- “Spin up parallel subagents to fix these TypeScript errors across the different packages”
- “Have a separate agent review this implementation – don’t give it our conversation history”
Being explicit makes a difference. Define scope, name the output format, say when tasks can run in parallel. Here’s a prompt structure that works well:
Use subagents to explore this codebase in parallel:
1. Find all API endpoints and summarize their purposes
2. Identify the database schema and relationships
3. Map out the authentication flow
Return a summary of each – not the full file contents.
If a subagent is running long and you want to keep working, Ctrl+B sends it to the background. Results surface automatically when it finishes. /tasks shows what’s running.
Custom Subagents
When you find yourself requesting the same kind of agent repeatedly – a security reviewer before every commit, a docs proofreader for every new guide – define it once as a custom subagent.
Custom subagents live as Markdown files in .claude/agents/ for project-level agents (shared with the team) or ~/.claude/agents/ for user-level agents. The /agents command walks you through setup interactively.
Here’s a real example:
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
injection risks, auth issues, and sensitive data exposure.
Use proactively before commits touching auth, payments, or user data.
tools: Read, Grep, Glob
model: sonnet
—You are a security-focused code reviewer. When invoked, analyze the
provided changes for:
– SQL injection, XSS, and command injection risks
– Authentication and authorization gaps
– Sensitive data in logs, errors, or responses
– Insecure dependencies or configurations
Return a prioritized list of findings with file:line references and a
concrete recommendation for each. Be critical. If you find nothing,
say so explicitly – do not invent issues to seem thorough.
The description field is what Claude uses to decide when to delegate automatically. “Reviews code for security issues before commits touching auth or payments” routes far more reliably than “security expert.” Be specific about trigger conditions, not just capabilities.
The tools field matters for predictability. A read-only reviewer has no business with Write or Bash access. Restricting tools keeps behavior contained and makes the agent easier to trust.
The last line – “do not invent issues to seem thorough” – is doing real work. LLMs default to agreeable, which in a security reviewer means flagging things that aren’t problems. Explicitly override that tendency.
CLAUDE.md for Team-Wide Policies
Custom subagents define who the specialists are. CLAUDE.md defines the rules for when to reach for them. Claude reads it at the start of every conversation, so behavior stays consistent across sessions and teammates – without anyone needing to remember to ask.
## Code review standards
When asked to review code, ALWAYS use a subagent with READ-ONLY access
(Glob, Grep, Read only). The review must check for:
– Security vulnerabilities
– Performance issues
– Adherence to patterns in /docs/architecture.md
Return findings as a prioritized list with file:line references.
This eliminates the cognitive overhead of remembering which pattern to use when. The rule is encoded in the project, not in your head.
Skills for Repeatable Complex Workflows
For multi-step workflows you run regularly, skills let you define the whole thing once and trigger it with a slash command.
name: deep-review
description: Comprehensive code review that checks security, performance,
and style in parallel. Use when reviewing staged changes before a commit or PR.
—Run three parallel subagent reviews on the staged changes:
1. Security review – check for vulnerabilities, injection risks,
authentication issues, and sensitive data exposure
2. Performance review – check for N+1 queries, unnecessary iterations,
memory leaks, and blocking operations
3. Style review – check for consistency with project patterns
in /docs/style-guide.md
Synthesize findings into a single priority-ranked summary. Each issue
should include file, line number, and recommended fix.
/deep-review runs all three in parallel and returns one consolidated report. The kind of review that used to take fifteen minutes of back-and-forth now takes a single command.
Skills differ from CLAUDE.md in a key way: CLAUDE.md is always loaded and shapes every interaction. A skill loads on demand. That makes skills the right home for workflows that should be available, but not applied to every prompt.
Hooks for Automation
Hooks are shell commands or scripts that fire automatically at specific points in Claude Code’s lifecycle. The most useful pattern: a Stop hook that runs checks before Claude ends its turn.
“hooks”: {
“Stop”: [
{
“hooks”: [
{
“type”: “command”,
“command”: “\”$CLAUDE_PROJECT_DIR\”/.claude/hooks/check-tests.sh”
}
]
}
]
}
}
When Claude finishes its turn, the Stop event fires. The script runs the test suite. If tests fail, it returns decision: "block" and a reason – Claude Code feeds that back as an instruction to keep working. Tests pass, Claude exits normally.
Start with conversational invocation. Let patterns emerge. Build automation around the ones that stick.
Four Patterns That Actually Work
01 – Research Before Implementing
Before you touch unfamiliar code, delegate the exploration.
– How are emails currently sent in this codebase?
– What notification patterns already exist?
– Where should new notification logic live based on current architecture?Summarize findings, then we’ll plan the implementation.
You start implementation from a solid foundation instead of discovering things mid-build.
02 – Parallel Modifications
Same pattern across multiple independent files.
– src/api/users.ts
– src/api/orders.ts
– src/api/products.tsFollow the pattern in src/api/auth.ts. Work on all three simultaneously.
Three files, roughly the time of one.
03 – Independent Review
Fresh eyes on your own work.
implementation. Do not give it our previous conversation. I want
an unbiased review – security vulnerabilities, unhandled edge cases,
error handling gaps. Be critical.
The reviewer evaluates what exists, not the story you’ve been telling yourself about it.
04 – Pipeline Workflow
Multi-stage tasks with clean handoffs.
Build this feature as a pipeline:
1. First subagent: Design the API contract, write it to docs/api-spec.md
2. Second subagent: Implement the endpoints based on that spec
3. Third subagent: Write integration tests for the implementation
Each stage completes before the next begins.
Design doesn’t bleed into implementation. Testing evaluates the result independently. Each stage gets exactly the context it needs.
Start Conversational, Automate Later
The biggest mistake I see people make with subagents is trying to build the whole system upfront. They define fifteen custom agents before they’ve figured out which three they actually need.
Start with conversation. Ask Claude to use subagents for specific tasks. Notice which requests keep recurring. Build automation – custom agents, CLAUDE.md policies, skills – once you understand which patterns are actually worth encoding.
The goal isn’t to have a sophisticated subagent architecture. The goal is to stay in flow longer, catch more issues earlier, and not have to start over every time a session gets heavy. Subagents are a tool for that. Use them when they help, skip them when they don’t.