Claude Code Subagents Guide: Delegate Without Drift

Why delegation without a contract produces drift

A Claude Code subagent is a separate agent the main session can hand a task to. It runs with its own context window, its own system prompt, and its own tool access, does the work, and returns a result the parent session reads. The appeal is that it isolates a job. A research task, a code review, a focused refactor, each runs in a fresh context that does not pollute the main thread and does not get polluted by it. The risk is that a subagent invoked without a clear contract is a delegation into a black box, and the black box drifts.

A subagent spun up with a one-line instruction and the parent's full tool set behaves unpredictably. It interprets the vague brief loosely, wanders into work nobody asked for, edits files it should only have read, and returns prose the parent cannot parse into a next action. Because it runs in an isolated context, the parent cannot see what it did until it finishes, and by then the drift has happened. The session that delegated a focused task gets back a sprawling, half-relevant result and has to redo the work it tried to offload. Delegation that should have saved effort costs more than doing the job inline.

This guide covers the subagent configuration that makes delegation reliable: the agent file anatomy that defines a clear job, the scoped tool list that limits what the agent can touch, the mandatory reads that give it the context it needs, the output contract that lets the parent consume the result, and the failure modes a well-built agent guards against. For the resource isolation that makes subagents worth using at all, Claude Code context window management covers why a fresh context is the point. For running several at once, Claude Code parallel agents covers fan-out coordination.

The subagent file anatomy

A subagent is defined by a Markdown file with frontmatter that declares its identity and a body that defines its behaviour. The frontmatter carries the name, the description that decides when the agent is invoked, and the tools it may use. The body carries the system prompt: the agent's intent, what it must read, how it operates, and what it returns.

---
name: code-reviewer
description: Reviews a diff for correctness bugs and security issues. Invoke after a change is written, before it ships.
tools: Read, Grep, Bash
---

You are a code reviewer. Your single job is to review the changes in the
current diff and report bugs, security issues, and risky patterns. You do
not fix anything. You report.

## Mandatory reads
- The project CLAUDE.md for the rules the code must follow
- The diff under review (git diff or the files named by the caller)

## Operating procedure
1. Read the diff in full before commenting on any part of it
2. For each change, check: correctness, edge cases, security, error handling
3. Flag anything that violates a CLAUDE.md rule as a hard issue
4. Distinguish hard issues (must fix) from suggestions (could improve)

## Output contract
Return a list of findings. Each finding: file:line, severity (HARD or
SUGGESTION), and a one-sentence description. End with a verdict: PASS if no
HARD issues, FAIL otherwise. Return nothing else.

## Failure modes
- Do NOT edit files. You have no Edit tool and must not request one.
- Do NOT review code outside the diff. Stay scoped to what changed.
- Do NOT pass a change with a HARD issue to be polite. Report it.

Each section does a specific job. The description is what Claude Code matches against to decide when to invoke this agent, so it must be precise about the trigger. The tools line scopes what the agent can do, and a reviewer that only reads gets Read, Grep, Bash and no Edit, which makes "do not change files" a structural fact rather than a hope. The mandatory reads point the agent at the context it needs so it does not start blind. The operating procedure sequences the work. The output contract is the part the parent depends on, because a result in a known shape can be acted on, and a result in free prose cannot. The failure modes name the drift the agent must avoid in its own voice.

This anatomy, intent plus mandatory reads plus procedure plus output contract plus failure modes, is what turns a vague delegation into a contract. The agent knows its job, has the context, produces a parseable result, and cannot exceed its tools.

Scoping tools to the job

The most consequential line in a subagent definition is the tools field, because it decides what the agent can do to your system. A subagent inherits no tools by default beyond what you grant, and the right grant is the minimum the job requires.

