A subagent knows only its brief

Once a design has settled on a coordinator and workers, the most important text in the system is no longer the coordinator’s prompt. It is the message the coordinator writes each time it hands work to a worker, because that message is almost everything the worker will ever know about the job.

What a subagent starts with

Claude Code’s documentation is precise about this. Each subagent “runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” Its initial context is its own system prompt and the task message, “the delegation prompt Claude writes when it hands off the work.” The conversation that led to the handoff is not in it.

At the other end, the subagent “does that work in its own context and returns only the summary.” So two things cross the boundary, and both are yours to design.

Two ways a brief fails

It dictates steps. “Search for X, read the top three results, summarise them” fixes the route. When the first result turns out to be irrelevant, a procedural brief has no way to say so, and the subagent follows the steps anyway.

It is too thin. Anthropic hit this building its research system. With short instructions, “subagents misinterpreted the task or performed the exact same searches as other agents.” In one of their examples, a question about a semiconductor shortage sent one subagent to an earlier automotive chip crisis while two others duplicated each other’s work on current supply chains.

Their fix was specific:

Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries.

Anthropic Engineering, How we built our multi-agent research system

Alongside that, they describe prompting by “instilling good heuristics rather than rigid rules”. The brief sets the goal and the limits, and the subagent chooses the route.

The same job, briefed twice

The goal-oriented brief is longer and has more constraints, not fewer. The difference is what it constrains: the destination, the edges and the shape of the answer, instead of the route. Each part does a specific job.

That is also how a coordinator keeps visibility and control without dictating steps. It decides the goal, the division of work and the form of the answers, and it can check every result against the same format.

Put the permanent parts in the definition

Some of a brief is the same every time: the sources to prefer, the return format, the tools a worker may use. In Claude Code those belong in the subagent’s definition, a Markdown file with frontmatter in .claude/agents/ for a project or ~/.claude/agents/ for all your projects. Only name and description are required.

# .claude/agents/vendor-researcher.md
---
name: vendor-researcher
description: Checks one requirement of a third-party service against
  vendor documentation and returns met / not met / unclear with sources.
  Use for vendor due diligence. Not for pricing or code changes.
tools: WebSearch, WebFetch
model: sonnet
---
You check requirements of third-party services.
Prefer the vendor's own documentation and status history over blog posts.
For each requirement return: met, not met or unclear; one sentence of
reasoning; source URL and date retrieved. Mark anything that rests on a
single source as unconfirmed. Do not re-check facts the brief marks as known.

Three fields do more than they appear to:

• description decides when it is used. “Claude uses each subagent’s description to decide when to delegate tasks.” Saying what it is not for matters as much as what it is for.
• tools enforces the limit. “Web search and fetch only” written in a brief is a request. The same limit in tools is a constraint the subagent cannot step outside, and leaving the field out gives it every tool available to subagents. It is the same split between advice and enforcement that runs through Claude Code configuration generally.
• model sets the cost. Routing narrow, repetitive work to a faster, cheaper model is one of the uses the documentation lists.

With the permanent parts in the definition, each per-task brief shrinks to what is actually specific: the objective, what is already known, and the boundaries. Subagents can also run side by side, “Research the authentication, database, and API modules in parallel using separate subagents”, and by default a subagent can spawn its own, “up to three layers below the main conversation.” Every one of those layers is another boundary that only a brief crosses.

Try it

Decide the fix before opening each one.

The whole method

1. Assume the subagent has seen nothing but its own prompt and your brief.
2. Brief the destination: objective, what is already known, boundaries, sources, return format.
3. Move what is true for every task into the subagent definition, and enforce tool limits there.
4. Make every worker return the same shape, so the coordinator can combine and check the results.

Sources: Anthropic Engineering, How we built our multi-agent research system; the Claude Code documentation on subagents. The “already known” part of the brief is our addition. Checked September 2026.

More on this

• Give the task the shape it already has — Most agent designs go wrong by imposing a structure the work does not have. Draw the dependencies and the pattern names itself.
• Where a person gets to say no — A plan to approve, a gate, a retry limit, a customer asking for a human. Each is a pause, and each belongs somewhere different.
• Your MCP server is a prompt — Tool descriptions, resource lists and error messages all end up in front of the model. When Claude picks the wrong tool, the fix is usually in text the server wrote.