implement_plan

实施计划

你需要根据 thoughts/shared/plans/ 中经批准的技术计划进行实施。这些计划包含多个阶段，每个阶段都有具体的变更和成功标准。

执行模式

你有两种执行模式：

模式 1：直接实施（默认）

适用于小型计划（3 个或更少任务），或用户要求直接实施的情况。

• 你亲自实施每个阶段
• 上下文会在主对话中累积
• 适用于快速、目标明确的实施

模式 2：Agent 协调（大型计划的推荐模式）

适用于包含 4 个或更多任务的计划，或需要保留上下文的情况。

• 你作为精简的协调者
• Agent 执行每个任务并创建交接记录
• 交接记录可抵御上下文压缩：即使上下文被压缩，也会保留
• 适用于多阶段实施

若要使用 Agent 协调模式，请说：“我将为此计划使用 Agent 协调模式”，并按照下方的 Agent 协调部分操作。

---

开始

收到计划路径后：

• 完整阅读计划，并检查是否已有已勾选项（- [x]）
• 阅读原始工单及计划中提及的所有文件
• 完整阅读文件——切勿使用限制或偏移参数；你需要掌握完整上下文
• 深入思考各部分如何衔接
• 创建待办列表以跟踪进度

实施前风险检查

开始实施前，进行深入的事前验尸分析：

/premortem deep <plan-path>

该分析会根据全面的检查清单评估计划：

• 技术风险（可扩展性、依赖项、数据、安全性）
• 集成风险（破坏性变更、迁移、回滚）
• 流程风险（需求不明确、利益相关方意见）
• 测试风险（覆盖率缺口、负载测试需求）

如果发现高严重性风险：

• 事前验尸分析会通过 AskUserQuestion 阻止流程
• 用户必须：明确接受风险、补充缓解措施，或研究解决方案
• 如果新增了缓解措施，请先更新计划再继续

以下情况可跳过事前验尸分析：

• 计划已有带缓解措施的“## Risks (Pre-Mortem)”章节
• 用户明确要求跳过（--skip-premortem）

事前验尸分析通过后，如果你已了解需要完成的工作，就开始实施。

如果未提供计划路径，请索取。

实施理念

计划经过精心设计，但现实情况可能复杂。你的职责是：

• 在遵循计划意图的同时，根据实际情况调整
• 完整实施每个阶段后再进入下一阶段
• 确认你的工作与更广泛的代码库保持一致
• 完成各部分后，更新计划中的复选框

如果实际情况与计划不完全一致，请思考原因并清楚说明。计划是你的指引，但也需要运用自己的判断。

如果遇到不一致：

• 停下来，深入思考为何无法遵循计划
• 清楚地说明问题：

  Issue in Phase [N]:
  Expected: [what the plan says]
  Found: [actual situation]
  Why this matters: [explanation]
  
  How should I proceed?
  

验证方法

完成一个阶段后：

• 运行成功标准中的检查（通常 make check test 涵盖所有内容）
• 修复所有问题后再继续
• 同时更新计划和待办事项中的进度
• 使用 Edit 在计划文件中勾选已完成的项目
• 暂停以供人工验证：完成某阶段的所有自动化验证后，暂停并告知用户该阶段已准备好进行手动测试。使用以下格式：

  Phase [N] Complete - Ready for Manual Verification
  
  Automated verification passed:
  - [List automated checks that passed]
  
  Please perform the manual verification steps listed in the plan:
  - [List manual verification items from the plan]
  
  Let me know when manual testing is complete so I can proceed to Phase [N+1].
  

如果用户要求连续执行多个阶段，则跳过中途暂停，直到最后一个阶段。否则，默认只执行一个阶段。

在用户确认之前，不要勾选手动测试步骤中的项目。

遇到阻碍时

如果遇到问题：

• 首先，确认你已阅读并理解所有相关代码
• 考虑代码库是否已在计划编写后发生变化
• 清楚地说明不一致之处并请求指导

谨慎使用子任务——主要用于有针对性的调试或探索不熟悉的领域。

可恢复的 Agent

如果计划由 plan-agent 创建，你或许可以恢复它以进行澄清：

1. 检查 .claude/cache/agents/agent-log.jsonl 中的 plan-agent 条目
2. 查找 agentId 字段
3. 若要澄清或更新计划：

   Task(
     resume="<agentId>",
     prompt="Phase 2 isn't matching the codebase. Can you clarify..."
   )
   

恢复的 Agent 会保留此前的完整上下文（研究、代码库分析）。

可恢复的 Agent：

• plan-agent - 创建了实施计划
• oracle - 研究了最佳实践
• debug-agent - 调查了问题

恢复工作

如果计划中已有勾选项：

• 相信已完成的工作确实已经完成
• 从第一个未勾选的项目开始
• 只有在发现异常时才验证之前的工作

请记住：你是在实施解决方案，而不只是在勾选项目。牢记最终目标，并保持推进。

---

Agent 编排模式

实施较大型计划（4 项以上任务）时，使用 Agent 编排以抵御上下文压缩。

为什么要进行 Agent 编排？

