Claude Code Subagents: How to Use Them Well

Most people meet subagents the same way. You spawn a reviewer, it writes three paragraphs, you skim them, you merge. It felt like a review. Nothing was actually checked, nothing blocked the merge, and nothing carried over to the next change.

The gap between that and a setup you can rely on is not more agents. It is a few structural decisions: which roles exist, what each one may touch, what shape it has to return, and which ones may run at the same time. This walks through those decisions, the two rules that matter most, and how to plug in expertise you did not write.

What Claude Code subagents actually are

A subagent is a role, not a model. It is four things: a prompt, a tool allowlist, a model tier, and its own context window. The parent gets back the child's result rather than the child's transcript.

That last part is the one people underrate. Context isolation is the whole trick. A planning agent can open forty files, chase a call chain through three layers, and burn a hundred thousand tokens doing it, and the orchestrator gets back a plan and nothing else. A clean parent window is what keeps a long session coherent instead of degrading into summarized mush around hour two.

The rest of the payoff is practical. Read-heavy work fans out. Cheap work runs on a cheaper model. Each role gets a hard boundary around what it can touch, and a reviewer that cannot write files cannot quietly fix what it was asked to judge.

None of it runs itself. Driving the loop, feeding the tools, and enforcing those boundaries is the job of the agent harness.

The Claude Code agents view: where subagents live

The usual form is one markdown file per role in the project's agents folder, listed and edited from the in-session agents view. A short frontmatter block gives the role a name, a description, and the tools it may use. The body is the prompt.

The description field does more work than it looks like. It is the routing interface: it is what the orchestrator reads when deciding whether this role fits the task in front of it. "Use for productivity tasks" routes to nothing reliably. "Use when tracing which callers break if a function signature changes" routes well. Write it for the dispatcher, not for a human browsing a list.

Start with three roles. A planner that only reads, an adversarial critic that only reads, and an implementer that writes. Add a fourth only when a stage keeps failing the same way.

Claude Code sub agents vs skills vs the harness

These three get mixed up constantly, and the distinction decides which one you reach for.

A skill is packaged instructions an agent loads into its own context. It changes what one agent knows. A sub agent is an entire delegated agent with its own context window and tool permissions. It adds a second worker to the job. The harness is the loop around both. One is knowledge, one is labor, one is the machinery. More on the first in AI agent skills, explained.

Reach for a skill when the agent needs to know something. Reach for a subagent when the work needs to happen somewhere other than your main context window.

The pipeline pattern: name the stages, fix what they return

Casual delegation gets you an opinion. A pipeline names the stages, fixes what each returns, decides which can run at once, and lets one stage's result control the next.

What turns a handful of roles into a Claude Code agents team is not the roster. It is the contract between the stages: a fixed return shape, a fixed order, and a rule about who may write.

The shape we settled on after running it daily on real changes:

Plan           explore from the root, write a plan per issue     parallel     cheaper model
Pressure-test  critics hunt logic conflicts before lock-in       parallel     frontier
Implement      implement + simplify + test                       SEQUENTIAL   frontier
Review         adversarial red-team per issue                    parallel     frontier
Fix            close every must-fix finding                      SEQUENTIAL   frontier
E2E            browser walk, desktop and mobile viewports        single       cheaper model
Learn          distill wrong-then-fixed lessons into a store     single       frontier

Nothing there is exotic and none of it needs a framework. Seven stages is what our repo needs; three is a fine place to start. What transfers is the shape.

The stage worth stealing first is the last one. Every run's plan findings, review findings, and end-to-end failures get distilled into a central store as trigger, action, reason entries. Every agent reads it before starting, and a recorded lesson overrides its default behavior. One review pass is a coin flip. A store that grows every run is the part that compounds.

Fix the model per role, not per run

Nobody picks a model at run time. The cheaper reasoning model plans and drives the browser. The frontier model implements, fixes, red-teams, and criticizes.

The rule behind it: spend the expensive model where a wrong answer ships, not where it is only a slower read. A planner that misses a caller costs one round of rework, because the next stage reads the same code anyway. A reviewer that misses a bug costs you the bug. So critics and reviewers never get the smaller model. A cheap reviewer produces a confident "looks good," which is worse than no review, because it feels like a gate and works as a rubber stamp.

Every stage returns a schema, not prose

Each stage declares a structured output shape, and those shapes are what let stages compose.

Give the review stage a must_fix boolean per finding and the fix stage can iterate exactly those findings, spawning nothing when there are none. Give the plan critic a verdict field of GO, GO-WITH-CHANGES, or NO-GO and a NO-GO aborts the run and hands the plans back before any code exists.

Prose cannot do that. "I have some concerns about the caching approach" gives an orchestrator nothing to branch on.

Running Claude Code agents in parallel: read in parallel, write in sequence

This is the rule that matters most, and it is not the one most people guess:

Parallelism is a function of write access, not of task independence.

Disjoint file lists buy you nothing. Two agents in one git worktree share one working tree, and the failure mode is not the merge conflict you are picturing. No conflict marker, no red text, no prompt. One agent's write silently wipes another's uncommitted edits, and everything downstream keeps running as if the file always looked that way.

We learned it the expensive way. One implementer ran git checkout -- to undo its own change and reverted three files belonging to an agent that had not committed yet. It rebuilt the missing code from memory, which sounds like a save and is worse: the tree then held code no plan described and no review had seen, and both agents reported success. Only re-running both agents' tests together caught it.

Two fixes came out of that, both still in force. Implementers run one at a time. And every agent sharing a tree gets this as a hard constraint in its prompt:

Do NOT run git checkout / reset / restore / stash / clean / commit.
They wipe sibling agents' uncommitted edits in this shared worktree.
EDIT FILES ONLY. The main session commits later.

