execute

执行

目的

通过专用子 Agent，严格按照构建、评审和验证的循环推进每个步骤，以执行蓝图计划。让主对话保持精简，专注于协调和用户决策，同时由子 Agent 负责繁重的实现、评审和验证工作。确保每个步骤都符合验收标准后，再将其标记为完成并继续下一步。

努力程度

将每个阶段都视为唯一一次做好工作的机会。构建应是完整的实现，而非草稿。评审应真正严苛。验证必须运行每个工具并检查每项结果。全部三个阶段通过后，该步骤的代码应达到可用于生产的状态。

工作流

定位计划

扫描 docs/plans/ 中的计划文件。如果只有一个计划文件，就使用该文件。如果存在多个计划文件或里程碑文件夹，请向用户列出这些文件，并询问要执行哪一个。对于包含编号步骤文件的里程碑文件夹，从第一个尚未标记为已完成的步骤开始。如果用户请求中直接指定了计划文件（例如，“执行 01_milestone_name.md”），则直接使用该文件，无需询问。

开始执行前，将整个计划文件读入上下文。找出所有步骤标题、各步骤的阶段说明（阶段 1：构建、阶段 2：评审、阶段 3：验证），以及步骤之间的依赖关系。统计步骤总数，并在询问是否继续之前，告知用户计划包含多少个步骤，以及其中有多少个已标记为完成。

如果用户要求仅执行特定步骤（例如，“执行步骤 3-5”或“跳过步骤 2”），请按顺序执行指定步骤，跳过其他步骤。如果被跳过的步骤包含所请求步骤依赖的内容，请发出警告。

Git 处理

执行第一步之前，询问用户要使用哪种 Git 模式。准确提供以下两个选项：

用户管理模式：

• 每个单独步骤的三个阶段（构建、审查、验证）全部完成后暂停。
• 用户自行检查更改、暂存文件并提交。
• 不要自动创建任何提交。
• 在用户明确表示继续之前，不要恢复执行。
• 即使将多个步骤批量执行，也要在批次中的每个单独步骤完成后暂停。批次边界作为累计进度检查点——在批次的最后一步完成后提供批次摘要，但用户已在每一步完成后获得审查机会。

技能管理模式：

• 每个单独步骤通过全部三个阶段后，自动创建提交。
• 如果某一步需要人工干预（审查发现阻塞问题或验证检查失败），在干预彻底解决且该步骤通过所有剩余阶段之前，不要提交该步骤的任何更改。绝不提交未完成的步骤。
• 将计划文件的进度更新（✅ 标题前缀和已勾选的复选框）与该步骤的实现更改放在同一个提交中——不要单独提交计划进度。
• 使用清晰、描述性且符合 Conventional Commits 格式的提交消息，并注明步骤。
• 提交消息中绝不包含 Claude Code 或 AI 署名。不得添加 co-authored-by 行、机器人签名或任何形式的 AI 标记。
• 暂停节奏取决于计划复杂度：
  • 简单计划（单份文档）： 连续执行所有步骤，不暂停。计划完成后提供最终摘要。
  • 复杂计划（多份里程碑文档）： 用户选择技能管理模式后，询问要采用哪种暂停节奏：
    • 里程碑暂停（默认）：每份里程碑文档完成后暂停。提供里程碑摘要，并询问是否继续下一个里程碑。在一个里程碑内，连续执行所有步骤，不在批次边界暂停。
    • 全程自动：不暂停地执行整个计划，包括跨越里程碑边界。计划完成后提供最终摘要。

保存用户的选择（Git 模式，以及对于复杂计划的技能管理模式所选暂停节奏），并在本次执行会话的其余时间内始终如一地应用。如果用户想在会话中途切换模式，必须明确提出。每次都默认询问——绝不沿用之前会话中的模式或暂停节奏。

步骤执行

将步骤分成批次，每批最多 3 个步骤。在每个批次内，严格按顺序执行步骤：步骤 A 必须完成完整的构建、审查和验证周期，并通过全部三个阶段，之后步骤 B 才能开始构建阶段。批次内的执行顺序始终如下：

1. 步骤 A：构建 → 审查 → 验证（全部必须通过）
2. 步骤 B：构建 → 审查 → 验证（全部必须通过）
3. 步骤 C：构建 → 审查 → 验证（全部必须通过）

绝不将构建阶段、审查阶段或验证阶段集中批量执行。步骤 A 的审查或验证尚未完成时，绝不开始步骤 B 的构建。每个阶段都决定下一阶段能否开始。每个步骤都决定下一步骤能否开始。

批次完成后（批次内的所有步骤都通过了全部阶段），根据所选模式处理 git，然后向用户提供批次摘要，说明哪些步骤已完成。在用户管理模式下，每个步骤完成后都已暂停。在技能管理模式下，除非已到达暂停间隔边界（里程碑暂停的里程碑边界，或简单计划和完全自动模式的计划结束），否则继续执行下一批次。

批次绝不跨越里程碑边界。如果当前里程碑还剩 2 个步骤，且下一个里程碑还有步骤，则当前批次只包含这 2 个步骤。如果剩余步骤少于批次大小，则当前批次只包含剩余步骤。如果批次内某个步骤失败，则不执行该批次中的其余步骤——报告失败并等待指示。

子 Agent 调度

使用 Claude Code 的 Agent 工具调度子 Agent。参阅 references/subagent-prompts.md 获取准确的提示词模板。调度前，将占位符替换为实际值。

