implement_plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Plan

方案落地执行指南

You are tasked with implementing an approved technical plan from

thoughts/shared/plans/

. These plans contain phases with specific changes and success criteria.

你的任务是基于

thoughts/shared/plans/

中已获批的技术方案进行落地实现。这些方案包含多个阶段，每个阶段都有明确的变更要求和验收标准。

Execution Modes

执行模式

You have two execution modes:

你有两种执行模式：

Mode 1: Direct Implementation (Default)

模式1：直接执行（默认）

For small plans (3 or fewer tasks) or when user requests direct implementation.

You implement each phase yourself
Context accumulates in main conversation
Use this for quick, focused implementations

适用于小型方案（3个及以下任务）或用户要求直接执行的场景。

由你自行完成每个阶段的实现
上下文会在主对话中累积
适用于快速、聚焦的落地需求

Mode 2: Agent Orchestration (Recommended for larger plans)

模式2：Agent编排（推荐用于大型方案）

For plans with 4+ tasks or when context preservation is critical.

You act as a thin orchestrator
Agents execute each task and create handoffs
Compaction-resistant: handoffs persist even if context compacts
Use this for multi-phase implementations

To use agent orchestration mode, say: "I'll use agent orchestration for this plan" and follow the Agent Orchestration section below.

适用于包含4个及以上任务的方案，或需要严格保留上下文的场景。

你将作为轻量化编排者
由各个Agent执行具体任务并完成工作交接
抗压缩性：即使上下文被压缩，交接内容仍会保留
适用于多阶段的复杂实现

要使用Agent编排模式，请说明："I'll use agent orchestration for this plan"，并遵循下方的Agent编排章节内容。

Getting Started

开始执行

When given a plan path:

Read the plan completely and check for any existing checkmarks (- [x])
Read the original ticket and all files mentioned in the plan
Read files fully - never use limit/offset parameters, you need complete context
Think deeply about how the pieces fit together
Create a todo list to track your progress

当拿到方案路径后：

完整阅读方案内容，检查是否已有完成标记（- [x]）
阅读原始需求工单以及方案中提及的所有文件
完整读取文件内容 - 切勿使用limit/offset参数，你需要获取完整上下文
深入思考各部分内容的关联逻辑
创建待办列表跟踪执行进度

Pre-Implementation Risk Check

落地前风险检查

Before starting implementation, run a deep pre-mortem:

/premortem deep <plan-path>

This analyzes the plan against comprehensive checklists:

Technical risks (scalability, dependencies, data, security)
Integration risks (breaking changes, migration, rollback)
Process risks (unclear requirements, stakeholder input)
Testing risks (coverage gaps, load testing needs)

If HIGH severity risks are identified:

The premortem will block via AskUserQuestion
User must: accept risks explicitly, add mitigations, or research solutions
If mitigations are added, update the plan before proceeding

Skip premortem if:

Plan already has a "## Risks (Pre-Mortem)" section with mitigations
User explicitly requests to skip (
```
--skip-premortem
```
)

After premortem passes, start implementing if you understand what needs to be done.

If no plan path provided, ask for one.

在开始实现前，需执行深度预演风险分析：

/premortem deep <plan-path>

该命令会对照全面的检查清单分析方案：

技术风险（可扩展性、依赖关系、数据、安全）
集成风险（破坏性变更、迁移、回滚）
流程风险（需求不明确、相关方输入缺失）
测试风险（覆盖缺口、性能测试需求）

若识别到高优先级风险：

预演分析会通过AskUserQuestion流程暂停执行
用户需：明确接受风险、添加缓解措施，或研究解决方案
若添加了缓解措施，需先更新方案再继续执行

可跳过预演分析的情况：

方案中已包含"## Risks (Pre-Mortem)"章节且有对应的缓解措施
用户明确要求跳过（
```
--skip-premortem
```
）

预演分析通过后，若你已明确执行要求，即可开始落地实现。

若未提供方案路径，请向用户索要。

Implementation Philosophy

落地执行理念

