Designing Effective Subagents

Four design principles

1. One job per agent

A "helper" that reviews, tests, documents and deploys does none of those well. Narrow roles (test-runner, security-reviewer, docs-writer) get sharper instructions and better routing.

2. A description that singles it out

Claude chooses a subagent by its description. If two agents both say "helps with code quality", routing becomes a coin flip. Make each description name what triggers it and what it returns:

description: Runs the test suite, then diagnoses and fixes failing tests. Use after code changes or when tests fail. Returns a list of fixes and the final test status.

3. Least-privilege tools

Give each agent only what its job needs. A reviewer needs Read, Grep, Glob, not Edit. A docs writer may need Edit but not Bash. Limited tools make agents safer and keep them on task.

4. Structured output and obstacle reporting

The main agent has to use what a subagent returns. Tell the subagent exactly what shape to report in, and what to do when it gets stuck:

## Report format
STATUS: done | blocked | partial
CHANGED: list of files changed
VERIFIED: the exact command you ran and its result
OBSTACLES: anything that stopped you, and what you'd need to continue

Obstacle reporting is crucial. A subagent that hits a missing credential or an ambiguous requirement should say so rather than guess or quietly skip work.

Anti-patterns to avoid

• The do-everything agent, which routes unpredictably and follows instructions poorly.
• Overlapping descriptions, so the wrong agent gets picked.
• Full tool access by default, which is riskier and less focused.
• Free-form reports, which are hard for the main agent to act on.
• Delegating tiny tasks, which costs tokens and latency for no benefit.

Check your understanding