Building Agent Team Prompts

Overview

Agent team prompts must be self-contained — teammates don't inherit your conversation history. Every piece of context a teammate needs must be in their spawn prompt or discoverable from the codebase.

Core principle:

A good agent team prompt specifies WHO does WHAT on WHICH files, HOW they communicate, and WHEN they're done.

Before You Build the Prompt

Verify the task actually benefits from an agent team:

Multiple independent workstreams (review, research, non-overlapping implementation)

Competing hypotheses that benefit from parallel investigation

Cross-layer work where each layer is independently ownable

Don't use agent teams for:

sequential tasks, work concentrated in a few files, or simple tasks where coordination overhead exceeds benefit. Use subagents or a single session instead.

Prompt Template

Every agent team prompt should cover these sections. Skip sections that don't apply.

1. Goal

One sentence: what is the team trying to accomplish?

2. Team Composition

For each teammate:

Name

descriptive, kebab-case (

security-reviewer

,

backend-impl

)

Role

one sentence describing their focus

Model

:

sonnet

for routine/research tasks,

opus

for complex reasoning. Default to

sonnet

unless the task demands deep analysis.

Right-sizing:

Prefer fewer teammates with more tasks over many single-task teammates. A team of 3 with 5 tasks each beats a team of 6 with 2 each. Only spawn a teammate when the work genuinely benefits from a separate context window.

Heuristic:

Before spawning, estimate the work per teammate. If a teammate would have fewer than 3 tasks or less than 15 minutes of work, merge their responsibilities into another teammate's role instead.

3. Teammate Spawn Prompts

Each teammate gets a self-contained prompt including:

Full task context

— what they need to know that isn't in CLAUDE.md

Specific instructions

— what to investigate, build, or review

File ownership

— which files/directories they own exclusively

Hands off

— files owned by other teammates they must not modify

Output expectations

— format, structure, where to write results

Critical:

Teammates can't see your conversation. If the user explained something important earlier, include it in the spawn prompt.

Always include:

Tell each teammate to check existing codebase patterns before building or reviewing. For implementation: "Before writing new code, check how similar features are implemented in the codebase and follow those patterns." For review: "Check project conventions and existing patterns to calibrate your review."

4. Task Breakdown

Define concrete tasks with:

Clear deliverable per task

Dependencies between tasks (what blocks what)

Assignment to a specific teammate

Target: 3-6 tasks per teammate

Don't just assign roles — break work into trackable tasks with the shared task list.

5. Communication Protocol

Specify when teammates should message each other:

Share findings

"If you discover X, message

teammate-Y

"

Cross-cutting concerns

"Flag breaking changes to all teammates"

Adversarial challenge

for debugging, teammates actively try to disprove each other's theories

If teammates don't need to communicate, say so explicitly — it saves tokens.

6. Coordination Settings

Delegate mode

Use when the lead should coordinate only, not implement. Recommended for 3+ teammates or when the lead would compete for files.

Plan approval

Require when teammates modify production code or make architectural decisions. Skip for read-only research/review.

Definition of done

State explicitly what constitutes completion.

7. Deliverables

What each teammate produces (with format)

What the lead synthesizes from teammate outputs

Final output (report, PR comments, implementation, etc.)

Task Type Patterns

Code Review

Scope reviewers by domain, not file count

Cross-cutting reviewers (security, testing) coordinate with domain reviewers

Structured output per finding:

severity | file:line | description | suggestion

Lead synthesizes into single review summary

Feature Implementation

One teammate per layer (DB / API / frontend / tests)

Define shared interfaces explicitly — one teammate defines the API contract, others consume it

Require plan approval

before implementation

Use delegate mode

for the lead

Strict file ownership — no two teammates touch the same file

Debugging / Investigation

One teammate per hypothesis

Use adversarial structure

teammates challenge each other's theories via messages

Include a reproduction teammate if the bug is intermittent

Lead tracks which hypotheses survive scrutiny and synthesizes the conclusion

Research / Exploration

One teammate per research angle

Instruct teammates to ground findings in the actual codebase, not general knowledge

Define a synthesis plan: who writes the final report and in what format

Set scope boundaries to prevent endless research

File Ownership Rules

File conflicts are the #1 source of wasted work in agent teams.

Every modified file has exactly one owner

— if two teammates need it, one owns it and the other requests changes via messages

Shared types/interfaces

one teammate defines them, others read only

Tests

owned by whoever owns the code under test, or a dedicated test teammate who doesn't touch source

Config files

one designated teammate Quick Reference Element Ask yourself Team size Can fewer teammates with more tasks do this? Model Does this need Opus, or is Sonnet sufficient? Delegate mode Should the lead avoid implementing? (yes for 3+) Plan approval Are teammates modifying production code? Communication Do teammates need to share or challenge findings? File ownership Could two teammates touch the same file? Scope When is this team "done"? Deliverables What exactly does each teammate produce? Common Mistakes Mistake Consequence Fix No file ownership Teammates overwrite each other Assign every modified file to one owner Vague deliverables Inconsistent output quality Specify format per teammate All teammates on Opus 4x cost for Sonnet-level tasks Default to Sonnet, upgrade selectively No communication plan Silos, missed cross-cutting insights Specify message triggers Lead implements too Competes with teammates for files Enable delegate mode No scope boundary Research runs forever Define "done" explicitly Too many teammates Coordination overhead exceeds benefit Fewer teammates, more tasks each No plan approval Bad architectural decisions ship Require for implementation tasks No existing pattern check Teammates reinvent what exists Tell them to check how similar features work