Sub-Agents

Your main session is not a dumping ground

I run 8 agents daily. That sounds like a lot until you realize the alternative: asking Claude Code to review auth changes, watching it read 15 files and write a 200-line audit, and noticing your context window is now half gone.

You needed the 5-line summary. Not the journey.

Sub-agents fix this. They're separate Claude Code instances that handle focused tasks in their own context windows. The security review happens over there. The test generation happens over there. Your main session stays clean and can keep steering.

Why this actually matters

Your context stays focused. The main session makes decisions. Agents do the deep dives. You get the result, not the noise.

Parallel execution. Code review, security scan, and test generation running at the same time, not queued up. Three expert reviews in the time of one.

Specialization that holds. Each agent carries instructions tuned for exactly one job. A code-reviewer knows your team's standards. A tdd-guide enforces test-first. Better instructions, better output, every time.

Built-in agent types

Claude Code ships with several agent patterns ready to go:

These spawn automatically when the task calls for it. You can also be explicit: "Run the code-reviewer on the files I just changed."

Building your own agents

Custom agents are markdown files in .claude/agents/. Each one defines a role, behavior, and constraints. Here's one I use constantly:

# PR Description Writer

## Role
You generate pull request descriptions from git diffs.

## Behavior
1. Read the full diff with `git diff main...HEAD`
2. Analyze each commit for its purpose
3. Group changes by category (feature, fix, refactor, test)
4. Write a structured PR description:
   - Summary (2-3 sentences)
   - Changes (bulleted by category)
   - Testing notes
   - Breaking changes (if any)

## Constraints
- Never include file paths with absolute user directories
- Keep the summary under 100 words
- Use conventional commit categories

Save it, then invoke it: "Use the PR description writer for this branch." Claude Code reads the file, follows the instructions, delivers the output. Simple as that.

When to delegate vs just do it

Not everything needs an agent. Here's the honest breakdown.

Delegate when:

• The task requires reading a ton of files (research, audits, anything that looks like exploration)
• You need the result but don't care about the intermediate steps
• Multiple tasks can run in parallel
• It's a review, scan, or verification task

Just do it directly when:

• It's a quick edit (a few lines, maybe two files)
• You need to steer every step in real time
• It's a one-off question about the codebase

The rough rule: if it takes more than a minute and you don't need to babysit it, delegate.

Parallel execution is the real unlock

For complex tasks, launch multiple agents at once:

Launch 3 agents in parallel:
1. Agent 1: Security review of the auth module
2. Agent 2: Performance audit of the database queries
3. Agent 3: Test coverage analysis for the API routes

Each works independently, uses its own context, returns a focused report. This is where sub-agents go from "nice to have" to "I can't work without this."

Things I learned the hard way

One task per agent. An agent that does code review AND writes tests is two agents crammed into one file. Split them. You'll thank yourself later.

Be specific. "Review this file for security issues" works way better than "look at the code and tell me if anything's wrong." Bounded tasks, better results.

Trust but verify. Agents are good, not perfect. Skim the output before acting on it. False positives happen. Edge cases get missed.

Start with the built-ins. Use code-reviewer and tdd-guide for a week before writing custom agents. You'll learn what you actually need, not what you think you need.

Keep agent files short. 20-40 lines is the sweet spot. If your agent file hits 200 lines, you've encoded multiple agents into one. Break it up.