building-agent-team-prompts

构建 Agent 团队提示词

概览

Agent 团队提示词必须自包含——队友不会继承你的对话历史。队友所需的每一项上下文都必须包含在其启动提示词中，或能从代码库中找到。

核心原则： 优质的 Agent 团队提示词会明确说明谁负责哪些文件上的哪些工作、如何沟通，以及何时算完成。

编写提示词前

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

• 多个相互独立的工作流（审查、研究、互不重叠的实现）
• 存在相互竞争的假设，适合并行调查
• 涉及多个层级，且每个层级都能独立负责

以下情况不要使用 Agent 团队： 顺序执行的任务、集中在少数几个文件上的工作，或协调开销超过收益的简单任务。改用子 Agent 或单个会话。

提示词模板

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

1. 目标

用一句话说明团队要完成什么。

2. 团队组成

为每位队友列出：

• 名称：描述性名称，使用 kebab-case（security-reviewer、backend-impl）
• 角色：用一句话描述其工作重点
• 模型：常规任务或研究任务使用 sonnet，复杂推理使用 opus。除非任务需要深入分析，否则默认使用 sonnet。

合理配置规模： 优先选择人数较少、每人承担更多任务的团队，而不是人数多、每人只做一项任务的团队。3 人团队每人承担 5 项任务，胜过 6 人团队每人承担 2 项任务。只有在工作确实受益于独立上下文窗口时，才启动队友。

经验法则： 启动前，估算每位队友的工作量。如果某位队友的任务少于 3 项，或工作时间少于 15 分钟，就将其职责并入其他队友的角色。

3. 队友启动提示词

为每位队友提供自包含的提示词，其中包括：

• 完整任务背景——他们需要了解、但 CLAUDE.md 中没有的信息
• 具体说明——需要调查、构建或审查的内容
• 文件所有权——由他们独占负责的文件或目录
• 禁止触碰——其他队友负责、他们不得修改的文件
• 输出要求——格式、结构及结果写入位置

重要： 队友看不到你的对话。如果用户之前解释过重要信息，请将其写入启动提示词。

务必包含： 要求每位队友在构建或审查前先检查代码库中的现有模式。实现任务应说明：“编写新代码前，先检查代码库中类似功能的实现方式，并遵循这些模式。”审查任务应说明：“检查项目惯例和现有模式，以校准审查标准。”

4. 任务分解

将任务拆解为具体事项，并注明：

• 每项任务的明确交付物
• 任务间的依赖关系（哪些任务会阻塞其他任务）
• 具体由哪位队友负责
• 目标：每位队友承担 3–6 项任务

不要只分配角色——要将工作拆解为可跟踪的任务，并加入共享任务列表。

5. 沟通协议

明确队友何时应互相发送消息：

• 分享发现：“如果发现 X，请给 teammate-Y 发消息”
• 跨领域事项：“发现破坏性变更时，通知所有队友”
• 对抗性质疑：调试时，队友应主动尝试证伪彼此的理论

如果队友之间无需沟通，请明确说明——这样可以节省令牌。

6. 协调设置

• 委派模式：当负责人只需协调、不参与实现时使用。适用于 3 人及以上的团队，或负责人会与队友争抢文件时。
• 计划审批：队友要修改生产代码或做出架构决策时，必须要求审批。只读研究或审查任务可跳过。
• 完成定义：明确说明满足什么条件才算完成。

7. 交付物

• 每位队友要产出的内容（包括格式）
• 负责人需要从队友的输出中综合整理的内容
• 最终输出（报告、PR 评论、实现等）

任务类型模式

代码审查

• 按领域划分审查人员，而非按文件数量划分
• 跨领域审查人员（安全、测试）与领域审查人员协调
• 每条发现采用结构化输出：severity | file:line | description | suggestion
• 负责人综合整理，形成一份审查摘要

功能实现

• 每层安排一位队友（DB / API / 前端 / 测试）
• 明确界定共享接口——由一位队友定义 API 契约，其他队友使用该契约
• 实现前必须获得计划批准
• 让负责人使用委派模式
• 严格划分文件所有权——任何两个队友都不能修改同一个文件

调试 / 调查

• 每个假设安排一位队友
• 采用对抗式结构：队友通过消息质疑彼此的理论
• 如果 Bug 是间歇性出现的，应安排一位复现问题的队友
• 负责人跟踪哪些假设经得起审查，并综合得出结论

研究 / 探索

• 每个研究角度安排一位队友
• 要求队友以实际代码库为依据，而非依赖一般知识
• 制定综合计划：由谁撰写最终报告，以及采用什么格式
• 设置范围边界，避免研究无休止地进行

文件所有权规则

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

1. 每个修改过的文件都只能有一位所有者——如果两位队友都需要修改该文件，其中一位负责所有，另一位通过消息提出修改请求
2. 共享类型 / 接口：由一位队友定义，其他队友只能读取
3. 测试：由负责被测代码的队友所有，或交由专门的测试队友负责，但该队友不得修改源代码
4. 配置文件：指定一位队友负责

快速参考

要素	问问自己
团队规模	能否减少队友人数，让每位队友承担更多任务？
模型	这需要 Opus 吗，还是 Sonnet 就够了？
委派模式	负责人是否应该避免编写实现？（3 人及以上时应避免）
计划批准	队友是否会修改生产代码？
沟通	队友是否需要共享发现或相互质疑？
文件所有权	是否可能有两位队友修改同一个文件？
范围	这个团队何时算“完成”？
交付物	每位队友具体要产出什么？

常见错误

错误	后果	修正方法
未划分文件所有权	队友相互覆盖修改	为每个修改过的文件指定一位所有者
交付物含糊不清	输出质量参差不齐	为每位队友指定交付格式
所有队友都使用 Opus	完成 Sonnet 级别任务却要花 4 倍成本	默认使用 Sonnet，有选择地升级
未制定沟通计划	各自为政，错过跨领域洞见	明确规定何时发送消息
负责人也参与实现	与队友争夺文件	启用委派模式
未设定范围边界	研究永无止境	明确界定“完成”
队友太多	协调成本超过收益	减少队友人数，让每位队友承担更多任务
未要求计划批准	糟糕的架构决策被付诸实施	实现任务必须获得计划批准
未检查现有模式	队友重新发明已有实现	要求队友检查类似功能的实现方式