⚡

编写实施计划技能Skill writing-implementation-plans

编写实施计划技能用于为软件开发项目创建详细的实施指南，包含文件路径、代码示例和验证步骤，帮助工程师零代码库背景快速上手。关键词：实施计划、软件开发、代码示例、测试验证、工程师指南、项目任务分解、验收标准覆盖。

其他 0 次安装 0 次浏览 更新于 3/8/2026

name: writing-implementation-plans description: 当设计完成且需要为零代码库背景的工程师提供详细实施任务时使用 - 创建全面的实施计划，包含确切的文件路径、完整的代码示例和验证步骤，假设工程师具有最小的领域知识 user-invocable: false

编写实施计划

概述

编写全面的实施计划，假设工程师对我们的代码库零背景且品味可疑。记录他们需要知道的一切：每个任务要接触的文件、代码、可能需要检查的测试和文档、如何验证。以小块任务的形式提供整个计划。保持DRY（不要重复自己）。YAGNI（你不会需要它）。频繁提交。

假设他们是熟练的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太了解好的测试设计。

开始时宣布： “我正在使用writing-implementation-plans技能来创建实施计划。”

保存计划到： docs/implementation-plans/YYYY-MM-DD-<feature-name>/phase_##.md

关键点：设计计划提供方向，而非代码

设计计划故意保持高层次。 它们描述组件、模块和契约——而非实施代码。这是有意为之的。

你必须基于代码库调查生成新代码。 不要从设计文档复制代码。即使设计计划包含代码示例（不应该，但有些可能），将其视为仅作说明。

为什么这很重要：

  • 设计计划可能已过时数天或数周
  • 代码库状态在设计和实施之间变化
  • 调查揭示实际模式、依赖和约束
  • 你的代码必须与当前代码库配合工作

设计计划告诉你去哪里。代码库调查告诉你如何从当前位置到达那里。

开始前

必需：验证范围和代码库状态

1. 范围验证

计算设计计划中的阶段/任务数。

如果设计计划有 >8 个阶段： 停止。拒绝继续。

告诉用户： "此设计有[N]个阶段，超过了实施计划的8阶段限制。请重新运行此技能，范围不超过8个阶段。你可以：

  1. 选择前8个阶段用于此实施计划
  2. 将设计分解为多个实施计划
  3. 简化设计以适配8个阶段"

如果已在实施第9+阶段： 用户应在界定下一批时提供之前的实施计划作为上下文。

2. 审查模式选择

范围验证后，询问如何处理阶段审查：

使用AskUserQuestion：

问题："你希望如何审查实施计划的阶段？"
选项：
  - "将所有阶段写入磁盘，我之后审查"
  - "在写入前交互审查每个阶段"

跟踪此选择 - 它影响每阶段工作流程。

3. 代码库验证

你必须在每个阶段前验证当前代码库状态。使用codebase-investigator来验证假设并确保当前状态与你想要写出的内容一致。

你在写入任何任务前必须验证当前代码库状态。

不要自己验证代码库。使用codebase-investigator代理。

向代理提供设计假设，以便报告差异：

派遣一个子代理codebase-investigator来理解此项目的测试行为。

  • 不要规定关于测试的新要求。遵循代码库的做法。
    • 例如：除非你理解问题范围主要是功能性的，或收到人类指示，否则不要强制要求TDD，并且不要假设模拟数据库或其他外部依赖是可接受的。
  • 如果发现难以用模拟隔离测试的问题，应向人类操作员提出问题，询问他们希望如何继续。
  • 指示子代理查找包含测试行为、逻辑和方法细节的CLAUDE.md或AGENTS.md文件，并包括文件引用，以便你在计划中提供给执行者传递给其子代理。

派遣第二个子代理codebase-investigator（同时）并附带：

  • “设计假设这些文件存在：[列出设计中的预期路径/结构]”
  • “验证每个文件是否存在并报告与这些假设的任何差异”
  • “设计说[功能]在[位置]实施。验证这是准确的”
  • “设计期望[依赖]版本[X]。检查实际安装版本”

向代理查询的示例：

来自docs/plans/YYYY-MM-DD-feature-design.md的设计假设：
- 认证服务在src/services/auth.ts中，带有login()和logout()函数
- 用户模型在src/models/user.ts中，带有email和password字段
- 测试文件在tests/services/auth.test.ts
- 使用bcrypt依赖进行密码哈希

验证这些假设并报告：
1. 存在什么 vs 设计期望什么
2. 任何结构差异（不同路径、函数、导出）
3. 任何缺失或额外组件
4. 当前依赖版本

审查调查者发现并记录与设计假设的任何差异。

基于调查者报告，永远不要写：

  • “更新index.js如果存在”
  • “修改config.py（如果存在）”
  • “创建或更新types.ts”

基于调查者报告，总是写：

  • “创建src/auth.ts”（调查者确认不存在）
  • “修改src/index.ts:45-67”（调查者确认存在，检查了行号）
  • “无需更改config.py”（调查者确认已正确）

如果代码库状态与设计假设不同： 记录差异并相应调整实施计划。