A reviewer reads and reports, so it gets read-only tools. A researcher fetches and synthesises, so it gets search and fetch tools but no write access. A focused refactor agent needs Edit, but only for the files in its scope, and pairing it with permission rules keeps it inside that scope. The mistake is granting the full tool set out of convenience, because an agent with Edit, Bash, and unrestricted permissions can do anything the main session can, including the destructive things you delegated specifically to keep it away from.

---
name: researcher
description: Researches a technical question and returns a cited summary. Invoke for questions that need external sources.
tools: WebSearch, WebFetch, Read
---

This researcher can search the web, fetch pages, and read local files, and it can do nothing else. It cannot edit, cannot run shell commands, cannot touch the repository. The scoping is the safety property: even if the agent misinterprets its brief entirely, the worst it can do is return a bad summary, because it has no tool that changes state. Granting tools by job is the same least-privilege discipline that Claude Code permissions applies to the main session, pushed down to each delegated task.

The subagent CLAUDE.md template

The project CLAUDE.md governs how the main session uses subagents: when to delegate, how to brief, and the rules every subagent inherits when it reads the file.

# Subagent rules

## When to delegate
- A task that needs a fresh context (long research, full-file review)
- A task that runs better in isolation from the main thread
- A repeated, well-defined job worth a dedicated agent

## Briefing a subagent (MANDATORY)
- State the single job in one sentence
- Name the files the agent must read
- State the exact output shape the parent needs back
- NEVER hand a subagent a vague, open-ended instruction

## Tool scoping (MANDATORY)
- Grant each agent the MINIMUM tools its job needs
- A read-only job gets read-only tools, no Edit, no destructive Bash
- NEVER grant the full tool set "to be safe"

## Output contracts
- Every subagent returns a result in a defined shape
- The parent must be able to parse the result into a next action
- A result in free prose with no structure is a failure

## Hard rules
- NEVER delegate without stating the job, the reads, and the output shape
- NEVER grant a subagent more tools than its job requires
- NEVER trust a subagent result that does not match its output contract
- NEVER let a subagent edit files when its job is to report
- ALWAYS isolate long or context-heavy work in a subagent
- ALWAYS define the output contract before invoking the agent

Three rules carry most of the value.

The briefing rule prevents drift at its source. Drift starts with a vague instruction, because an agent given room to interpret will interpret in directions you did not intend. The rule forces a one-sentence job, named reads, and a defined output before the agent runs, which leaves no room to wander.

The tool-scoping rule makes safety structural. An agent without an Edit tool cannot edit no matter how it misreads its brief. The rule ties the tool grant to the job so the agent's capabilities match its purpose, which is the difference between a contained delegation and an open-ended one.

The output-contract rule is what makes the result usable. A subagent that returns structured findings can be consumed by the parent automatically. One that returns a wall of prose forces the parent to re-read and re-interpret, which burns the context the delegation was supposed to save. The rule makes the shape a requirement, not a nicety.

Briefing a subagent so it does not wander

How you invoke a subagent matters as much as how you define it. A good brief restates the job, names the inputs, and states the output, even when the agent's own definition already covers them, because the brief is the agent's immediate context and the most recent instruction carries weight.

A weak invocation looks like "review the auth changes." A strong one looks like "review the diff in src/auth/ for correctness and security issues, read the project CLAUDE.md for the rules these files must follow, and return your findings in the PASS/FAIL contract from your definition." The strong version leaves nothing to interpretation: the scope is the auth diff, the context is CLAUDE.md, the output is the known contract. The agent starts aligned and stays aligned because there is no slack to drift into.

The same discipline applies to inputs the agent cannot discover on its own. If a review depends on a spec, name the spec. If a refactor must preserve a public API, state the API. A subagent runs in an isolated context and knows only what its definition, its mandatory reads, and your brief tell it. Anything you assume it knows but do not state is a gap it will fill with a guess. This is the delegation equivalent of the precision that CLAUDE.md examples brings to project rules: the more exact the instruction, the less room for the wrong outcome.

Output contracts that survive the context boundary

