What Claude Code Subagents Actually Are
Claude code subagents are separate agents your main Claude Code session launches to handle a specific task on their own. Each one gets its own instructions and its own working context, does the job you handed it, and reports a single result back to the main session. The main session stays in charge - it decides what to delegate, reads what comes back, and stitches the results together. Think of it as Claude hiring short-term help for the parts of a job that can happen at the same time.
The reason this matters is that most builds have independent parts hiding inside them. Researching which of three libraries to use does not depend on writing your test suite. Migrating file four does not depend on migrating file seven. When those parts run one after another in a single thread, you wait through all of them in sequence. When they run as subagents, they happen in parallel and you wait once.
When to Use Subagents - and When Not To
Use subagents when the work splits into parts that do not depend on each other. That is the entire test. If two tasks can be done by two different people in two different rooms without either one asking the other a question, they are subagent candidates.
- Good fit: researching several options at once - one agent per library, framework, or API, each reporting back a short recommendation.
- Good fit: bulk edits across many independent files - a migration, a rename, applying the same pattern to ten routes.
- Good fit: parallel tracks of one project - one agent writes tests while another writes documentation while a third audits for a specific bug class.
- Bad fit: a single tightly coupled change where step two needs the exact output of step one. Splitting that across agents just adds coordination overhead.
- Bad fit: anything where you cannot clearly say what 'done' looks like for each piece. If you cannot write the brief, you cannot delegate it yet.
The Delegate-Verify Loop - My Method for Running Subagents
The Delegate-Verify loop is the three-step routine I run every time I use subagents: split, brief, verify. It exists because parallel work fails in a specific way - the agents each do something reasonable, but the pieces do not fit, and you find out at the end when it is expensive to fix. The loop front-loads the thinking so the merge is boring.
- Split: break the work into tasks that are genuinely independent. Write each one as a sentence starting with a verb - 'migrate the auth routes', 'write tests for the parser', 'research the three queue libraries'. If two sentences reference each other, they are not split yet.
- Brief: give each subagent everything it needs and nothing it does not. The exact files to touch, the conventions to follow, the definition of done, and what to leave alone. A subagent cannot ask a clarifying question the way you would in chat, so the brief has to stand on its own.
- Verify: read every result before you accept it. Do not merge on trust because the summary sounds confident. Check the actual diff, run the tests, confirm the agent stayed inside its lane. This is the step people skip and the step that earns all the speed.
A Real Build: Ten Files in an Hour Instead of an Afternoon
I had a client migration - ten route files that all needed the same change to how they handled a shared response format. Done one at a time in a single session, it is a slow afternoon of the same mechanical edit repeated, with attention drifting by file six. The files did not depend on each other, which is exactly the signal to parallelize.
I split it into per-file tasks, wrote one brief that named the shared pattern and the two things to never change, and let subagents run the edits in parallel while I watched. Then I ran the verify step properly: I read all ten diffs and ran the test suite before accepting anything. Two files needed a small correction the agents had handled slightly differently - caught in five minutes because I checked instead of trusting. The whole job closed inside an hour. The speed came from the parallelism; the correctness came from not skipping verify.
Sequential vs Delegate-Verify on the same ten-file migration
| Approach | What It Feels Like |
|---|---|
| One agent, file by file | A long afternoon of the same edit; attention drifts; small inconsistencies slip in unnoticed |
| Subagents with no verify | Fast, but the inconsistencies ship because nobody read the diffs |
| Delegate-Verify loop | Parallel edits plus a deliberate review pass - fast and correct, because the merge is where you look hardest |
How to Keep Control While Agents Run in Parallel
Control does not come from watching every keystroke - it comes from the shape of the work you hand out. Three habits keep a parallel run from drifting.
- Give each subagent a narrow lane and say what is out of bounds. 'Only touch files in /routes/auth. Do not change the shared types.' Boundaries prevent two agents from editing the same thing.
- Ask for a small, checkable result, not a vague report. 'Return the diff and the test output' beats 'let me know how it went.'
- Always run the verify step yourself. The subagents are fast; your judgment on whether the result is right is the part that does not parallelize.
Start Small: Your First Subagent Run
Pick a job you already understand that has an obvious split - a small migration, a research question with three options, or tests-plus-docs on a feature you just built. Write the tasks as verb-first sentences, brief each one completely, let them run, and then read every result before you accept it. Do that once on real work and the pattern clicks: delegate the independent parts, verify the merge, keep the speed without the mess.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What are subagents in Claude Code?
Subagents are separate agents your main Claude Code session launches to each handle a single task on their own and run in parallel. Each gets its own brief and working context, does the job, and reports one result back to the main session, which stays in charge of what to delegate and how to merge the results. They are useful when a build has parts that do not depend on each other.
When should I use Claude Code subagents?
Use them when the work splits into genuinely independent tasks - researching several options at once, applying the same change across many files, or running parallel tracks like tests and docs at the same time. Avoid them for a single tightly coupled change where each step needs the exact output of the last, because the coordination cost outweighs the parallel speed.
How do I stop subagents from making a mess?
Run the Delegate-Verify loop: split the work into independent tasks, brief each subagent completely including what is out of bounds, and verify every result before you merge it. Put your project conventions in CLAUDE.md so every subagent inherits the same rules. The verify step - reading the actual diffs and running the tests instead of trusting the summary - is what keeps parallel speed from turning into parallel chaos.
Do subagents read my CLAUDE.md file?
Yes. When Claude Code spins up subagents, each one reads the project's CLAUDE.md, so your folder conventions, naming rules, and always/never guardrails propagate to every agent automatically. You brief the shared rules once in the file rather than repeating them in every task.
Last reviewed by David Iya on July 26, 2026
