Agents: Design Patterns

Start with a single agent plus good tools. Add agents only when a specific pattern below solves a problem you’ve actually seen. More agents means more latency, more cost, and more places for context to get lost.

1. Specialist subagent (the default multi-agent step)

Main agent ──task──▶ [specialist] ──summary──▶ Main agent

• Use for: code search, review, test running, documentation lookup.
• Key design: a narrow description, a read-only configuration where possible, and a strict output template.
• Template: code-reviewer.md, researcher.md

2. Orchestrator + parallel workers

             ┌─▶ worker A (area 1) ─┐
Orchestrator ├─▶ worker B (area 2) ─┼─▶ Orchestrator merges
             └─▶ worker C (area 3) ─┘

• Use for: broad research (“audit every service for X”) and multi-area changes that don’t overlap.
• Key design:
  • Split the work so that workers never touch the same files.
  • Give each worker a complete, self-contained brief, because workers don’t share context.
  • Define a merge format up front so the orchestrator can combine the results.
• Watch for: duplicated work, inconsistent conventions across workers, and token cost multiplying by the number of workers.

3. Generator + verifier

Generator ──output──▶ Verifier ──pass/fail + evidence──▶ (loop or finish)

• Use for: anything where “looks done” and “is done” differ, such as code changes, migrations, and data transforms.
• Key design:
  • The verifier is independent: a fresh context and a skeptical prompt, and it must produce evidence (commands run and their outputs).
  • Limit the loop (for example, three rounds at most), then escalate to a human.
• Template: cursor-verifier.md

4. Pipeline (staged hand-offs)

Spec writer ─▶ Implementer ─▶ Test writer ─▶ Reviewer

• Use for: repeatable multi-stage workflows.
• Key design: each stage writes an artifact (a file) that the next stage reads, rather than relying on chat context. Artifacts make the stages debuggable and restartable.

5. Router

Router ─classify─▶ { billing-agent | tech-support-agent | sales-agent }

• Use for: SDK agents and products that handle distinct request types.
• Key design: a router that’s cheap and fast, specialists with non-overlapping scopes, and a fallback for “none of the above”.

6. Human-in-the-loop checkpoint

• Use for: irreversible or externally visible actions such as deploying, sending email, deleting data, or spending money.
• Key design:
  • The agent proposes, writing a plan file or a dry-run output. A human approves, and only then does the agent execute.
  • Enforce the checkpoint with permissions or hooks, not only with prompt text.

Writing the brief a parent sends to a subagent

Most failures in multi-agent setups come from a thin brief. A good brief includes:

Goal:        <one sentence>
Context:     <what the parent knows that the subagent needs: files, decisions, constraints>
Scope:       <what's in / out; which files it may touch>
Deliverable: <exact output shape and length>
Done when:   <stop condition>

Put this template in your main agent’s rules or skill so it writes briefs consistently.

Guardrails toolbox

Guardrail	Mechanism	Strength
Prompt instruction (“never edit”)	System prompt	Soft: the model usually complies
Tool allowlist	tools: (Claude Code), allowedTools (SDK)	Hard
Read-only mode	readonly: true (Cursor)	Hard
Command blocking	Hooks (beforeShellExecution / PreToolUse, exit code 2)	Hard
Permission prompts	Host permission modes / allowlists	Hard (needs a human)
Sandbox	Container, ephemeral runner, scoped tokens	Hardest

Put at least one hard guardrail on anything that can modify state outside the repo.

Choosing models per role

Role	Model choice
Search / exploration / classification	Fast, cheap
Implementation	Strong general model (or inherit)
Review / verification / architecture	Strongest available; independence matters more than speed
Router	Fastest

Use model: inherit unless you have measured a reason to change it. It keeps the agent in step with whatever the user has chosen.