4. 外部依赖研究

当阶段涉及外部库或依赖时，在写入任务前研究它们。

使用分层方法—从文档开始，仅在需要时升级到源代码。

第1层：互联网研究员（默认）

使用internet-researcher用于：

  • 官方文档和API参考
  • 常见使用模式和示例
  • 标准规范（OAuth2、JWT、HTTP等）
  • 最佳实践和已知陷阱

这处理约80%的外部依赖问题。 大多数集成工作遵循记录的模式。

第2层：远程代码研究员（升级）

使用remote-code-researcher当：

  • 文档未覆盖你的边缘情况
  • 你需要了解内部实施以进行扩展/定制
  • 文档描述什么但你需要知道如何
  • 行为与文档不同，你需要地面真相
  • 你正在扩展或钩入库内部

决策框架

阶段涉及外部依赖？
├─ 否 → 仅codebase-investigator
└─ 是 → 我们需要知道什么？
    ├─ API使用，标准模式 → internet-researcher
    ├─ 标准/规范实施 → internet-researcher
    ├─ 实施内部，扩展点 → remote-code-researcher
    └─ 本地状态 + 外部信息 → combined-researcher

何时派遣

当阶段提到时派遣internet-researcher：

  • 要集成的外部包/库
  • 要调用的第三方API
  • 要实施的标准（OAuth、JWT、OpenAPI等）

升级到remote-code-researcher当：

  • Internet-researcher返回"文档未覆盖此"
  • 任务需要扩展库行为
  • 任务需要匹配不在文档中的内部模式
  • 你需要了解错误处理、边缘情况或内部

报告发现

在代码库验证旁包括外部研究发现：

**外部依赖调查发现：**
- ✓ Stripe SDK使用`stripe.customers.create()`带参数：{email, name, metadata}
- ✓ OAuth2刷新流程 per RFC 6749 Section 6
- ✗ 设计假设同步API，但库仅支持异步
- + 错误处理使用类型化异常层次结构（StripeError子类）
- 📖 来源：[官方文档 | RFC规范 | 源代码@提交]

标准 vs 实施： 标准问题（例如，“OAuth2如何工作”）是internet-researcher领域。实施问题（例如，“auth0-js如何存储令牌”）可能需要remote-code-researcher。

小块任务粒度

每个步骤是一个动作（2-5分钟）。

对于功能任务：

  • “编写失败的测试” - 步骤
  • “运行它以确保失败” - 步骤
  • “实施最小代码以使测试通过” - 步骤
  • “运行测试并确保通过” - 步骤
  • “提交” - 步骤

对于基础设施任务：

  • “创建配置文件” - 步骤
  • “验证其工作（安装、构建、运行）” - 步骤
  • “提交” - 步骤

任务依赖必须明确且顺序化：

  • 任务N需要辅助函数？任务N-1创建它。
  • 任务N需要引导凭据？先前任务提供它们。
  • 永远不要编写假设"这将以某种方式存在"的代码。

任务类型：基础设施 vs 功能

匹配任务结构到设计阶段指定的内容。

设计计划区分基础设施阶段（操作验证）和功能阶段（测试验证）。你的实施任务必须尊重此区别。

阶段类型 任务结构 验证
基础设施 创建文件、配置、操作验证 命令成功（安装、构建、运行）
功能 编写测试、实施、验证测试通过 测试通过以验证行为

基础设施任务（项目设置、配置文件、依赖）：

  • 不要在脚手架上强制TDD
  • 验证 = 操作成功
  • "npm install 成功"是有效验证
  • 验证：无 — 明确说明此点，不要为设置阶段发明验收标准

功能任务（做某事的代码）：

  • 测试是伴随代码的交付物
  • 每个任务列出它验证的验收标准（例如，“验证：AC1.1, AC1.3”）
  • 测试必须验证那些特定的验收标准案例，而不仅仅是"测试代码"
  • 阶段结束于所有验收标准列出的测试通过

测试行为，而非实施。

  • 测试你的函数产生正确的输出，而不是它以某种方式调用依赖
  • 如果你重构了内部但行为保持不变，测试仍会通过吗？如果否，你在测试实施细节。
  • 验收标准是规格："无效密码返回401"意味着测试响应，而不是验证调用了bcrypt.compare()

什么不需要测试：

  • 类型（TypeScript编译器验证这些）
  • 有自己测试的依赖（不要通过你的代码重新测试它们）
  • 如何调用事物（测试结果，而不是接线）
  • 基础设施/设置（操作验证）

子组件任务分组。 设计计划将阶段结构化为子组件：类型 → 实施 → 测试。当为子组件编写任务时，用子组件标记包裹它们（见"任务和子组件标记"部分）：

<!-- START_SUBCOMPONENT_A (tasks 1-3) -->
<!-- START_TASK_1 -->
### 任务1: TokenPayload类型和TokenConfig
...
<!-- END_TASK_1 -->

<!-- START_TASK_2 -->
### 任务2: TokenService实施
...
<!-- END_TASK_2 -->

<!-- START_TASK_3 -->
### 任务3: TokenService测试
...
<!-- END_TASK_3 -->
<!-- END_SUBCOMPONENT_A -->