Plans are carefully designed, but reality can be messy. Your job is to:

Follow the plan's intent while adapting to what you find
Implement each phase fully before moving to the next
Verify your work makes sense in the broader codebase context
Update checkboxes in the plan as you complete sections

When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.

If you encounter a mismatch:

STOP and think deeply about why the plan can't be followed

Present the issue clearly:

Issue in Phase [N]:
Expected: [what the plan says]
Found: [actual situation]
Why this matters: [explanation]

How should I proceed?

方案是经过精心设计的，但实际情况可能复杂多变。你的职责是：

遵循方案的核心意图，同时根据实际情况灵活调整
完成当前阶段的全部工作后再进入下一阶段
确保你的工作在整个代码库的上下文环境中合理可行
完成对应章节后更新方案中的复选框

当实际情况与方案不符时，需深入思考原因并清晰沟通。方案是你的指导，但你的判断同样重要。

若遇到不符情况：

暂停执行并深入思考方案无法落地的原因

清晰呈现问题：

第[N]阶段问题：
预期：[方案描述内容]
实际：[当前真实情况]
影响说明：[详细解释]

请问我应如何推进？

Verification Approach

验证流程

After implementing a phase:

Run the success criteria checks (usually
```
make check test
```
covers everything)
Fix any issues before proceeding
Update your progress in both the plan and your todos
Check off completed items in the plan file itself using Edit

Pause for human verification: After completing all automated verification for a phase, pause and inform the human that the phase is ready for manual testing. Use this format:

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].

If instructed to execute multiple phases consecutively, skip the pause until the last phase. Otherwise, assume you are just doing one phase.

do not check off items in the manual testing steps until confirmed by the user.

完成一个阶段的实现后：

执行验收标准中的检查项（通常
```
make check test
```
可覆盖所有内容）
解决所有问题后再继续
同时更新方案和待办列表中的进度
使用编辑功能在方案文件中标记已完成的项

等待人工验证：完成该阶段的所有自动化验证后，暂停执行并告知用户该阶段已准备好进行人工测试。请使用以下格式：

第[N]阶段已完成 - 等待人工验证

自动化验证已通过：
- [列出已通过的自动化检查项]

请执行方案中列出的人工验证步骤：
- [列出方案中的人工验证项]

请告知我人工测试完成情况，以便我推进至第[N+1]阶段。

若用户要求连续执行多个阶段，可跳过中间的等待环节，直到最后一个阶段完成后再暂停。否则，默认仅执行单个阶段。

在用户确认前，请勿标记人工测试步骤为已完成。

If You Get Stuck

遇到阻塞时的处理

When something isn't working as expected:

First, make sure you've read and understood all the relevant code
Consider if the codebase has evolved since the plan was written
Present the mismatch clearly and ask for guidance

Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.

当遇到预期外的问题时：

首先确保你已阅读并理解所有相关代码
考虑代码库是否在方案制定后有更新
清晰呈现不符情况并寻求指导

仅在必要时使用子任务 - 主要用于针对性调试或探索不熟悉的领域。

Resumable Agents

可恢复Agent

If the plan was created by

plan-agent

, you may be able to resume it for clarification:

Check
```
.claude/cache/agents/agent-log.jsonl
```
for the plan-agent entry
Look for the
```
agentId
```
field

To clarify or update the plan:

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

The resumed agent retains its full prior context (research, codebase analysis).

Available agents to resume:

```
plan-agent
```
- Created the implementation plan
```
oracle
```
- Researched best practices
```
debug-agent
```
- Investigated issues

若方案由

plan-agent

创建，你可通过恢复该Agent来获取澄清：

检查
```
.claude/cache/agents/agent-log.jsonl
```
中的plan-agent条目
找到
```
agentId
```
字段

如需澄清或更新方案：

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

恢复后的Agent会保留其全部历史上下文（研究内容、代码库分析结果）。

可恢复的Agent包括：

```
plan-agent
```
- 负责制定实现方案
```
oracle
```
- 负责研究最佳实践
```
debug-agent
```
- 负责排查问题

