code-subagents

实现子 Agent

每项任务使用一个全新的子 Agent。每批任务完成后进行一次综合审查。相互独立时并行执行， 存在依赖时按顺序执行。

何时使用子 Agent

适合使用的情况（必须同时满足以下所有条件）：

• 设计已敲定：计划或 design.md 已规定文件内容（类型、签名、架构、契约或可供照搬的现有模式）
• 工作项有明确的要求、负责的文件和验证命令
• 不与其他正在进行的工作共享文件或状态

首选任务包括新建文件、搭建脚手架、编写样板代码，以及遵循现有模式进行编辑。 是否并行是另一个问题：只有通过下方的独立性检查时，才同时分派两个或更多符合条件的工作项。

不适合使用的情况：

• 任务紧密耦合（编辑相同文件）
• 需要了解跨任务的完整系统状态
• 故障彼此相关（修复一个可能解决其他故障）
• 问题尚未明确的探索性工作

分派模式

顺序执行（存在依赖的任务）

有依赖关系的任务逐一执行。每项任务都使用一个全新的子 Agent，以免受到先前上下文的影响。

Task 1 (Entity) → review → complete
Task 2 (Repository, depends on T1) → review → complete
Task 3 (Service, depends on T2) → review → complete

并行执行（相互独立的任务）

同时分派相互独立的任务。每个问题领域分配一个 Agent。

Task A (auth tests) ──→ review → complete
Task B (billing tests) ──→ review → complete    ← concurrent
Task C (notification tests) ──→ review → complete

**独立性检查：**修复任务 A 会影响任务 B 吗？它们会编辑相同的文件吗？ 如果这两个问题的答案都是否，则并行分派。

对于共享工作树的并行任务：

1. 分派前为每项任务指定独占的文件列表
2. 不要让实施人员暂存或提交更改
3. 在每项任务执行前后记录完整的 git status，包括未跟踪文件
4. 获取限定在任务路径范围内的补丁，并拒绝超出指定路径的更改
5. 如果文件归属有重叠或无法隔离，则按顺序运行任务

---

Agent 选择

每次分派都要明确选择 Agent（参见 atelier-orchestrator 中的 Delegation）。向实施人员提供设计摘录，避免他们自行做设计决策：机械式文件创建应匹配脚手架 Agent；对设计敏感的实现可以使用该框架的通用 Agent，这是允许不从 Atelier 的 Agent 中选择的唯一例外。批次审查员负责只读的严格审查。

---

提示词模板

分派子 Agent 时使用以下模板。这些模板经过实践检验——不要自行发挥，照原样使用并填入变量。

• references/implementor-prompt.md — 分派实施人员。包含自审清单。
• references/batch-reviewer-prompt.md — 对已完成批次进行计划与代码质量综合审查。

提示词质量规则

• 聚焦 — 一项任务，一个问题领域
• 自包含 — 提示词中包含所需的全部上下文。提供完整的工作项要求；不要让子 Agent 自行查找上下文
• 明确文件范围 — 使用确切路径，而非“相关文件”
• 明确输出要求 — 子 Agent 应返回什么？
• 有所约束 — 指明不应修改的内容

常见错误

错误	修正
“修复所有测试”	“修复 user.test.ts 中的 3 个失败项”
没有提供代码库相关背景	粘贴相关的模式和约定
没有约束	“不要更改生产代码”或将范围限定为特定文件
输出要求含糊	“返回：根本原因、所做更改、测试结果”

---

批次审查

每完成一个批次后，进行一次合并审查，不要针对每项任务分别审查。

指定一位新的审查者，并提供：

• 批次中各工作项的完整要求
• 相关约束
• 每项任务的路径范围补丁
• 完整的变更文件清单，包括未跟踪文件
• 实施者的报告和验证结果

审查者需检查是否符合要求以及代码质量：

1. 是否实现了每项要求和验收标准
2. 批次是否遵循所提供的约束
3. 是否包含未经请求的工作或超出范围的文件
4. 测试是否有意义，且覆盖了正确的边界
5. 代码是否遵循现有模式，且没有不必要的复杂性

按原文使用 references/batch-reviewer-prompt.md。

如果审查者发现严重或重要问题，请将每个问题退回给相关实施者，刷新其路径范围补丁，然后重新审查整个批次。可以记录并暂不处理次要问题。

---

处理子 Agent 的问题

子 Agent 可能会在实施前或实施过程中提问。这是好事——说明他们在思考，而不是猜测。

• 清楚、完整地回答
• 视需要提供更多背景信息
• 不要催促他们开始实施
• 如果问题暴露了计划中的缺漏，这是有价值的信息——请记录下来

---

整合结果

子 Agent 完成后（尤其是并行派发时）：

1. 阅读每份摘要——了解变更内容
2. 获取任务补丁——使用每项任务独占的文件列表
3. 审查批次——合并审查要求和质量
4. 运行完整测试套件——验证所有变更能协同工作
5. 提交——由协调者按顺序提交已审查的批次
6. 更新进度跟踪——仅在调用方使用进度跟踪时执行

如果并行任务的结果存在冲突，请手动解决。不要再派发另一个子 Agent 来合并——这需要掌握过多上下文。

---

子 Agent 失败时的处理

如果子 Agent 未能完成任务：

• 不要手动修复——这会污染你的上下文
• 派发一个修复子 Agent，并具体说明问题所在
• 如果连续失败两次，请停止并上报给人工处理。要求或约束可能需要修订。