Multi-Agent Delivery

以最少的协调成本完成可验证交付。不要为了使用多 Agent 而创建多 Agent。

读取项目权威约束

开始前按适用范围读取：

1. 根目录和目标模块的 AGENTS.md；
2. 项目唯一的 ARCHITECTURE.md；
3. README、测试说明和用户指定文档；
4. 当前 Git 状态、分支、base SHA 和用户已有修改。

把长期架构、技术栈和模块命令留在项目文档中。任务实例只引用相关文件与章节，不复制长期规范。

做出五项判断

派发或实现前确认：

1. 最终交付物是什么；
2. 允许修改哪些文件或模块；
3. 哪些工作存在真实依赖，哪些可以并行；
4. 风险等级是什么；
5. 哪些验证必须在真实平台执行。

需要派发任务时，使用 templates/task-brief.md 形成唯一任务说明。不要再创建内容重复的 architecture、implementation 或 handoff 文档。

选择风险等级

取“项目最低等级、敏感路径等级、行为风险、变更规模”中的最高等级。

代码量不决定风险。credential scanner、删除逻辑、权限和原生 handle 等敏感改动即使只有一行，也按 R3 处理。

所有等级都要：

• 检查范围与基线；
• 保护用户已有修改；
• 运行与改动相关的最小验证；
• 运行 git diff --check；
• 如实报告未验证事项。

划分任务

每个子任务只包含一个明确结果、一组紧密相关文件和一套独立验收测试。保证失败后可以独立修复或拒绝，并让 reviewer 能一次理解完整 diff。

出现以下情况时拆分：

• 平台实现可以独立完成；
• 安全基础设施和业务接入混在一起；
• 文件范围不重叠且接口已经确定；
• 一个任务混合不同风险等级；
• diff 已大到难以一次审查。

出现以下情况时保持单任务：

• 同一行为只有少量紧密相关改动；
• 拆分后会频繁修改同一文件；
• 共享状态机存在严格顺序；
• 协调成本高于实现成本。

使用 Agent

只使用必要角色：

• Implementer：按 task brief 实现并验证；
• Reviewer：只读审查固定 diff；
• Fixer：仅在 reviewer 提出 finding 后修复。

执行规则：

• R0 不创建子 Agent；
• R1 默认由当前 Agent 实现，可增加一次轻量 reviewer；
• R2/R3 使用 fresh implementer 和 fresh reviewer；
• reviewer 不与 implementer 共用角色；
• 只有 finding 才创建 fixer；
• fixer 完成后必须由 fresh reviewer 复审。

模型选择规则：

• 默认不固定子 Agent 的模型或 reasoning effort，让 Codex 根据工作单元复杂度、模型 可用性、速度与成本自行选择；
• 用户、项目或任务明确指定时，严格遵循其模型与 reasoning effort；
• 安全、高风险、复杂状态机或最终裁决优先使用当前可用的高质量模型和 high reasoning； 不得以模型能力替代测试、审查或真实平台证据；
• 每次创建子 Agent 后，在下一次状态更新中报告 Agent 名称、职责，以及 spawn_agent 是否显式传入 model 和 reasoning effort；未显式传入时写明“按 Codex 配置优先级解析”， 运行时未暴露最终值时不得猜测。

只有同时满足以下条件才并行 writer：

• 使用独立 worktree；
• 修改文件不重叠；
• 公共接口已经确定；
• 每份结果可以独立测试；
• 已明确整合顺序。

否则保持单 writer。普通 implementer 不得静默改变公共接口或架构边界；先创建独立的 architecture-change 任务并取得裁决。

工作单元与可见里程碑

把一个 implementer 或 fixer 回合限制为一个明确、可返回的里程碑。不要把实现、完整 测试矩阵、re-review 和 whole-branch review 塞进同一回合；由协调者在每个返回边界 验收后再派下一角色。

按共同根因、同一文件闭包或同一验证命令对 reviewer findings 分组。单个 fixer 批次 默认最多处理 2–3 个 finding。只有不可分割的同一状态机根因才可超过，并在 task brief 中说明不可拆理由。数字是防止回合失控的默认值，不替代根因判断。

预计超过约 20–30 分钟，或无法在一个清晰测试边界返回的工作，拆成串行短里程碑。 这是规划启发式，不是硬超时。保持单 writer，不要为了显示进度而并发修改同一 worktree。

每个里程碑结束后，协调者先发布一次简短状态，再派下一角色：

当前阶段：
已完成：
验证结果：
下一步：

UI 中旧步骤没有自动刷新不等于任务停滞。必要时可一次性只读核对 task status、最新文件 时间或测试进程，但仍以角色正式返回为里程碑边界；不要定时轮询、发送心跳或频繁打断 子智能体。

本护栏只约束已启用的任务派发与协调，不强制 R0/R1 创建多 Agent，不改变模型能力， 也不引入实时监控或调度平台。

测试与审查

按三档运行测试：

1. Focused：每个子任务运行，覆盖直接行为；
2. Milestone：平台边界、状态机或产品闭环形成后运行；
3. Final：交付前运行完整矩阵。

不要在每个小修复后重复完整矩阵。只有 finding 或影响范围扩大时升级验证。

使用 templates/review-prompt.md 固定 base..head 或 patch、需求摘要和必跑验证。Reviewer 只输出带证据的 Critical、Important、Minor findings，不修改代码。没有 finding 时明确报告 0/0/0。

R3 和最终发布必须完成 whole-branch review。Final review 后不得暗改；如有修改，重新执行适用验证和 review。

管理 Git、审批与恢复

• 每个并行 writer 使用独立 worktree；
• 不覆盖 dirty 或 untracked 文件；
• 不执行 force push 或破坏性 Git；
• 临时分支可提交 checkpoint，但默认不 push；
• coordinator 验收后按依赖顺序整合；
• 项目要求单提交时，在最终 review 前 squash。

把 Windows、WSL、跨卷、签名等需要授权的操作合并为一个验证波次。同一波最多请求一次明确审批；拒绝或中止后不要循环弹窗。

仅对持续时间长、跨多个 Agent 的任务使用 templates/run-status.md。恢复时先读取该记录和 Git 状态，不重复实施已完成 SHA。

协调外部 Codex 任务时使用 wait_threads 和最新 cursor 进行阻塞等待。只处理 approval、ruling、failure 或 completion；普通进度不应让 coordinator 停止监听。

完成交付

交付前确认：

• 实际 diff 未超出允许范围；
• focused、milestone、final 验证按风险完成；
• 必要 review 已达到 0/0/0；
• 真实平台证据已取得，或明确标记为未验证；
• Git、commit 和 push 边界符合 task brief；
• 最终回复说明完成内容、验证结果、剩余风险和未完成事项。