执行代理使用这些标记来识别相关任务。测试任务证明子组件工作。

阅读设计计划的"完成时"部分。 如果它说"构建成功"，不要发明单元测试。如果它说"X的测试通过"，确保任务产生那些测试。

计划文档头部

每个计划阶段文档必须以这个头部开始：

# [功能名称] 实施计划

**目标：** [一句话描述这构建了什么]

**架构：** [2-3句话关于方法]

**技术栈：** [关键技术/库]

**范围：** 来自原始设计的[N]个阶段（如果部分实施，则阶段[X-Y]）

**代码库已验证：** [验证日期/时间]

---

## 验收标准覆盖

此阶段实施和测试：

### {slug}.AC1: [来自设计标准的标题]
- **{slug}.AC1.1 成功：** [从设计计划逐字复制]
- **{slug}.AC1.3 失败：** [从设计计划逐字复制]

### {slug}.AC2: [来自设计标准的标题]
- **{slug}.AC2.1 成功：** [从设计计划逐字复制]

---

验收标准覆盖规则：

  • 从设计计划逐字复制验收标准文本—不要释义
  • 使用完整的范围化验收标准标识符（例如，oauth2-svc-authn.AC1.1），而非裸AC1.1
  • 仅包括此阶段实施和测试的验收标准
  • 包括标准标题（{slug}.AC1）和特定案例（{slug}.AC1.1, {slug}.AC1.3）
  • 此阶段的任务必须产生验证这些特定案例的测试
  • 验收标准案例可能出现在多个阶段中，如果部分解决，但最终阶段必须完成它

任务和子组件标记

用HTML注释标记包裹每个任务和子组件 以在实施期间实现高效解析。

任务标记

每个任务必须被包裹：

<!-- START_TASK_1 -->
### 任务1: [任务名称]
...任务内容...
<!-- END_TASK_1 -->

<!-- START_TASK_2 -->
### 任务2: [任务名称]
...任务内容...
<!-- END_TASK_2 -->

子组件标记

当任务形成逻辑子组件时（例如，类型 → 实施 → 测试），包裹组：

<!-- START_SUBCOMPONENT_A (tasks 3-5) -->
<!-- START_TASK_3 -->
### 任务3: TokenService类型
...
<!-- END_TASK_3 -->

<!-- START_TASK_4 -->
### 任务4: TokenService实施
...
<!-- END_TASK_4 -->

<!-- START_TASK_5 -->
### 任务5: TokenService测试
...
<!-- END_TASK_5 -->
<!-- END_SUBCOMPONENT_A -->

关键规则：

  • 任务编号：START_TASK_1, START_TASK_2, 等
  • 子组件使用字母：START_SUBCOMPONENT_A, START_SUBCOMPONENT_B, 等
  • 子组件标记必须包括它们包含的任务：(tasks 3-5)
  • 子组件内的任务仍有自己的标记
  • 独立任务（不在子组件中）只有任务标记

为什么标记：

  • 执行可以通过grep START_TASK_列出所有任务而无需读取完整内容
  • 执行可以仅提取相关部分传递给task-implementor
  • 在实施期间减少上下文使用（特别是实验性工作流程）

阶段逐步实施

工作流程取决于上面选择的审查模式。

步骤0: 创建带依赖的细粒度任务跟踪器

验证范围（≤8阶段）后，使用TaskCreate为每个阶段创建细粒度子任务。此结构在上下文压缩后存活。

关键：包括绝对路径并设置依赖。

创建任务前，捕获绝对路径：

  • DESIGN_PATH: 设计计划的绝对路径（例如，/Users/ed/project/docs/design-plans/2025-01-24-feature.md）
  • PLAN_DIR: 实施计划目录的绝对路径（例如，/Users/ed/project/docs/implementation-plans/2025-01-24-feature/）

从设计计划阅读验收标准部分。 验收标准编号（AC1, AC1.1, AC1.2, 等）并定义"完成"意味着什么。当编写每个阶段时：

  1. 识别此阶段实施哪些验收标准（查看设计阶段的"完成时" + 组件职责）
  2. 将这些验收标准条目逐字复制到阶段的"验收标准覆盖"头部部分
  3. 确保任务产生验证每个列出验收标准案例的测试

对于每个阶段N，创建这些任务与依赖：

- [ ] 阶段 NA: 从{DESIGN_PATH}阅读[阶段名称]
      → 阻塞者: 阶段 (N-1)D（或如果N=1则无）
- [ ] 阶段 NB: 调查阶段N的代码库并激活相关技能
      → 阻塞者: 阶段 NA
- [ ] 阶段 NC: 研究阶段N的外部依赖
      → 阻塞者: 阶段 NB
- [ ] 阶段 ND: 写入{PLAN_DIR}/phase_0N.md
      → 阻塞者: 阶段 NC

逐字任务名称—不要释义。 精确复制任务名称如上所示。“Investigate codebase for Phase N and activate relevant skills"必须包括"and activate relevant skills” — 该短语在压缩后触发技能激活。释义会丢失关键指令。