Agents edit files. The orchestrator commits. That split is what stands between you and a silent revert.

The happy half: planning, criticism, and review are read-only, so they fan out freely and finish in the time of their slowest member. If you want genuinely parallel writes, give each agent its own worktree and merge afterward. Anything less is a race you will not see fail.

Barriers belong where a stage compares work

One scheduling detail worth copying. The plan stage fans out, and the critics do not start until every plan exists.

That barrier is not politeness. Cross-issue conflicts are only visible when all the plans are in hand: one plan's fix regressing another's invariant, a contract change landing on a consumer no plan mentions, two plans claiming the same migration number. A critic holding one plan cannot see any of it.

Review needs no barrier, because each reviewer looks at one finished change against the code as it stands. Barriers belong wherever a stage's job is to compare, and nowhere else.

Critics read plans, reviewers read diffs

The highest-value stage turned out to be one of the cheapest: an adversarial critic that attacks the plan before any code exists.

A recent example. A forgot-password endpoint must not reveal whether an account exists. The plan handled it the obvious way: return the same response for every input, and send the reset email inline. Same status, same body, registered or not. Every test anyone would write agreed it was safe.

The critic's finding was that the bodies were identical and the code paths were not. A registered address paid for a lookup, a token write, and a live mail round trip. An unregistered one returned immediately. Identical bytes, different latency, still an enumeration oracle and trivially measurable from outside. The fix was to move the whole branch into a background task so every input returns in the same few milliseconds.

No assertion on status code or response body catches that, so a green suite would have sat right on top of the hole. A critic reading a plan caught what a reviewer reading a diff would probably have missed, because the diff would have looked exactly the way the plan said it should.

How to use agents in Claude Code: a starter recipe

Six moves, in the order we would add them again:

1. Start with three roles, not twelve. Planner, critic, implementer. Add a role only when a stage repeatedly fails the same way.
2. Split read from write. Any role that only reads can fan out. Any role that writes runs alone, or gets its own worktree.
3. Make every role return a fixed shape. Even hand-run, "verdict plus findings, each with must-fix true or false" turns an opinion into a gate.
4. Pin the model per role. Critics and implementers get the best model available, always. Explorers can be cheaper.
5. Give the critic the whole plan set. Conflicts live between plans, and a critic that sees one plan cannot find them.
6. Write findings somewhere durable. A folder of trigger, action, reason notes that every agent reads at task start is the cheapest quality mechanism you have, and the only one that improves on its own.

Two gotchas that cost us real time

Orchestration arguments are typed even when they look like text. Ours takes a touchpoints argument that must be a JSON array. Pass a delimited string and the run dies with touchpoints.map is not a function before a single agent spawns. Validate orchestration inputs like an API boundary, because that is what they are.

Never trust an agent's final message. Verify against repo state instead: check git status, grep for the change's markers, run the tests together rather than per agent. A subagent that stopped early still sounds confident.

When this is worth it, and when it is absurd

A full pipeline of max-effort agents is slow and expensive, and you pay for every stage.

It earns that on security-adjacent changes, on contract or schema changes with consumers on both sides of the wire, on migrations, and on anything where the wrong design is expensive to unwind. The timing catch above paid for its run several times over.

It is absurd on a typo, a copy tweak, or a one-file refactor with one caller. Running a plan critic on a string change is theater, and doing it anyway is actively harmful, because it trains you to ignore the pipeline on the day it matters.

Plugging in expertise you did not write

Every role above is one you define and maintain. That is right for a planner or a reviewer: you want those legible, versioned, and editable by whoever comes next.

But some work needs expertise that is not in your repo and never will be. A consultant's audit method. A firm's private playbook. A curated document set that took years to build and thirty seconds to copy. The moment those instructions land on someone else's machine they are theirs, which is the threat model in agentic AI skill security.

A sealed Expert is the shape that fits that gap. It holds many skills, documents, and tools at once, it runs server-side, and the caller gets the answer rather than the instructions. From your pipeline's point of view it is one more entry in the tool list, and it drops into a stage exactly where a local subagent would.

It goes wherever your agent already looks

The integration surface is deliberately boring, because a tool nobody can wire up is not a tool.

Over MCP, an Expert appears as ordinary tools any MCP-capable client can call: consult_expert to start, get_result to poll, reply_to_expert when the Expert needs something back from you, plus discovery, cancellation, and artifact fetch. No custom adapter, no SDK.

For harnesses that load instructions from disk instead of speaking MCP, the CLI writes the adapter. askpert add <expert-id> currently targets 72 coding agents and harnesses, Claude Code and Codex and Cursor and Gemini CLI and Copilot and Zed and Cline and Windsurf and Goose and OpenCode among them. Nineteen of those already share the emerging .agents/skills convention, so one generated artifact serves all nineteen at once. Anything not on the list calls the REST endpoints directly.

The detail that makes it composable is the continuation loop. A consult returns a ticket rather than holding a connection, so a slow Expert never blocks your pipeline. Your orchestrator polls when it wants to. If the Expert needs an input it does not have, it says so and waits, which means it can sit inside a fan-out stage beside your own subagents and be cancelled like any other job.

The practical upshot is that adding one is not an integration project. The config governing this repo's own sessions wires two rented Experts next to the local roles, one that audits a domain's SEO and one that helps build a skill. Neither needed a line of glue code. Buyer-side wiring is in the docs, and you can browse the Experts other agents are calling.

Claude Code subagents FAQ

Package the expertise you cannot publish

If you recognized your own playbook a few sections up, the packaging problem is already solved. Put your knowledge, prompts, documents, and tools into a protected Expert, and other people's agents call it over MCP or REST while your files never leave the server.

Create an Expert and see what it is worth to somebody else's pipeline.