Resuming Work

恢复未完成的工作

If the plan has existing checkmarks:

Trust that completed work is done
Pick up from the first unchecked item
Verify previous work only if something seems off

Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum.

若方案中已有完成标记：

假设已完成的工作是正确的
从第一个未标记的项开始推进
仅在发现异常时才验证之前的工作

记住：你是在落地解决方案，而非仅仅勾选任务框。时刻牢记最终目标，保持推进节奏。

Agent Orchestration Mode

Agent编排模式

When implementing larger plans (4+ tasks), use agent orchestration to stay compaction-resistant.

在执行大型方案（4个及以上任务）时，使用Agent编排模式可确保上下文不丢失。

Why Agent Orchestration?

为什么选择Agent编排？

The Problem: During long implementations, context accumulates. If auto-compact triggers mid-task, you lose implementation context. Handoffs created at 80% context become stale.

The Solution: Delegate implementation to agents. Each agent:

Starts with fresh context
Implements one task
Creates a handoff on completion
Returns to orchestrator

Handoffs persist on disk. If compaction happens, you re-read handoffs and continue.

问题背景： 在长周期的实现过程中，上下文会不断累积。若在任务执行中途触发自动压缩，你会丢失实现上下文。在80%上下文时创建的交接内容会失效。

解决方案： 将实现工作委托给各个Agent。每个Agent：

以全新上下文启动
执行单个任务
完成后创建交接内容
返回给编排者

交接内容会持久化存储在磁盘上。即使发生上下文压缩，你也可重新读取交接内容并继续执行。

Setup

准备工作

Create handoff directory:
bash
```
mkdir -p thoughts/handoffs/<session-name>
```
Use the session name from your continuity ledger.
Read the implementation agent skill:
bash
```
cat .claude/skills/implement_task/SKILL.md
```
This defines how agents should behave.

创建交接目录：
bash
```
mkdir -p thoughts/handoffs/<session-name>
```
使用会话账本中的会话名称。
阅读实现Agent的技能文档：
bash
```
cat .claude/skills/implement_task/SKILL.md
```
该文档定义了Agent的行为规范。

Pre-Requisite: Plan Validation

前置条件：方案验证

Before implementing, ensure the plan has been validated using the

validate-agent

. The validation step is separate and should have created a handoff with status VALIDATED.

Check for validation handoff:

bash

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

If no validation exists, suggest running validation first:

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

If validation exists but status is NEEDS REVIEW, present the issues before proceeding.

在开始实现前，需确保方案已通过

validate-agent

验证。验证步骤是独立的，完成后会创建状态为VALIDATED的交接内容。

检查验证交接内容：

bash

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

若未找到验证内容，建议先执行验证：

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

若验证内容存在但状态为NEEDS REVIEW，需先向用户呈现问题再继续。

Orchestration Loop

编排循环

For each task in the plan:

Prepare agent context:
- Read continuity ledger (current state)
- Read the plan (overall context)
- Read previous handoff if exists (from thoughts/handoffs/<session>/)
- Identify the specific task