所有阶段任务后，创建最终化任务：

创建最终化任务前，检查.ed3d/implementation-plan-guidance.md是否存在。如果存在，在任务描述中包括其绝对路径：

# 如果.ed3d/implementation-plan-guidance.md存在：
- [ ] 最终化: 对所有阶段文件运行code-reviewer（指导：[.ed3d/implementation-plan-guidance.md的绝对路径]），修复所有问题包括小问题
      → 阻塞者: 所有阶段 *D 任务

# 如果.ed3d/implementation-plan-guidance.md不存在：
- [ ] 最终化: 对所有阶段文件运行code-reviewer，修复所有问题包括小问题
      → 阻塞者: 所有阶段 *D 任务

例如，对于在/Users/ed/project/docs/design-plans/2025-01-24-oauth.md的3阶段设计：

TaskCreate: "Phase 1A: Read Token Types from /Users/ed/project/docs/design-plans/2025-01-24-oauth.md"
TaskCreate: "Phase 1B: Investigate codebase for Phase 1 and activate relevant skills"
  → TaskUpdate: addBlockedBy: [1A]
TaskCreate: "Phase 1C: Research external deps (Phase 1)"
  → TaskUpdate: addBlockedBy: [1B]
TaskCreate: "Phase 1D: Write /Users/ed/project/docs/implementation-plans/2025-01-24-oauth/phase_01.md"
  → TaskUpdate: addBlockedBy: [1C]

TaskCreate: "Phase 2A: Read Token Service from /Users/ed/project/docs/design-plans/2025-01-24-oauth.md"
  → TaskUpdate: addBlockedBy: [1D]
TaskCreate: "Phase 2B: Investigate codebase for Phase 2 and activate relevant skills"
  → TaskUpdate: addBlockedBy: [2A]
TaskCreate: "Phase 2C: Research external deps (Phase 2)"
  → TaskUpdate: addBlockedBy: [2B]
TaskCreate: "Phase 2D: Write /Users/ed/project/docs/implementation-plans/2025-01-24-oauth/phase_02.md"
  → TaskUpdate: addBlockedBy: [2C]

TaskCreate: "Phase 3A: Read Session Manager from /Users/ed/project/docs/design-plans/2025-01-24-oauth.md"
  → TaskUpdate: addBlockedBy: [2D]
TaskCreate: "Phase 3B: Investigate codebase for Phase 3 and activate relevant skills"
  → TaskUpdate: addBlockedBy: [3A]
TaskCreate: "Phase 3C: Research external deps (Phase 3)"
  → TaskUpdate: addBlockedBy: [3B]
TaskCreate: "Phase 3D: Write /Users/ed/project/docs/implementation-plans/2025-01-24-oauth/phase_03.md"
  → TaskUpdate: addBlockedBy: [3C]

TaskCreate: "Finalization: Run code-reviewer over all phase files, fix ALL issues including minor ones"
  → TaskUpdate: addBlockedBy: [1D, 2D, 3D]

TaskCreate: "Test Requirements: Generate test-requirements.md from Acceptance Criteria"
  → TaskUpdate: addBlockedBy: [Finalization]

为什么任务描述中包括绝对路径： 压缩后，任务列表是唯一剩下的。绝对路径确保你确切知道要读/写哪些文件而不依赖上下文。

