run-plan

运行计划

加载书面计划文档，进行严格审查，然后通过工作者-验证者循环，按依赖顺序执行任务。

核心原则

不要盲目遵循计划。如果计划有问题，先指出再执行。但如果计划清晰，就忠实地执行。

硬性门槛

1. 先阅读并审查计划。 执行前务必审查完整计划。
2. 标准具有约束力；步骤是执行路径。 绝不跳过任务或更改其验收标准。步骤与实际情况一致时，按原文执行；如果实际情况与某一步骤矛盾（锚点已过时、符号已重命名、API 已变更），工作者应做出最小调整以满足标准，并报告偏差。禁止静默偏离；也禁止因计划中的执行路径过时而导致任务失败。
3. 绝不跳过验证。 必须执行计划中列出的测试运行、预期输出检查及其他验证。
4. 可并行的任务必须始终并行执行。 没有依赖关系且不会修改相同文件的任务，必须同时派发。禁止将它们按顺序分组执行。
5. 工作者和验证者必须由不同子 Agent 担任。 主 Agent 不得直接承担工作者或验证者的职责。必须通过 Agent 工具将两者分别派发为独立子 Agent。
6. 验证者不得接收工作者的输出。 验证者子 Agent 只能接收计划中的任务目标和验收标准。绝不得向其提供工作者的差异、日志或实现细节。验证者应通过阅读代码并独立运行测试来进行判断。
7. 遇到阻碍时停止。 不要猜测。向用户提问。

适用场景

• 使用 plan-crafting 技能制定计划之后
• 用户说“运行此计划”或“执行计划”时
• 计划文档已存在且应开始实施时

不适用场景

• 尚无计划文档时（先使用 plan-crafting）
• 工作范围仍不明确时（返回 clarification 技能）
• 无需计划的单步骤任务

流程

步骤 0：项目能力发现

审查计划之前，先发现项目提供了哪些验证和执行能力：

1. 验证基础设施 — 阅读计划的 Verification Strategy 标题。如果存在，则使用其中的策略。如果不存在，则按 plan-crafting 中相同的方式进行发现：

   • 端到端测试 → 集成测试 → 验证技能/Agent → 测试套件 → 构建 + lint
   • 记录发现的命令，供 E2E 门槛（步骤 3）使用

2. 可用的 Agent 和技能 — 扫描项目级 Agent（.claude/agents/）、插件 Agent 和项目技能（.claude/skills/），以供工作者使用。如果计划在任务步骤中引用了特定 Agent，应在开始执行前确认其存在。

3. 如果引用的 Agent/技能缺失： 通知用户。不要因此阻止执行 — 工作者可以不使用该 Agent，直接执行步骤。

步骤 1：加载并审查计划

1. 阅读计划文件
2. 严格审查：
   • 任务依赖关系是否正确？
   • 文件路径是否存在？
   • 步骤中是否有占位符？
   • 每个任务是否都有目标和可通过二元判断的验收标准？（如果没有，就无法填写验证者约定 — 返回 plan-crafting）
   • 是否有任何不明确之处？
3. 如果发现问题：开始前通知用户
4. 如果没有问题：通过 TaskCreate 创建任务并继续

步骤 2：任务执行循环

每个任务都要经过 合规性检查 → 工作者实施 → 验证者审查 循环。如果验证者拒绝，则将反馈发送给工作者重新实施。

digraph task_loop {
    rankdir=TB;
    "Compliance check (subagent)" [shape=box];
    "Worker implements (subagent)" [shape=box];
    "Validator reviews (subagent)" [shape=box];
    "Pass?" [shape=diamond];
    "Task complete" [shape=doublecircle];

    "Compliance check (subagent)" -> "Worker implements (subagent)";
    "Worker implements (subagent)" -> "Validator reviews (subagent)";
    "Validator reviews (subagent)" -> "Pass?";
    "Pass?" -> "Task complete" [label="Pass"];
    "Pass?" -> "Worker implements (subagent)" [label="Fail\nfeedback delivered"];
}

对于每个任务，执行以下循环：

2-1. 合规性检查（子 Agent）

