building-agent-team-prompts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Agent Team Prompts

构建Agent团队提示词

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.

Agent团队的提示词必须是自包含的——团队成员不会继承你的对话历史。成员所需的所有上下文信息都必须包含在其生成提示词中，或是能从代码库中获取。

核心原则： 优秀的Agent团队提示词需明确指定谁在哪些文件上做什么事、如何沟通，以及何时完成。

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.

确认任务确实能从Agent团队中获益：

存在多个独立工作流（评审、调研、无重叠的实现工作）
存在可从并行调研中获益的竞争性假设
跨层级工作，且每个层级可独立负责

请勿使用Agent团队的场景： 顺序执行的任务、工作集中于少量文件，或是协调成本超过收益的简单任务。此时应使用子Agent或单会话。

Prompt Template

提示词模板

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

每个Agent团队提示词都应包含以下部分，不适用的部分可跳过。

1. Goal

1. 目标

One sentence: what is the team trying to accomplish?

一句话说明：团队要达成什么目标？

2. Team Composition

2. 团队构成

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.

针对每个成员：

名称：描述性的短横线命名法（如
```
security-reviewer
```
、
```
backend-impl
```
）
角色：一句话说明其专注方向
模型：常规/调研任务使用
```
sonnet
```
，复杂推理任务使用
```
opus
```
。除非任务需要深度分析，否则默认使用
```
sonnet
```
。

规模适配： 优先选择数量更少但承担更多任务的成员，而非大量仅承担单一任务的成员。3个各承担5项任务的成员组成的团队，优于6个各承担2项任务的团队。只有当工作确实能从独立上下文窗口中获益时，才生成新的成员。

启发式规则： 在生成成员前，估算每个成员的工作量。如果某个成员的任务少于3项，或工作量不足15分钟，应将其职责合并到其他成员的角色中。

3. Teammate Spawn Prompts

3. 成员生成提示词

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."

每个成员都需要一个自包含的提示词，包括：

完整任务上下文——所有未包含在CLAUDE.md中的必要信息
具体指令——需调研、构建或评审的内容
文件归属——其专属负责的文件/目录
禁止操作——其他成员负责的、不得修改的文件
输出要求——格式、结构、结果存储位置

关键注意事项： 团队成员无法查看你的对话历史。如果用户之前解释过重要信息，必须将其包含在生成提示词中。

必须包含的内容： 告知每个成员在构建或评审前，先检查代码库中的现有模式。对于实现任务：“编写新代码前，检查代码库中类似功能的实现方式并遵循该模式。” 对于评审任务：“检查项目规范和现有模式，以此校准你的评审标准。”

4. Task Breakdown

4. 任务拆分

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.

定义具体任务时需包含：

每个任务的明确交付物
任务间的依赖关系（哪些任务会被其他任务阻塞）
任务的具体负责人
目标：每个成员负责3-6项任务

不要仅分配角色——需将工作拆分为可追踪的任务并形成共享任务列表。

5. Communication Protocol

5. 沟通协议

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.

明确规定成员间的沟通场景：

共享发现：“如果发现X，需向
```
teammate-Y
```
发送消息”
跨领域问题：“向所有成员标记破坏性变更”
对抗性验证：调试时，成员需主动尝试反驳彼此的理论

如果成员无需沟通，请明确说明——这能节省token消耗。

6. Coordination Settings

6. 协调设置

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.

委托模式：当负责人仅需协调而非参与实现时使用。推荐在团队规模为3人及以上，或负责人会与成员争抢文件权限时使用。
计划审批：当成员需修改生产代码或做出架构决策时要求启用。只读调研/评审任务可跳过。
完成标准：明确说明任务完成的判定条件。

7. Deliverables

7. 交付物

What each teammate produces (with format)
What the lead synthesizes from teammate outputs
Final output (report, PR comments, implementation, etc.)

每个成员需产出的内容（含格式）
负责人需从成员输出中整合的内容
最终输出（报告、PR评论、实现代码等）

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

每个层级分配一名成员（数据库/API/前端/测试）
明确定义共享接口——由一名成员定义API契约，其他成员基于契约开发
实现前必须经过计划审批
负责人启用委托模式
严格的文件归属规则——禁止两名成员修改同一文件

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

每个假设分配一名成员
采用对抗性结构：成员通过消息反驳彼此的理论
如果Bug出现间歇性，安排一名成员负责复现问题
负责人追踪哪些假设经得住验证，并整合最终结论

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

文件冲突是Agent团队中工作浪费的首要原因。

每个被修改的文件有且仅有一个负责人——如果两名成员都需要该文件，由一名成员负责，另一名通过消息请求变更
共享类型/接口：由一名成员定义，其他成员仅可读取
测试文件：由对应业务代码的负责人负责，或由专门的测试成员负责（不得修改业务代码）
配置文件：指定一名专属负责人

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?

要素	自问自查
团队规模	能否用更少的成员承担更多任务？
模型选择	是否需要Opus，还是Sonnet已足够？
委托模式	负责人是否应避免参与实现？（3人及以上团队建议启用）
计划审批	成员是否会修改生产代码？
沟通机制	成员是否需要共享或验证彼此的发现？
文件归属	是否存在两名成员可能修改同一文件的情况？
范围边界	团队何时算“完成”？
交付物	每个成员具体需要产出什么？

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

错误	后果	修复方案
未设置文件归属	成员互相覆盖代码	为每个被修改的文件分配唯一负责人
交付物定义模糊	输出质量不一致	为每个成员明确指定输出格式
所有成员都使用Opus	任务成本为Sonnet的4倍	默认使用Sonnet，仅在必要时升级为Opus
未制定沟通计划	信息孤岛，遗漏跨领域洞察	明确指定触发沟通的场景
负责人参与实现	与成员争抢文件权限	启用委托模式
未设置范围边界	调研无限期进行	明确定义“完成”标准
团队规模过大	协调成本超过收益	减少成员数量，为每个成员分配更多任务
未要求计划审批	不良架构决策被上线	实现任务必须经过计划审批
未要求检查现有模式	成员重复造轮子	告知成员先查看类似功能的实现方式