构建子 Agent 调度：

• 将计划中的步骤目标文本原样传入 {{STEP_OBJECTIVE}}。
• 将计划中的步骤验收标准列表原样传入 {{ACCEPTANCE_CRITERIA}}。
• 将计划中的 Phase 1 指示原样传入 {{PHASE_1_INSTRUCTIONS}}。
• 构建子 Agent 拥有完整的文件系统访问权限，可读取和写入文件。
• 从子 Agent 的回复中提取结构化构建摘要。

审查子 Agent 调度：

• 将计划中的步骤验收标准列表原样传入 {{ACCEPTANCE_CRITERIA}}。
• 将提取的构建摘要传入 {{BUILD_SUMMARY}}。
• 将计划中的步骤 Phase 2 指示原样传入 {{PHASE_2_INSTRUCTIONS}}。
• 审查子 Agent 会独立读取磁盘上的文件——提供构建摘要仅供其了解背景和确定关注重点，不应视为可信事实来源。
• 解析审查回复，找出阻塞性问题。

验证子 Agent 调度：

• 将计划中的步骤 Phase 3 检查清单原样传入 {{PHASE_3_CHECKLIST}}。
• 将项目的工具链配置（测试运行器、代码检查器、类型检查器命令）传入 {{TOOL_CHAIN_CONFIG}}。从计划的工具链表中提取工具链——该工具链已在规划期间由用户确认，是权威来源。如果计划没有工具链表，则从项目配置文件（pyproject.toml、package.json、Makefile 等）中检测。缓存解析出的配置，并在后续验证调度中重复使用，除非计划明确更改了工具链要求。
• 验证子 Agent 会运行实际工具，并按检查清单项目报告通过/失败。
• 解析验证回复，找出任何失败项。只要有一项检查失败，整个验证阶段就失败。

失败处理

如果审查子 Agent 返回任何阻塞性发现，请立即停止。不要继续验证。不要尝试自动修复。不要重试构建。不要提交此步骤中的任何更改。向用户完整呈现阻塞性发现，并附上文件:行号引用和说明。等待用户提供后续指示。用户可以选择：

• 手动修复问题并要求重新运行审查。
• 要求该技能根据附加指示重新运行构建。
• 跳过此步骤（标记为已跳过，而不是已完成）。
• 完全中止执行。

如果验证子 Agent 返回任何未通过的检查，请立即停止。不要继续下一步。不要尝试自动修复。不要提交此步骤中的任何更改。向用户完整呈现失败详情，包括完整错误输出。等待用户提供后续指示。可选方案与阻塞性审查发现相同。

用户解决干预事项（手动修复、重新运行构建等）后，从失败阶段开始重新运行剩余阶段。只有在所有三个阶段都顺利通过后，才提交此步骤——提交应包含最终解决状态，而非中间尝试。

建议性审查发现不会阻止执行。此步骤通过所有阶段后，将其作为提示信息告知用户。用户可以选择稍后处理或忽略。

已经通过所有三个阶段并标记为完成的步骤，即使其他步骤随后失败，也保留其勾选标记。步骤 B 失败不会撤销步骤 A 的完成状态。

进度跟踪

步骤通过所有三个阶段（构建、审查、验证）后，立即在计划文件中进行两项更新，将其标记为完成：

1. 在步骤标题前添加勾选标记。例如，将 ### Step 1: Auth middleware 改为 ### ✅ Step 1: Auth middleware。
2. 勾选已完成步骤中的所有 Markdown 复选框：将该步骤第 3 阶段验证清单（以及该步骤中的任何其他复选框）里的 - [ ] 全部改为 - [x]。

将这两项更改写入磁盘上的计划文件，以便跨会话保留进度。恢复执行时，扫描计划文件，找到第一个标题前没有 ✅ 标记的步骤，并从该步骤开始执行。

如果用户之前暂停了执行（用户管理的 Git 模式），恢复前请重新读取整个计划文件。用户可能在暂停期间编辑了计划。恢复时应遵循计划文件当前内容，无论用户是添加步骤、删除步骤、调整顺序还是修改指示。

恢复执行时修改计划

恢复执行时，务必从磁盘重新读取计划文件。切勿依赖之前会话中缓存的计划版本，也不要依赖对话早前的内容。用户可能已经：

• 根据审查发现修改步骤指示。
• 在现有步骤之间添加新步骤。
• 删除不再需要的步骤。
• 因依赖关系调整步骤顺序。
• 修改验收标准或验证清单。

恢复时原样接受计划。除非步骤依赖关系似乎已被破坏（例如，某步骤引用了已删除步骤的产物），否则不要对更改提出警告或质疑。

步骤报告

每个步骤完成全部三个阶段后，都要提供步骤报告。详细程度取决于执行模式：

• 用户管理模式（每个步骤后暂停）：提供完整的步骤报告，包含步骤标签和状态、修改的文件数、阻塞项和建议项的数量（如有建议项，简要列出）、验证结果摘要（通过 N/N 项检查），以及采取的 Git 操作（已暂停，等待用户处理）。
• 技能管理的连续模式（简单计划或全自动）：将每个步骤报告精简为一行，包含步骤标签、状态、修改的文件数、验证结果和提交哈希。运行结束时提供全面摘要。
• 技能管理的里程碑暂停模式：里程碑内的步骤采用精简的单行格式。每个暂停点都提供完整的里程碑摘要。

批次完成后，提供批次摘要，列出该批次中完成的所有步骤及累计统计数据。