Claude Code subagents are a context tool

A subagent runs in its own context window and reports back a summary. That is the mechanism, and everything useful follows from it. The parent conversation never sees the forty files the subagent read. It sees the conclusion.

The popular framing is a team of specialists: a security agent, a testing agent, a docs agent. That framing produces disappointment, because the "specialist" is the same model with a different system prompt. It is not more capable at security. It just has an empty context and a narrow instruction.

Which is still valuable. An empty context and a narrow instruction is often exactly what a task needs.

When Claude Code subagents pay off

The pattern is: the work produces far more intermediate output than final answer.

• "Where in this repo do we handle refund idempotency?" The search reads thirty files. You want one paragraph back.
• Reviewing a diff against a checklist, where the review reasoning is long and the verdict is short.
• Running an exploratory build or test sweep whose logs are enormous and whose signal is one failing case.
• Two genuinely independent pieces of work you want running at once, like a frontend change and an unrelated migration.

The parallel case has a hard constraint most people learn the expensive way: the tasks must not touch the same files. Two subagents editing the same module produce a mess neither of them understands, and you get to untangle it.

When they make things worse

Anything requiring back-and-forth. A subagent cannot ask you a question mid-task in any useful way. If the work needs three clarifications, delegating it means three wrong guesses instead.

Anything where the detail is the point. If you delegate "figure out why this test is flaky", you get a summary saying it is a timing issue, and the specific stack trace you needed is gone with the context that held it.

And small tasks. Spinning up a subagent to read one known file is slower and costs more than reading it. We watch engineers in workshops delegate reflexively for the first hour, then stop, because the round trip is noticeable.

Writing one that behaves

Two things determine quality: the description, which decides when it fires, and the tool list, which decides what it can do.

Make the description name real triggers, not a job title. "Use when the user asks where something is implemented, or needs a codebase-wide search across naming conventions" beats "code exploration expert".

Then restrict tools. A research subagent should not have write access. If it only reads, it cannot half-edit a file and leave you with a partial change nobody asked for. Give it read, search, and shell, and nothing else.

Finally, tell it what to return. Subagent output tends toward a wall of prose unless you specify the shape: Return the file path, the function name, and one sentence on how it works. No code blocks. Specifying the return format is the line that changes subagent output most.

What to do next

Look back at your last long session and find the point where the agent started forgetting earlier instructions. Scroll up. Whatever dumped a huge pile of output just before that is your first subagent candidate. Write one for exactly that job, restrict it to read-only tools, specify the return format in one sentence, and use it for a week before writing a second.

If you want help putting this into practice, talk to us.