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.

1. Every modified file has exactly one owner — if two teammates need it, one owns it and the other requests changes via messages
2. Shared types/interfaces: one teammate defines them, others read only
3. Tests: owned by whoever owns the code under test, or a dedicated test teammate who doesn't touch source
4. Config files: one designated teammate

Quick Reference

Common Mistakes