开始任务前，确认当前任务符合计划要求：

• 将计划中定义的步骤与当前文件状态进行对比
• 确认前置任务的输出已按预期存在
• 确认所有依赖任务均已完成
• 确认没有其他任务正在修改同一文件

如果发现问题：通知用户并在继续之前解决。

2-2. Worker 实施（子 Agent，通过 Agent 工具）

通过 Agent 工具派发子 Agent（worker），执行任务步骤：

• 当步骤与实际代码库相符时，worker 按照原文执行
• **有限范围内的调整：**当某个步骤与实际情况矛盾时（锚点已过时、符号已重命名、API 形式与计划中的代码块不同），worker 应以最小幅度调整执行路径，同时满足任务的目标和验收标准，并在报告中记录偏差
• **调整限制——如果修复需要执行以下操作，应停止并向主 Agent 报告，而不是自行调整：**更改其他任务会使用的接口、触及任务「文件」列表之外的文件，或更改验收标准。这些属于计划缺陷，而非执行路径偏差，应由主 Agent 按照计划修订协议处理（见 2-3）
• worker 执行每个步骤的验证（运行测试等）
• **如果计划为某个步骤指定了项目 Agent 或技能，**worker 应通过 Agent 工具或 Skill 工具使用它。如果该 Agent 或技能不可用，则直接执行该步骤。
• worker 向主 Agent 报告结果
• 主 Agent 不得在自身流程中代替 worker 执行其工作——必须始终派发子 Agent

2-3. 验证者审查（子 Agent，通过 Agent 工具——信息隔离）

通过 Agent 工具派发另一个独立的子 Agent（validator）。validator 在信息隔离环境下工作——它只知道任务本应实现的目标，不知道 worker 做了什么或如何实现。

构建 validator 提示词：

主 Agent 不得自由撰写 validator 提示词。使用以下固定模板，只填写计划文档中逐字复制的四个指定字段。不得改写、总结，也不得添加模板未要求的上下文。

You are an independent validator. You have no knowledge of how this task
was implemented. Your job is to judge whether the codebase currently meets
the goal described below, by reading files and running tests yourself.

## Task Goal

{TASK_GOAL}
— Copy the task's goal statement verbatim from the plan.

## Acceptance Criteria

{ACCEPTANCE_CRITERIA}
— Copy the task's acceptance criteria verbatim from the plan.
  Each criterion is a concrete, verifiable condition.

## Files To Inspect

{FILE_LIST}
— Copy the list of files this task is expected to create or modify,
  as listed in the plan.

## Test Commands

{TEST_COMMANDS}
— Copy any test execution commands or verification steps
  specified in the plan for this task.

## Your Review Process

1. Read each file in the file list directly from disk.
2. For each acceptance criterion, determine whether it is met
   based on what you see in the code. Record PASS or FAIL per criterion —
   binary only, no "partially met".
3. Run every test command listed above. Record results.
4. Note (do not judge) residual issues you happen to see: placeholder
   code (TODO, FIXME, stubs), debug code, commented-out blocks.

## Your Output

Verdict = AND of all acceptance criteria and listed tests.
PASS only if every criterion is met and every listed test passes.
Anything less is FAIL — no partial credit, no "close enough".

- If PASS: confirm which criteria were verified and which tests passed.
- If FAIL: list exactly which criteria failed and why, with file paths
  and line numbers. Do not suggest fixes — only describe what is wrong.
- Residual issues from step 4 are advisory findings appended to the
  report. They do not affect the verdict.

**验证层级分离：**validator 只根据该任务的约定进行判断——其验收标准和列出的测试命令。它不运行完整测试套件；跨任务回归检查只在端到端验证关卡（步骤 3）进行一次，而不是针对每个任务重复执行。

validator 提示词中不得包含的内容：

• worker 的差异、日志、输出或回复
• worker 的实现方法或策略
• 主 Agent 的任何改写或总结——模板中只能填写计划原文
• 暗示 worker 采用了何种方法的措辞（例如「检查重构是否正确完成」会泄露已执行重构这一信息）