为什么依赖： 任务在任务列表中显示[blocked by #X, #Y]，使执行顺序明确并防止无序工作。

使用TaskUpdate在开始时将每个子任务标记为in_progress，完成时标记为completed。

如果用户选择"在写入前交互审查每个阶段"：

每个阶段的工作流程（使用细粒度任务跟踪）：

  1. 任务 NA: 阅读设计阶段

    • 标记任务 NA 为 in_progress
    • 从设计计划提取<!-- START_PHASE_N -->部分
    • 标记任务 NA 为 completed

  2. 任务 NB: 验证代码库状态

    • 标记任务 NB 为 in_progress
    • 派遣 codebase-investigator 附带此阶段的设计假设
    • 审查调查者发现以获取差异
    • 基于发现激活相关技能（如果尚未激活）：
      • TypeScript代码？激活TypeScript/编码风格技能
      • React组件？激活React技能
      • 数据库工作？激活数据库技能
      • 匹配此阶段涉及的技术技能
    • 标记任务 NB 为 completed

  3. 任务 NC: 研究外部依赖（如果阶段涉及它们）

    • 标记任务 NC 为 in_progress
    • 派遣 internet-researcher 用于文档/标准/API模式
    • 如果文档不足，升级到 remote-code-researcher
    • 记录发现以包含在阶段输出中
    • 标记任务 NC 为 completed -（如果无外部依赖 - 仍标记 completed 并备注"N/A"）

  4. 为此阶段写入实施任务（在内存中，不写入文件）：

    • 基于设计阶段范围识别此阶段覆盖哪些验收标准
    • 包括带有逐字验收标准副本的"验收标准覆盖"部分
    • 编写实施和测试每个列出验收标准案例的任务

  5. 呈现给用户 - 在你的消息文本中输出完整的阶段计划：

**阶段 [N]: [阶段名称]**

**代码库验证发现：**
- ✓ 设计假设确认：[匹配了什么]
- ✗ 设计假设不正确：[设计说什么] - 实际：[现实]
- + 发现额外：[发现的意外事物]
- ✓ 依赖确认：[library@版本]

**外部依赖发现：**（如适用）
- ✓ [库] API：[文档/来源揭示的内容]
- ✓ 标准：[规范引用和关键细节]
- ✗ 设计假设不正确：[设计说什么] - 实际：[基于文档/来源的现实]
- 📖 来源：[官方文档 | RFC规范 | 源代码@提交]

**基于实际代码库状态和外部研究的实施任务：**

### 任务1: [组件名称]

**文件：**
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`

**步骤1: 编写失败的测试**
[完整代码示例]

**步骤2: 运行测试以验证失败**
[确切命令和预期输出]

**步骤3: 编写最小实施**
[完整代码示例]

**步骤4: 运行测试以验证通过**
[确切命令和预期输出]

**步骤5: 提交**
[确切git命令]

[继续此阶段所有任务...]
  1. 使用 AskUserQuestion:

选项：

  • “批准 - 继续到下一阶段”
  • “需要修订 - [描述更改]”
  • “其他”

  1. 任务 ND: 写入阶段文件（如果批准）

    • 标记任务 ND 为 in_progress
    • 写入到 docs/implementation-plans/YYYY-MM-DD-<feature-name>/phase_##.md
    • 计划文档仅包含实施任务（无验证发现）
    • 标记任务 ND 为 completed，继续到下一阶段

  2. 如果需要修订： 基于反馈修订，再次呈现（在批准前不要标记 ND 为 in_progress）

如果用户选择"将所有阶段写入磁盘，我之后审查"：

每个阶段的工作流程（使用细粒度任务跟踪）：

  1. 任务 NA: 阅读设计阶段

    • 标记任务 NA 为 in_progress
    • 从设计计划提取<!-- START_PHASE_N -->部分
    • 标记任务 NA 为 completed

  2. 任务 NB: 验证代码库状态

    • 标记任务 NB 为 in_progress
    • 派遣 codebase-investigator 附带此阶段的设计假设
    • 审查调查者发现以获取差异
    • 基于发现激活相关技能（如果尚未激活）：
      • TypeScript代码？激活TypeScript/编码风格技能
      • React组件？激活React技能
      • 数据库工作？激活数据库技能
      • 匹配此阶段涉及的技术技能
    • 标记任务 NB 为 completed

  3. 任务 NC: 研究外部依赖（如果阶段涉及它们）

    • 标记任务 NC 为 in_progress
    • 派遣 internet-researcher 用于文档/标准/API模式
    • 如果文档不足，升级到 remote-code-researcher
    • 标记任务 NC 为 completed -（如果无外部依赖 - 仍标记 completed 并备注"N/A"）

  4. 任务 ND: 写入阶段文件

    • 标记任务 ND 为 in_progress
    • 基于设计阶段范围识别此阶段覆盖哪些验收标准
    • 包括来自设计的逐字验收标准副本的"验收标准覆盖"部分
    • 编写实施和测试每个列出验收标准案例的实施任务
    • 直接写入磁盘到 docs/implementation-plans/YYYY-MM-DD-<feature-name>/phase_##.md
    • 标记任务 ND 为 completed，继续到下一阶段

在写入前不要向用户发出阶段内容。 这节省令牌。

所有阶段写入后：

宣布：“所有[N]个阶段文件已写入docs/implementation-plans/YYYY-MM-DD-<feature-name>/。让我知道是否有任何阶段需要修订。”

任务结构

基于任务类型使用适当的模板（见上面的任务类型部分）。

基础设施任务模板

<!-- START_TASK_N -->
### 任务 N: [基础设施组件]

**文件：**
- 创建：`package.json`
- 创建：`tsconfig.json`

**步骤1: 创建文件**

[完整文件内容 - 无占位符]

**步骤2: 操作验证**

运行：`npm install`
预期：安装无误

运行：`npm run build`
预期：构建无误

**步骤3: 提交**

```bash
git add package.json tsconfig.json
git commit -m "chore: initialize project structure"

<!-- END_TASK_N -->


### 功能任务模板

```markdown
<!-- START_TASK_N -->
### 任务 N: [组件名称]

**验证：** {slug}.AC1.1, {slug}.AC1.3（列出此任务测试的特定验收标准案例）

**文件：**
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py` (unit|integration|e2e)

**实施：**
[描述要实施什么 - 契约、行为、关键逻辑。包括复杂/非明显实施的代码。]

**测试：**
测试必须验证上面列出的每个验收标准：
- {slug}.AC1.1: [测试应验证的简要描述]
- {slug}.AC1.3: [测试应验证的简要描述]

遵循项目测试模式。Task-implementor在执行时生成实际测试代码。

**验证：**
运行：`[测试命令]`
预期：所有测试通过

**提交：** `feat: [描述]`
<!-- END_TASK_N -->

功能任务的关键原则：

  1. 明确列出验收标准。 每个功能任务在"验证"字段中指定它验证哪些验收标准案例。

  2. 描述测试，不要编写测试代码。 验收标准文本是规格（例如，“AC1.3: 无效密码返回401”）。Task-implementor在执行时以新鲜代码库上下文生成测试代码。

  3. 包括非明显实施的实施代码。 如果实施复杂或适用项目特定模式，包括代码。如果给定验收标准描述直接明了，描述它。

  4. 指定测试类型和位置。 单元、集成或e2e？哪个文件？这确保阶段间一致性。

为什么计划中无测试代码：

  • 测试代码需要来自实施的实际函数签名
  • 项目测试模式在执行时发现
  • 验收标准文本如"无效密码返回401"已是清晰的测试规格
  • Task-implementor比实施计划者有更新鲜的上下文

如果你发现自己写"这直到阶段N+1才编译"： 停止。你在描述属于当前阶段的东西。每个阶段在阶段完成时必须可执行且所有测试通过。

常见合理化 - 停止

这些违反技能要求：

借口 现实
“文件可能存在，我会说’更新如果存在’” 使用codebase-investigator。写明确指令。
“设计提到此文件，必须在” 代码库变化。使用调查者验证当前状态。
“我可以快速自己验证文件” 使用codebase-investigator。节省上下文并防止幻觉。
“设计计划有代码，我会用那个” 否。设计提供方向。从代码库调查生成新代码。
“设计计划是最近的，代码仍应工作” 代码库可能已变。调查是真相来源，不是设计。
“用户在执行期间可以弄清楚文件是否存在” 你的工作是确切指令。无歧义。
“测试阶段3将失败但没关系，因为它会在阶段4修复” 所有阶段在结束前必须编译并通过测试。
“阶段验证减慢我” 偏离轨道浪费更多时间。验证每个阶段。
“我会批处理所有阶段然后在结束时验证” 如果用户选择批处理模式则有效。否则增量验证。
“我会只请求批准，用户可以看到计划” 在AskUserQuestion前在消息文本中输出完整计划。用户必须看到它。
“计划看起来足够完整可以问” 显示所有任务与所有步骤和代码。然后问。
“此计划有12阶段但它们小” 限制是8阶段。无例外。拒绝并重定向。
“我可以合并阶段以适配8” 那是用户的决定，不是你的。拒绝并解释选项。
“注释解释需要做什么” 代码注释不是指令。代码必须按原样运行。为依赖创建先前任务。
“工程师将找出引导方法” 代码中无实施问题。现在解决或创建先决条件任务。
“基础设施任务也需要TDD结构” 否。使用基础设施模板。按设计计划操作验证。
“我会为这个配置文件任务添加测试” 如果设计说"完成时: 构建"，不要发明测试。尊重设计。
“功能阶段但设计忘记测试” 向用户表面。功能需要测试。设计缺口，不是你的决定跳过。
“计划看起来完整，跳过验证” 总是验证。现在发现的缺口比执行期间发现更便宜。
“验证对于简单计划过度” 简单计划验证快。复杂计划更需要。总是验证。
“最终化任务完成，小问题可以等待” 否。任务说"修复所有问题包括小问题。"零问题前未完成。
“我会跳过创建细粒度任务，每阶段一个足够” 细粒度任务在压缩后存活。每阶段创建NA, NB, NC, ND + 最终化。
“依赖是明显的，不需要addBlockedBy” 任务列表显示阻塞状态。用TaskUpdate显式设置依赖。
“相对路径在任务描述中没问题” 压缩后，上下文丢失。使用绝对路径使任务自包含。
“我会释义任务名称，相同含义” 否。任务名称是逐字的。"and activate relevant skills"在压缩后触发行为。
“我知道这个库如何工作从训练” 研究它。API变化。使用internet-researcher用于文档，remote-code-researcher用于内部。
“文档可能足够准确” 通常是。但如果扩展/定制库行为，用源代码验证。
“我会克隆仓库以检查文档” 否。使用internet-researcher用于文档。仅克隆（remote-code-researcher）用于源代码调查。
“阶段有外部依赖但我会跳过研究” 当阶段涉及外部依赖时研究是强制的。现在表面未知。
“测试要求可以在执行期间生成” 否。测试要求必须在执行前存在。Code reviewer使用它们。
“此类型需要单元测试” 否。TypeScript编译器验证类型。不要测试编译器检查的内容。
“应该测试此调用依赖正确” 否。测试行为（结果），而不是接线（如何调用事物）。
“依赖在此使用，应该验证它工作” 否。依赖有自己的测试。测试你的代码的行为。
“更多测试 = 更好覆盖” 错误测试 = 噪音。测试验收标准，不多。
“阶段没有验收标准但我会添加一些测试” 否。明确说明"验证: 无"用于基础设施阶段。不要发明工作。
“验收标准清晰，不需要测试要求” 测试要求将标准映射到特定测试。执行需要此映射。
“我会跳过测试要求，用户选择批处理模式” 批处理模式跳过交互批准。测试要求仍生成并写入。
“测试要求任务是可选的” 否。它是带依赖的跟踪任务。必须在执行移交前完成。

所有这些意味着：停止。精确遵循要求。

当不知道如何继续时

如果你无法在没有未解决问题的情况下编写可执行代码： 立即停止。

不要写模糊注释。不要留TODO。不要继续。

相反，使用 AskUserQuestion 附带：

  1. 阻塞问题的确切描述：

    • 你不能做的具体实施决策
    • 设计中缺失的信息
    • 未定义的依赖

  2. 关于为什么这阻塞你的上下文：

    • 这影响哪个任务/阶段
    • 你已通过codebase-investigator验证了什么
    • 设计文档说什么（或不说什么）

  3. 你能看到的可能解决方案：

    • 选项 A: [具体方法带权衡]
    • 选项 B: [替代方法带权衡]
    • 选项 C: [如适用]

示例：

我在阶段2, 任务3 (Bootstrap Logto M2M application) 被阻塞。

问题：代码需要管理API凭据来创建资源，但这些凭据尚不存在（鸡生蛋问题）。

设计文档说："Bootstrap Logto with applications and roles"但未指定如何获取初始凭据。

代码库验证：无现有引导凭据或手动设置记录。

可能解决方案：
A. 添加阶段0: 手动设置 - 记录用户通过Logto UI手动创建初始M2M应用的步骤，保存凭据到.env
B. 使用Logto管理API如果可用 - 需要不同格式的管理凭据
C. 修改Logto docker-compose通过环境变量注入初始M2M应用

我应采取哪种方法？

永远不要以不确定的实施继续。向用户表面决策。

要求检查清单

开始前：

  • [ ] 计数阶段 - 如果>8则拒绝
  • [ ] 询问用户审查模式（批处理 vs 交互）
  • [ ] 捕获绝对路径：DESIGN_PATH 和 PLAN_DIR
  • [ ] 从设计计划阅读验收标准部分
  • [ ] 创建细粒度任务列表与TaskCreate（每阶段 NA, NB, NC, ND + 最终化 + 测试要求）
  • [ ] 设置依赖与TaskUpdate addBlockedBy（见步骤0）
  • [ ] 任务描述包括绝对路径（非相对）

对于每个阶段（任务 NA 到 ND）：

  • [ ] 任务 NA： 标记 in_progress，从设计阅读<!-- START_PHASE_N -->，标记 completed
  • [ ] 任务 NB： 标记 in_progress，派遣 codebase-investigator，审查发现，标记 completed
  • [ ] 任务 NC： 标记 in_progress，如果需要研究外部依赖（或标记 completed 带"N/A"），标记 completed
  • [ ] 基于调查者和研究发现写入确切路径和代码的完整任务
  • [ ] 如果交互模式： 输出完整阶段计划，使用 AskUserQuestion 请求批准
  • [ ] 任务 ND： 标记 in_progress，写入到任务描述中的绝对路径，标记 completed

对于计划中的每个任务：

  • [ ] 确切文件路径带行号用于修改
  • [ ] 完整代码 - 零TODO，零未解决问题在注释中
  • [ ] 每个代码示例立即运行而无需实施决策
  • [ ] 如果代码引用辅助/实用程序，先前任务创建它们
  • [ ] 确切命令带预期输出
  • [ ] 无条件指令（“如果存在”，“如果需要”）

最终化（所有阶段 ND 任务完成后）：

  • [ ] 标记最终化任务为 in_progress
  • [ ] 派遣 code-reviewer 验证计划对比设计
  • [ ] 修复所有问题包括小问题
  • [ ] 重新运行 code-reviewer 直到 APPROVED 带零问题
  • [ ] 标记最终化任务为 completed
  • [ ] 进行到测试要求

测试要求（最终化后）：

  • [ ] 标记测试要求任务为 in_progress
  • [ ] 派遣 Opus 子代理从验收标准生成测试要求
  • [ ] 如果交互模式： 呈现给用户，使用 AskUserQuestion 请求批准
  • [ ] 如果批处理模式： 直接写入不询问
  • [ ] 写入 test-requirements.md 到 PLAN_DIR
  • [ ] 标记测试要求任务为 completed
  • [ ] 进行到执行移交

计划验证（最终化任务）

这是一个跟踪任务：“最终化: 对所有阶段文件运行code-reviewer，修复所有问题包括小问题”

所有阶段 D 任务完成后，标记最终化任务为 in_progress。

步骤1: 派遣 code-reviewer

<invoke name="Task">
<parameter name="subagent_type">ed3d-plan-and-execute:code-reviewer</parameter>
<parameter name="description">验证实施计划对比设计</parameter>
<parameter name="prompt">
  审查实施计划的完整性和与设计的一致性。

  DESIGN_PLAN: [设计计划路径，例如，docs/design-plans/YYYY-MM-DD-feature.md]

  IMPLEMENTATION_GUIDANCE: [.ed3d/implementation-plan-guidance.md的绝对路径，或"None"如果文件不存在]

  IMPLEMENTATION_PHASES:
  - [phase_01.md的路径]
  - [phase_02.md的路径]
  - [... 所有阶段文件]

  如果 IMPLEMENTATION_GUIDANCE 不是 "None"，首先阅读它并应用任何项目特定
  审查标准、编码标准或质量门，它指定在标准审查检查清单之外。

  评估：
  1. **覆盖**: 实施计划是否覆盖设计的全部要求？
     - 检查每个设计阶段映射到实施任务
     - 检查每个"完成时"标准有相应验证
     - 检查设计提到的每个组件有实施任务

  2. **缺口**: 是否有任何缺失部分？
     - 设计中提到但实施中缺失的功能
     - 设计中指定但实施任务缺失的测试
     - 未考虑的依赖或设置步骤

  3. **对齐**: 实施方法是否匹配设计？
     - 架构决策被遵循
     - 文件路径与设计一致
     - 子组件结构匹配设计阶段

  4. **可执行性**: 每个阶段是否可以独立执行？
     - 任务间依赖明确
     - 无前向引用尚不存在的代码
     - 每个阶段以可验证状态结束

  报告：
  - GAPS: [列出任何缺失覆盖]
  - MISALIGNMENTS: [列出任何与设计的偏离]
  - ISSUES: [计划本身的关键/重要/小问题]
  - ASSESSMENT: APPROVED / NEEDS_REVISION
</parameter>
</invoke>

步骤2: 修复所有问题（包括小问题）

关键: 你必须修复所有问题，包括小问题。

不要合理化跳过小问题。在所有问题解决前不要标记最终化为completed。

如果审阅者返回 NEEDS_REVISION 或报告任何问题：

  1. 为每个问题创建任务（在压缩后存活）：

    TaskCreate: "Finalization fix [Critical]: <从审阅者逐字问题描述>"
TaskCreate: "Finalization fix [Important]: <从审阅者逐字问题描述>"
TaskCreate: "Finalization fix [Minor]: <从审阅者逐字问题描述>"
...每个问题一个任务...
TaskCreate: "Finalization: Re-review after fixes"
TaskUpdate: 设置 "Re-review" 被所有修复任务阻塞

    逐字复制问题描述，即使长。压缩后，任务描述是唯一剩下的—它必须包含完整问题细节以理解要修复什么。

  2. 审查识别的缺口、错位和问题

  3. 修复所有—关键、重要和小问题

  4. 更新相关阶段文件

  5. 解决每个时标记每个修复任务完成

  6. 重新运行 code-reviewer 验证

  7. 如果发现更多问题，创建新的个别修复任务并重复

  8. 当零问题时标记"Re-review"完成

常见合理化要拒绝：

  • “小问题可以在执行期间修复” - 否。现在修复它们。
  • “这个小问题只是风格偏好” - 否。修复它。
  • “我们可以以后解决此” - 否。任务说"修复所有问题包括小问题。"

步骤3: 完成最终化

仅当 code-reviewer 返回 APPROVED 带零问题时：

标记最终化任务为 completed。

进行到测试要求生成。

测试要求生成

跟踪任务：“测试要求: 从验收标准生成 test-requirements.md”

最终化完成后标记 in_progress。

测试要求将验收标准映射到特定自动化测试，并识别需要人工验证的标准。测试分析师代理在执行期间使用此验证覆盖。

步骤1: 通过子代理生成

<invoke name="Task">
<parameter name="subagent_type">ed3d-basic-agents:opus-general-purpose</parameter>
<parameter name="description">从验收标准生成测试要求</parameter>
<parameter name="prompt">
阅读在[DESIGN_PATH]的设计和在[PLAN_DIR]的实施阶段。

生成 test-requirements.md 映射每个验收标准到：
- 自动化测试: 标准, 测试类型 (unit/integration/e2e), 预期测试文件路径
- 人工验证: 无法自动化的标准, 带理由和验证方法

基于计划期间做出的实施决策合理化。每个验收标准必须映射到自动化测试或记录的人工验证。
</parameter>
</invoke>

步骤2: 基于审查模式处理

  • 交互模式： 呈现给用户，使用 AskUserQuestion 请求批准。这是最后的交互项。
  • 批处理模式： 直接写入，宣布完成。

如果用户在交互模式中请求修订：

  1. 为每个修订创建任务（在压缩后存活）：

    TaskCreate: "Test requirements fix: <从用户逐字修订请求>"
...每个修订一个任务...
TaskCreate: "Test requirements: Re-present for approval"
TaskUpdate: 设置 "Re-present" 被所有修复任务阻塞

    逐字复制修订请求，即使长。压缩后，任务描述必须包含完整细节。

  2. 解决每个修订，完成时标记任务

  3. 重新呈现请求批准

  4. 重复直到批准

步骤3: 写入并完成

写入到 [PLAN_DIR]/test-requirements.md。标记任务 completed。进行到执行移交。

执行移交

测试要求生成完成后，宣布：

“实施计划完成并已验证。保存到[计数]个阶段文件 + test-requirements.md 在 docs/implementation-plans/YYYY-MM-DD-<feature-name>/。第一阶段文件是<full-path>。测试要求在<full-path>/test-requirements.md。”