Spawn implementation 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.
  """
)

Process agent result:
- Read the agent's handoff file
- Update ledger checkbox:
```
[x] Task N
```
- Update plan checkbox if applicable
- Continue to next task
On agent failure/blocker:
- Read the handoff (status will be "blocked")
- Present blocker to user
- Decide: retry, skip, or ask user

针对方案中的每个任务：

准备Agent上下文：
- 读取会话账本（当前状态）
- 读取方案（整体上下文）
- 读取上一个交接内容（若存在，来自thoughts/handoffs/<session>/）
- 明确当前具体任务

启动实现Agent：

Task(
  subagent_type="general-purpose",
  model="claude-opus-4-5-20251101",
  prompt="""
  [粘贴.claude/skills/implement_task/SKILL.md的内容]

  ---

  ## 你的上下文

  ### 会话账本：
  [粘贴账本内容]

  ### 方案：
  [粘贴相关方案章节或完整方案]

  ### 你的任务：
  第[N]项/共[总任务数]项：[方案中的任务描述]

  ### 上一个交接内容：
  [粘贴上一个任务的交接内容，或"This is the first task - no previous handoff"]

  ### 交接目录：
  thoughts/handoffs/<session-name>/

  ### 交接文件名：
  task-[NN]-[short-description].md

  ---

  请执行你的任务并创建交接内容。
  """
)

处理Agent执行结果：
- 读取Agent创建的交接文件
- 更新账本中的复选框：
```
[x] Task N
```
- 若适用，更新方案中的复选框
- 继续执行下一个任务
Agent执行失败/遇到阻塞时：
- 读取交接内容（状态为"blocked"）
- 向用户呈现阻塞问题
- 决定：重试、跳过，或询问用户

Recovery After Compaction

上下文压缩后的恢复

If auto-compact happens mid-orchestration:

Read continuity ledger (loaded by SessionStart hook)

List handoff directory:

bash

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

Read the last handoff to understand where you were
Continue spawning agents from next uncompleted task

若在编排过程中触发自动压缩：

读取会话账本（由SessionStart钩子加载）

列出交接目录内容：

bash

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

读取最后一个交接内容，明确当前进度
从下一个未完成的任务开始，继续启动Agent

Example Orchestration Session

编排会话示例

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]
...

用户：/implement_plan thoughts/shared/plans/PLAN-add-auth.md

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

正在创建交接目录...
[创建thoughts/handoffs/add-auth/]

第1项/共6项：创建用户模型
[启动带有完整上下文的Agent]
[Agent完成任务，创建task-01-user-model.md]

✅ 第1项任务完成。交接内容：thoughts/handoffs/add-auth/task-01-user-model.md

第2项/共6项：添加认证中间件
[启动带有上一个交接内容的Agent]
[Agent完成任务，创建task-02-auth-middleware.md]

✅ 第2项任务完成。交接内容：thoughts/handoffs/add-auth/task-02-auth-middleware.md

--- 触发自动压缩 ---
[上下文被压缩，但交接内容仍保留]

Claude: [读取账本，发现任务1-2已完成]
[读取最后一个交接内容task-02-auth-middleware.md]

从第3项/共6项任务恢复执行：创建登录端点
[启动Agent]
...

Handoff Chain

交接链

Each agent reads previous handoff → does work → creates next handoff:

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)
...

The chain preserves context even across compactions.

每个Agent会读取上一个交接内容 → 执行工作 → 创建下一个交接内容：

task-01-user-model.md
    ↓ (由Agent 2读取)
task-02-auth-middleware.md
    ↓ (由Agent 3读取)
task-03-login-endpoint.md
    ↓ (由Agent 4读取)
...

该链条可在上下文压缩后仍保留执行上下文。

When to Use Agent Orchestration

何时使用Agent编排模式

Scenario	Mode
1-3 simple tasks	Direct implementation
4+ tasks	Agent orchestration
Critical context to preserve	Agent orchestration
Quick bug fix	Direct implementation
Major feature implementation	Agent orchestration
User explicitly requests	Respect user preference

场景	模式
1-3个简单任务	直接执行
4个及以上任务	Agent编排
需要保留关键上下文	Agent编排
快速修复Bug	直接执行
核心功能落地	Agent编排
用户明确要求	遵循用户偏好

Tips

注意事项

Keep orchestrator thin: Don't do implementation work yourself. Just manage agents.
Trust the handoffs: Agents create detailed handoffs. Use them for context.
One agent per task: Don't batch multiple tasks into one agent.
Sequential execution: Start with sequential. Parallel adds complexity.
Update ledger: After each task, update the continuity ledger checkbox.

保持编排者轻量化： 不要自行执行实现工作，仅负责管理Agent。
信任交接内容： Agent会创建详细的交接内容，可用于获取上下文。
单任务单Agent： 不要将多个任务批量交给一个Agent。
顺序执行： 先使用顺序执行，并行执行会增加复杂度。
更新账本： 每个任务完成后，更新会话账本中的复选框。