**使用固定模板的原因：**主 Agent 已看过 worker 的输出，可能会无意识地根据 worker 的实际操作来描述 validator 的任务。固定模板可消除此信息渠道——validator 只能看到计划的原始规范，而看不到主 Agent 在 worker 完成工作后的理解。 验证结果：

• 通过： 将任务标记为已完成，并转到下一个任务
• 未通过 — 重试前先进行分类。 首先对失败进行分类：
  • 执行者缺陷 — 计划正确，但代码未达到要求：将验证器的反馈交给执行者，并返回步骤 2-2 重新实现。反馈应为验证器自己的评估——不要加入主 Agent 的解读。第二次及之后重试时，提供此任务此前的所有验证器反馈（累积内容，原文照录），而不仅是最新反馈——重复失败往往存在只有跨多次尝试才能发现的共同根因。
  • 计划缺陷 — 按照计划编写的代码无法满足计划要求：例如方案不可行、计划遗漏了依赖项、接口理解有误，或某项标准与已核实的代码库实际情况相矛盾。不要让执行者基于有问题的计划重试——请调用下方的计划修订协议。

重试上限： 如果同一任务连续失败 3 次（包括执行者重试和计划修订），请向用户报告情况并请求介入。

计划修订协议（针对计划缺陷）：

当分类结果为计划缺陷，或执行者无法继续适应时，触发此协议。

1. 对照代码库进行诊断。 阅读与计划相矛盾的实际状态；准确找出哪些任务字段（步骤、文件、依赖项、标准）有误。
2. 直接修订计划文档——仅修改受影响的任务，且不得超出计划的目标和工作范围。在计划文件底部的 ## Plan Amendment Log 部分追加一条记录，说明修改内容、原因以及触发此次修订的任务。修订必须写入文件，不能只留在对话记忆中——后续任务的合规检查和审查工作都会读取计划文件，因此不修订文件就会造成偏差。
3. 标准保护（防止钻空子）： 只有当验收标准在事实上已过时（例如命令更名、文件移位）时，才可以更正标准——更正后的标准必须验证与原标准相同的结果。绝不能因为实现未能通过标准就降低、放宽或删除标准——这是奖励欺骗，而二元判定的存在正是为了发现此类问题。如果某项标准对目标的描述确实有误，请上报用户：这是范围决策，不是计划修订。
4. 重新运行合规检查（2-1），然后针对修订后的任务派发新的执行者。
5. 计划修订计入任务的 3 次尝试上限。任务需要反复修订说明规划失败——应升级处理，而不是第三次修订。

并行执行规则（硬性门槛 #4）：

能够并行执行的任务必须并行派发。禁止按顺序逐个执行这类任务。

并行执行条件（必须全部满足）：

• 不依赖其他任务
• 不修改同一文件
• 不更改共享状态（数据库架构、配置文件等）

并行执行时：

• 为每项任务派发一个独立的“执行者子 Agent”
• 每个执行者完成后，派发一个独立的“验证器子 Agent”进行审查
• 所有并行任务完成后，汇总结果，再继续下一个有依赖关系的任务

并行任务的提交协议： 并行派发的执行者不得执行其任务的提交步骤——在共享工作树中并发执行 git add/git commit 会在 Git 索引上发生竞争，并可能导致不同任务的暂存内容交错。因此，每项任务通过验证后，由主 Agent 按顺序仅暂存该任务的文件（依据计划中的 Files 列表），并创建该任务的提交。按顺序执行的任务则按计划中的说明提交。

以下情况必须按顺序执行：

• 有明确依赖关系的任务（须等前置任务完成后再执行）
• 修改同一文件的任务（必须按顺序执行）

步骤 3：端到端验证关卡

所有任务完成后（包括存在时的最终验证任务），将最高级别的验证作为独立关卡运行：

1. 运行在步骤 0 中发现的验证命令（或计划中的验证策略）
2. 运行完整测试套件，检查是否存在回归
3. 确认已满足所有计划成功标准

如果全部通过： 向用户报告成功摘要。

如果端到端验证失败 — 失败处理流程：

端到端关卡失败意味着各个任务通过了各自的验证，但整个系统无法正常工作。这是集成问题，不是任务级问题。

