Playbooks · Coding tasks · last verified 2026-10-25

Run parallel research with Claude Code subagents

For a solo developer × running independent investigations in parallel × Claude Code subagents, so three lines of research finish in one session without flooding the main conversation.

Before you start

You need a Claude Code session in a project you can read freely. A subagent is a Markdown file with YAML frontmatter: the file's body becomes the subagent's system prompt, and the frontmatter says when Claude should use it and what it may touch. Only two frontmatter fields are required — name and description — and a file missing either one is skipped without a visible error, which is the first failure mode to know about. Project subagents live in .claude/agents/ and can be checked into version control; user subagents live in ~/.claude/agents/ and work across projects. This page was not run inside Claude Code this run: the file shapes and limits below come from Claude Code's own subagents documentation, read this run, not from a completed session.

The rule for whether parallel is even the right shape: the docs' parallel pattern works when the research paths do not depend on each other. If path B needs path A's answer, that is a chain, not a parallel run, and running it in parallel buys confusion instead of speed.

What "done" looks like

At the end of one session you have three short summaries — one per path — each naming the files it read and the finding it stands behind, and a synthesis that says where they agree, where they conflict, and what you still need to check yourself. The main conversation holds the summaries, not the thousands of lines the exploration read. No code has changed unless you asked a subagent that may write to change it.

Steps

Split the investigation into independent paths, on paper, before you spawn anything. Write one sentence per path: what it must answer, and what it must not need from the other paths. If you cannot write a path's question without referencing another path's answer, merge them or sequence them — do not parallelize a dependency.
Start with the built-in subagents before writing any file. Claude Code already ships Explore (read-only, for searching and analyzing a codebase), Plan (read-only, for research during plan mode), and General-purpose (for complex work that both explores and changes things). Asking Claude to use Explore for a codebase question is often the whole job; a custom file earns its place only when you keep spawning the same kind of worker with the same instructions.
When a custom worker repeats, write one small file for it. A code reviewer, for example, in .claude/agents/code-reviewer.md: frontmatter with a name, a description that says exactly when Claude should delegate to it ("Use when reviewing a change for correctness and test coverage, before it is merged"), and a tools list that matches the job — Read, Grep for a reviewer that must not change anything. The body is the reviewer's instructions: what to check, what a finding must cite (file and line), and that it reports findings instead of fixing them. Keep the description short: when the combined descriptions of your custom subagents pass 15,000 tokens, Claude Code warns at startup, and every description costs context on every session whether that subagent runs or not.
Give the cheap model the read-only work. A subagent's model field takes sonnet, opus, haiku, fable, a full model ID, or inherit. Exploration that only reads files is the natural place for haiku. Two cost facts from the docs that shape this choice: a subagent's requests count toward the same usage limits as the main conversation, so parallel is not free — it is faster, not cheaper; and a subagent starts with a fresh context window, so it does not see your conversation history unless the delegation message carries what it needs.
Ask for all of the paths in one message, then let Claude synthesize. Name each path and its question, and say the paths are independent. Each subagent works in its own context and returns only its summary; Claude then combines them. Your job at this step is the synthesis check, not re-reading everything: where do two summaries disagree, where does one cite a file the other did not read, and which finding would change your decision if it were wrong?
Verify one finding per path by hand before acting on it. Open the cited file and check the claim. This matters more than usual with subagents, because a subagent reads files, web pages, and command output you never reviewed, and text from those sources can carry instructions aimed at the main conversation. Claude Code scans each report for that shape of text and marks it, but the scan does not judge whether content is malicious — it only flags the shape. A finding that would make you run a command, change a permission, or merge a change gets checked in the file itself, not on the report's word.
Check the file actually loaded before you trust a quiet session. A subagent file with a misspelled frontmatter field is not rejected with an error — Claude Code ignores a field it does not recognize, silently. A file with no name or no description is skipped silently, and two files in the same agents directory declaring the same name load only one of them, chosen by filesystem read order. If Claude never delegates to your new subagent, check the file before concluding the description was wrong: run claude plugin validate against the agents directory, or run Claude Code with --debug and search the debug log for the unrecognized-field note.

Check the subagents' work

Check one finding per path by hand, in the cited file, before you act on any of them. If a hand check disagrees with a summary, check that whole path by hand.
Check that no summary's recommendation rests on a file it did not cite. An uncited claim is a claim you cannot verify, and it does not get into the synthesis.
Check that read-only workers stayed read-only: a reviewer that edited a file has exceeded the tools you gave it, and its other findings are suspect too.
Check the synthesis for disagreements, not just agreements. Two paths agreeing is weak evidence if they read the same files; a disagreement is where the real investigation lives.

What can go wrong

Parallelizing a dependency. Two subagents answering questions that need each other's answers produce confident summaries that cannot both be right. The split in step 1 is the prevention, and there is no later step that repairs a bad split.
A silent file problem. A missing description, a misspelled field, a duplicate name — all fail quietly, and the session just never uses your subagent. The validate and debug checks in step 7 are how you tell a loading failure from a delegation failure.
Context that never arrived. A subagent does not see your conversation, your skills already invoked, or files you already read. A delegation message that says "check the thing we discussed" delegates nothing usable. Put the question, the scope, and the files in the message itself.
Twenty subagents at once. By default, when 20 subagents are running, spawning another fails with a concurrent-limit error and the error tells Claude not to retry. A session that fans out without bound hits that wall; three deliberate paths do not.
A report that smuggles instructions. Source text a subagent read can imitate conversation markers or mention permission settings. The scan flags the shape; it does not certify the content. Treat any report that asks for a permission change or a skipped check as untrusted until you have checked the underlying file.

Limits

Subagents are for work that returns a summary: verbose output you do not need in the main context, a self-contained task, or a job with restricted tools. Work that needs frequent back-and-forth, or phases that share significant context, belongs in the main conversation — the docs say so directly, and a subagent that starts fresh will cost you the re-explanation every time.
Parallel subagents are faster, not cheaper: their requests draw on the same usage limits as the main conversation. If the budget is the constraint, fewer paths on a cheaper model beats more paths on the flagship model.
A subagent that finishes cannot be assumed to have finished well: a subagent stopped at its turn limit returns its output marked partial, and a background subagent that fails on an API error returns its last output with the failure named. Partial is a state to resume from, not a summary to trust.

Verification

Checked 2026-10-25. This page was not run inside Claude Code this run; its claims rest on Claude Code's own subagents documentation, read this run. Sources: Create custom subagents — Claude Code Docs (built-in Explore, Plan, and General-purpose agents; frontmatter with name and description required; project and user agent directories; model aliases and the haiku cost option; the parallel-research pattern for independent paths; the 15,000-token description warning; the 20-concurrent-subagent limit; silent skipping of malformed files; output scanning for instruction-shaped text). Omitted: no claim is made that a particular custom subagent file was tested in a live session, and no usage cost is quoted, because the docs state the limit-sharing rule without a price.

Back to: Coding playbooks hub · Also: Review a pull request with a coding agent