Giving Claude a team

A flaky test can send an assistant through logs, fixtures, and several source files before a two-sentence explanation emerges. The explanation is useful. Keeping every abandoned theory in the main conversation is less useful when the next step is a small fix.

Claude Code subagents give that investigation a separate working space. A helper can explore one question and bring back a result, while the main conversation stays focused on the decision. The useful skill is learning what to delegate and what the returned answer needs to contain.

An investigation leaves a paper trail

Imagine a parser test that fails only on empty input. An investigation might inspect a fixture, search for the parser's callers, and compare several test runs. In a single conversation, that evidence and the intermediate discussion can accumulate alongside the actual implementation task.

Some of the material deserves to stay: the input that reproduces the failure, the relevant function, and the expected behavior. Much of it can remain in the investigation's notebook. Delegation creates a place to do that sorting.

return values[0];

parse(values)

What the helper actually receives

A subagent has a context window and instructions for its task, with access to the tools its configuration permits. In the ordinary fresh-context pattern, Claude supplies a delegation prompt rather than handing over the entire conversation. The subagent documentation explains the available modes and configuration.

This is context isolation, not a guarantee that the answer is correct. A helper can misunderstand an input just as the main assistant can. A good result includes the relevant file locations, a reproduction or supporting observation, and a distinction between established findings and guesses.

The full investigation also costs tokens. Returning a short report can reduce what the parent carries into later work; it doesn't erase the cost of the helper's reading and reasoning.

Start with the helpers already available

Claude Code provides built-in agents for common kinds of work. Explore is suited to searching and understanding a codebase. Plan gathers information for an implementation approach. A general-purpose agent can handle work requiring a broader tool set.

Choose by the job. “Find where this value enters the parser” is an exploration task. “Compare two fixes against these constraints” needs a more explicit analysis brief. “Implement the chosen change” needs permission to edit and a clear ownership boundary.

A subagent that reports to the main conversation is different from an agent-team teammate that coordinates with other teammates. Extra participants add coordination work. Start with a helper when one well-defined question will unblock the task.

Write a job description with limits

A project-specific agent lives in .claude/agents/. A personal agent can live in ~/.claude/agents/. Save this example as .claude/agents/parser-reviewer.md:

---
name: parser-reviewer
description: Review parser changes for edge cases and public API regressions
tools: Read, Grep, Glob
model: inherit
---
Review the supplied change without editing files.
Check empty input, malformed input, and API compatibility.
Return findings with file locations and supporting evidence.
State what you could not verify.

The description helps Claude decide when the agent is relevant. The body supplies the working brief. The tool list gives this reviewer a narrow surface: it can inspect files and search, but it doesn't have an editing tool or shell access.

A configuration named “read-only” that includes unrestricted Bash deserves closer inspection. A shell can modify files even when Write and Edit are absent. Match the actual tools and permission settings to the intended job; the label alone provides no boundary.

Put the important constraint in the brief

“Review the parser” leaves a lot open. The helper needs to know which change, which behavior matters, and whether an API decision has already been made. A concrete request is easier to complete:

Use the parser-reviewer subagent to inspect the current parser diff. The public API must remain unchanged. Check the empty-input fixture and report correctness concerns with file locations. Do not edit files.

The main assistant still has to connect the report to the wider task. If the helper cannot run tests, a report based on inspection should say so. “No issue found” and “the tests pass” are different observations.

Separate files as well as conversations

Separate context windows don't automatically mean separate files. Two editing agents in the same checkout can overwrite each other's work. Give independent changes separate ownership, or use a supported worktree mode when each task needs its own checkout.

isolation: worktree

Add that field to an editing agent's frontmatter when worktree isolation is appropriate. A Git worktree has its own working directory, so the helper can make a change without modifying the parent's files directly. Claude Code can clean up an unchanged temporary worktree; a changed one needs its result inspected and integrated.

Worktrees prevent direct file collisions. They don't prevent incompatible design decisions or merge conflicts. Two changes to the same interface still need someone to reconcile the resulting behavior.

Both branches begin with shared history, but their working directories hold independent changes. The parser edit and its test can develop separately. Before combining them, check that the test expects the same behaviour the implementation provides.

Delegate a result you can check

Good candidates include a search across many files, a focused review, and independent investigations of different failure theories. A tiny lookup or a conversation depending on many unrecorded decisions may be easier to handle in the main thread.

Keep the brief proportional to the task. Include a question, relevant constraints, the expected output, and the tools or files the helper owns. Ask for enough evidence to check the conclusion, without requesting a replay of every intermediate step.

A smaller parent context still has a price

Delegation adds startup instructions, another investigation, and a report. Parallel execution can shorten elapsed time while increasing total usage. A less expensive model may be suitable for a straightforward search, but the required accuracy still matters more than the model label.

Watch what the helper returns. A ten-page summary can bring much of the reading burden straight back into the parent. A useful report might be a finding, two supporting locations, and an unresolved question. Exact savings depend on the task and configuration.

Give the team a job, not just a headcount

Start with one question that can be answered independently. Supply the constraint, let a helper investigate, and check the evidence it returns. Add a separate checkout when the work includes edits that need isolation.

The payoff is a clearer main conversation with a better next decision. More agents become useful when the task has meaningful boundaries. For the rest of the session, the same habit carries into keeping context focused: bring forward what the work needs, and leave the investigation's scaffolding where it belongs.