1. 诊断（尝试 1）：

   • 仔细阅读失败输出
   • 找出哪些任务之间的交互可能导致了失败
   • 派遣工作子 Agent 实施有针对性的修复（范围限定在已诊断出的交互上）
   • 重新运行端到端验证命令

2. 重新诊断（尝试 2）：

   • 如果有针对性的修复未能解决问题，请重新阅读失败输出
   • 检查是否存在不同的根本原因（首次诊断可能有误）
   • 实施第二项有针对性的修复
   • 重新运行端到端验证命令

3. 升级并告知用户（尝试 2 次失败后）：

   • 报告：端到端验证测试的内容、失败之处、已尝试的修复，以及当前的推测
   • 由用户决定：继续调试、重新规划特定任务，或接受部分完成
   • 不要默默地继续重试 — 最多尝试 2 次，之后必须升级处理

何时停止

出现以下情况时，立即停止执行并向用户寻求帮助：

• 遇到阻碍（缺少依赖项、测试失败、指令不明确）
• 计划存在妨碍执行的关键缺漏
• 不理解某项指令
• 验证反复失败

请先请求澄清，不要猜测。

验证器检查清单

每项任务完成后，验证以下内容：

• 是否满足每项验收标准？（每项标准均为二元判断 — 最终结论取所有标准的 AND）
• 任务列出的测试命令是否通过？
• 是否创建或修改了指定文件？
• 是否创建了提交？（由工作者创建；并行任务则由主 Agent 创建）

验证器不会检查代码是否严格按照计划中的步骤实现 — 工作者可能调整了实现路径。验收标准才是约定。

反模式

反模式	失败原因
未审查计划就执行	计划中的错误会传导至实现
跳过验证步骤	错误不断累积，后续调试成本上升
遇到阻碍时猜测	偏离规范，需要返工
并行运行无法并行的任务	文件冲突、依赖关系混乱
顺序运行可并行的任务	浪费时间，造成不必要的执行延迟
每个并行工作者都运行 git commit	Git 索引竞争；交错暂存会将多个任务混入同一次提交
因行锚点已过时而让工作者判定任务失败	验收标准才是约定，执行路径不是；应调整并报告，而非判失败
工作者悄悄偏离计划却不报告	主 Agent 会失去审计轨迹；验证者可能会通过计划从未要求的代码
验证者为每项任务运行完整测试套件	会重复运行 N 次测试套件；回归检查应属于 E2E 门禁，运行一次即可
遇到计划缺陷导致的失败时重试工作者	在不可能完成的任务上耗尽重试预算；应先分诊，再修订计划
弱化验收标准，让失败的实现也能通过	这是奖励作弊——设置二元判定正是为了发现问题，而不是迁就问题
只在对话中修订计划，却不修改计划文件	后续合规检查和审查工作会读取该文件；文件未修订就意味着出现了无声偏移
主 Agent 在同一流程中承担工作者／验证者角色	破坏独立验证；造成确认偏误
将工作者的输出传给验证者	验证者会受工作者的表述方式影响，而不是独立判断
不使用固定模板，自行撰写验证者提示词	主 Agent 会在措辞和表述框架中无意识地泄露工作者的上下文
不将计划逐字复制到模板中，而是改述计划	改述会经过主 Agent 在工作完成后的理解过滤，从而引入偏见
未经用户明确同意就在 main/master 上开始实现	未经明确批准，禁止这样做
因为各项任务都已通过而跳过 E2E 门禁	任务级通过 ≠ 系统级通过；集成错误会隐藏在任务之间
未向用户升级处理便重试 E2E 失败超过两次	浪费预算；用户可能了解根本原因的相关背景

转换

计划执行完毕后：

• 要结束工作分支 → 向用户报告结果并建议后续步骤
• 如果需要独立验证 → 建议切换到 review-work 技能
• 如果执行过程中发现歧义 → 返回 clarification 技能进行处理
• 如果计划本身需要修改 → 返回 plan-crafting 技能进行修订

此技能本身**不会调用下一个技能。**它会在报告执行结果后结束，由用户选择下一步。