The hardest part of delegation is the handoff, because the subagent and the parent do not share a context. Everything the parent learns from the subagent comes through the result, and a result the parent cannot parse is a result it cannot use. The output contract is the protocol that makes the handoff reliable.

A strong contract specifies the exact shape: a list of findings with fields, a verdict from a fixed set, a structured object the parent can read programmatically. The reviewer above returns findings keyed by file:line with a severity and a one-line description, ending in PASS or FAIL. The parent reads the verdict, branches on it, and acts. There is no interpretation step, because the shape is known in advance.

A weak contract is "summarise what you found," which produces prose that the parent must re-read and re-judge, defeating the purpose of delegating. The fix is to make the contract part of the agent definition and restate it in the brief, so the agent produces the shape every time. When the output is structured, the parent consumes it in one step and moves on, which is the efficiency delegation is supposed to deliver. For tasks where the contract feeds a downstream stage, Claude Code parallel agents covers how multiple structured results merge without contradiction.

Common Claude Code mistakes with subagents

Six patterns Claude generates incorrectly without CLAUDE.md constraints.

1. A vague, open-ended brief

Claude generates: "look into the performance issue" with no scope or output shape.

Correct pattern: a one-sentence job, named files to read, and the exact result shape the parent needs.

2. The full tool set granted by default

Claude generates: a reviewer agent with Edit and unrestricted Bash.

Correct pattern: scope tools to the job, so a read-only task gets read-only tools.

3. No output contract

Claude generates: an agent that returns free prose the parent has to re-interpret.

Correct pattern: a defined output shape the parent can parse into a next action.

4. A subagent editing when it should report

Claude generates: a review agent that "helpfully" fixes the issues it finds.

Correct pattern: no Edit tool for a reporting job, so fixing is structurally impossible.

5. Missing mandatory reads

Claude generates: an agent that starts work without reading the CLAUDE.md or the spec.

Correct pattern: list the mandatory reads so the agent has its context before it acts.

6. Delegating a task that belongs inline

Claude generates: a subagent for a two-line change that the main session should just make.

Correct pattern: delegate only context-heavy or isolation-worthy work; do small tasks inline.

Add each pattern to CLAUDE.md with the corrected form. Combined with the agent file anatomy above, the result is delegation Claude gets right the first time.

When a subagent is worth it

Not every task should be delegated. A subagent pays for itself when the job is context-heavy enough that running it inline would crowd the main thread, or isolated enough that a fresh context produces a cleaner result, or repeated enough that a dedicated agent definition earns its keep. Long research, full-codebase review, and focused multi-file refactors all clear that bar.

A two-line edit does not. Spinning up a subagent for a trivial change adds the overhead of briefing, the latency of a separate run, and the cost of parsing a result, all to avoid work the main session could do in one tool call. The judgement is the same one that governs any abstraction: the delegation is worth it when the job's weight exceeds the handoff's cost, and not before. A session that delegates everything spends more time coordinating than working, which is its own kind of drift.

Building subagents that delegate without drift

The subagent setup in this guide produces agents that do one job, run with the minimum tools that job needs, read the context they depend on, and return a result the parent can parse, with failure modes named in the agent's own voice. The result is delegation that contains the work instead of scattering it, where a handed-off task comes back in a shape the session can act on rather than a sprawl it has to redo.

The principle is the same as any Claude Code configuration. A subagent without a contract is a delegation into a black box that drifts, edits what it should read, and returns prose nobody can use. The agent definition and the briefing discipline are what turn the black box into a reliable worker with a clear job and a known output.

For the context isolation that makes subagents worth building, Claude Code context window management covers why a fresh window is the core benefit. For running many agents at once, Claude Code parallel agents covers fan-out and result merging. For the least-privilege foundation each agent's tool scope rests on, Claude Code permissions covers the policy layer.

Get Claudify. Build subagents that finish the job you gave them and nothing else.