Designing Effective Subagents

Subagents become useful only after you stop thinking of them as personalities and start treating them as bounded execution lanes.

Most bad subagent designs fail in one of two ways:

1. They are too vague, so the helper improvises.
2. They are too broad, so the helper recreates the whole parent task badly.

The real design work is not "make more agents." It is define sharp ownership.

Start With A Job, Not A Persona

A subagent should have a concrete job: inspect migrations, review security-sensitive code, draft release notes, or run a compatibility check. "Be a senior engineer" is not a job. It is a vibe.

Good subagent descriptions answer:

1. What input will this agent receive?
2. What output must it return?
3. What tools can it use?
4. What should it do when blocked?

If you cannot tell whether the subagent succeeded without rereading everything it did, the job definition is weak.

Output Contracts Matter

If the parent agent needs findings, request findings with file references and severity. If it needs a patch, request changed files and verification evidence. If it needs a summary, request decisions and unresolved questions.

Without an output contract, subagent output becomes prose that must be interpreted again.

That defeats the point of delegation. You moved the work, but not the cognitive load.

Limit Tool Access

Subagents do not need every tool. A read-only reviewer should not have write access. A writer does not need deployment permissions. A verifier may need test commands but not broad edit scope.

Tool limits are not just security. They also improve focus.

A helper with too many tools tends to wander. A helper with a narrow tool surface behaves more like a function and less like a loose collaborator.

Report Obstacles Explicitly

A good subagent reports blockers instead of guessing. Examples:

1. "The source file does not exist."
2. "The test requires network access."
3. "The requested change conflicts with another edited file."

This is what keeps delegation honest. A good worker reports the wall. A bad worker invents a door.

When Subagents Shine

Subagents work well for:

1. Independent research lanes.
2. Code review of a finished patch.
3. Parallel implementation in disjoint files.
4. Log analysis while the main agent continues debugging.

They are weak for tightly coupled sequential work, vague expert judgment, and tasks where the next step depends immediately on their answer.

One useful heuristic: if the parent agent will have to stop and reinterpret every paragraph the subagent returns, keep the work local.

The Practical Rule

Use a subagent only when you can name three things clearly:

1. What it owns.
2. What it must return.
3. How the parent will verify it.

If any of those are fuzzy, delegation is likely to add noise faster than it adds throughput.