问题： 在长期实施过程中，上下文会不断累积。如果自动压缩在任务中途触发，你会丢失实施上下文。在上下文使用量达到 80% 时创建的交接内容会过时。

解决方案： 将实施工作委派给 Agent。每个 Agent 都会：

• 从全新的上下文开始
• 实施一项任务
• 完成后创建交接记录
• 返回编排器

交接记录会持久保存在磁盘上。如果发生压缩，你可以重新读取交接记录并继续。

设置

1. 创建交接记录目录：

   mkdir -p thoughts/handoffs/<session-name>
   

   使用连续性记录中的会话名称。

2. 阅读实施 Agent 技能说明：

   cat .claude/skills/implement_task/SKILL.md
   

   其中定义了 Agent 应如何行动。

前置要求：计划验证

实施之前，请确保已使用 validate-agent 验证计划。验证步骤是独立的，并且应该已创建状态为 VALIDATED 的交接记录。

检查验证交接记录：

ls thoughts/handoffs/<session>/validation-*.md

如果不存在验证记录，建议先运行验证：

"This plan hasn't been validated yet. Would you like me to spawn validate-agent first?"

如果验证记录存在，但状态为 NEEDS REVIEW，请在继续之前说明问题。

编排循环

对于计划中的每项任务：

1. 准备 Agent 上下文：

   • 阅读连续性记录（当前状态）
   • 阅读计划（整体上下文）
   • 阅读先前的交接记录（如果存在，位于 thoughts/handoffs//）
   • 确认具体任务

2. 启动实施 Agent：

   Task(
     subagent_type="general-purpose",
     model="claude-opus-4-5-20251101",
     prompt="""
     [Paste contents of .claude/skills/implement_task/SKILL.md here]
   
     ---
   
     ## Your Context
   
     ### Continuity Ledger:
     [Paste ledger content]
   
     ### Plan:
     [Paste relevant plan section or full plan]
   
     ### Your Task:
     Task [N] of [Total]: [Task description from plan]
   
     ### Previous Handoff:
     [Paste previous task's handoff content, or "This is the first task - no previous handoff"]
   
     ### Handoff Directory:
     thoughts/handoffs/<session-name>/
   
     ### Handoff Filename:
     task-[NN]-[short-description].md
   
     ---
   
     Implement your task and create your handoff.
     """
   )
   

3. 处理 Agent 结果：

   • 阅读 Agent 的交接记录文件
   • 更新记录中的复选框：[x] 任务 N
   • 如适用，更新计划中的复选框
   • 继续下一项任务

4. Agent 失败或遇到阻碍时：

   • 阅读交接记录（状态将为“blocked”）
   • 向用户说明阻碍
   • 决定：重试、跳过或询问用户

压缩后的恢复

如果编排过程中发生自动压缩：

1. 阅读连续性记录（由 SessionStart 钩子加载）
2. 列出交接记录目录：

   ls -la thoughts/handoffs/<session-name>/
   

3. 阅读最后一份交接记录，了解当前进度
4. 从下一项未完成的任务开始继续启动 Agent

编排会话示例

User: /implement_plan thoughts/shared/plans/PLAN-add-auth.md

Claude: I'll use agent orchestration for this plan (6 tasks).

Setting up handoff directory...
[Creates thoughts/handoffs/add-auth/]

Task 1 of 6: Create user model
[Spawns agent with full context]
[Agent completes, creates task-01-user-model.md]

✅ Task 1 complete. Handoff: thoughts/handoffs/add-auth/task-01-user-model.md

Task 2 of 6: Add authentication middleware
[Spawns agent with previous handoff]
[Agent completes, creates task-02-auth-middleware.md]

✅ Task 2 complete. Handoff: thoughts/handoffs/add-auth/task-02-auth-middleware.md

--- AUTO COMPACT HAPPENS ---
[Context compressed, but handoffs persist]

Claude: [Reads ledger, sees tasks 1-2 done]
[Reads last handoff task-02-auth-middleware.md]

Resuming from Task 3 of 6: Create login endpoint
[Spawns agent]
...

交接链

每个 Agent 都会读取先前的交接记录 → 执行工作 → 创建下一份交接记录：

task-01-user-model.md
    ↓ (read by agent 2)
task-02-auth-middleware.md
    ↓ (read by agent 3)
task-03-login-endpoint.md
    ↓ (read by agent 4)
...

即使发生上下文压缩，这条链也能保留上下文。

何时使用 Agent 编排

场景	模式
1-3 项简单任务	直接实施
4 项以上任务	Agent 编排
需要保留关键上下文	Agent 编排
快速修复错误	直接实施
实施重大功能	Agent 编排
用户明确提出要求	尊重用户偏好

提示

• 让编排器保持精简： 不要亲自实施。只负责管理 Agent。
• 相信交接记录： Agent 会创建详细的交接记录。利用它们获取上下文。
• 每项任务使用一个 Agent： 不要把多项任务合并交给一个 Agent。
• 按顺序执行： 从顺序执行开始。并行执行会增加复杂度。
• 更新记录： 每项任务完成后，更新连续性记录中的复选框。