ddev-plan

name	ddev-plan
description	在已有规格或多步骤任务需求、且在动代码之前使用。若上游 ddev-pc-test 已产出测试用例，自动走 TDD 流程：先实现测试 demo 代码（红灯），再实现被测代码（绿灯），测试覆盖不到的部分直接开发。

编写计划

概述

ddev-plan 的职责是把上游已经确认的设计映射成可执行的实施顺序，避免展开成详细代码草稿。计划里要清楚说明：每个任务对应哪些已确认文档、允许改哪些文件、必须遵守哪些约束、完成后用什么证据证明实现结果与文档一致。

计划文档只正向描述本次实现要做什么、分别在哪一步做、做到什么结果。不要专门写“明确不做什么”或“范围外不做什么”的条目。凡是计划里没有列出的任务、步骤、文件改动和验证动作，默认都不属于这次实现范围。

要假设后续执行者是熟练开发者，但对当前仓库上下文并不熟，所以计划必须告诉他先读哪些 spec / detail / flow / dataflow 文档，以及这些文档在当前任务里分别约束什么。

这个 skill 只消费已经确认过的 spec 文档、结构设计文档和图，不负责重新决定架构，也不负责在计划阶段发明新的数据结构、状态流或接口契约。上游通常先经过 ddev-spec，图形细化则交给 ddev-diagram，结构和数据流细化则交给 ddev-detail。

如果上游已经为嵌入式 C / 纯 C 场景定义了”禁止业务全局变量、限制长链 if/else、优先 context/状态机/表驱动”的 spec 约束，这里必须原样传递到执行计划，不能在任务拆解时弱化成泛泛的”优化代码结构”。对于其他语言项目，同样需要原样传递上游定义的模块边界、接口契约和实现约束。

对于 C 项目（.c / .h），本阶段必须加载 ddev-c-pro 和 ddev-comment-gen skill，将设计规范、命名规范、Doxygen 注释标准、风格偏好作为实现约束写入计划，确保执行者明确知道编码规范要求。对于其他语言项目，如果有对应的编码规范 skill，也应在本阶段加载并写入计划约束。

开始时声明： “我正在使用 ddev-plan skill 来创建实现计划。”

上下文： 这个 skill 应该在专门的 worktree 里运行（由上游设计流程创建）。

计划保存到： docs/plans/YY-MM-DD_name/exec_plans/<feature-name>.md

• （如果用户对计划位置有偏好，以用户偏好为准）

范围检查

如果规格覆盖了多个彼此独立的子系统，那么在上游设计阶段就应该拆成多个子项目规格。如果没有拆，就应该建议拆成多个计划 - 每个子系统一个。每个计划都应该能独立产出可运行、可测试的软件。

如果 spec 文档、结构设计文档或流程图还没确认，或者还在反复改，就先回上游把设计定住，不要在 ddev-plan 里提前写实现细节。

范围写法也必须保持正向：只列本计划实际覆盖的子系统、文件、任务和验证。没有写进计划的内容，不补充、不顺带、不默认实现。

TDD 优先策略

如果上游 ddev-pc-test 已产出测试用例文档（detail/tests/）和测试 demo 代码大纲，计划必须走 TDD 流程。如果不存在测试用例，跳过本节，按常规流程直接规划实现。

判断步骤

1. 检查 docs/plans/YY-MM-DD_<topic>/detail/tests/ 目录是否存在测试用例文档
2. 如果存在，读取测试总览文档，确认覆盖了哪些接口/路径/状态
3. 将测试用例映射到计划任务中：每个测试用例对应一个 TDD 子任务

TDD 任务编排

TDD 模式下的任务必须按红-绿-重构拆成三个连续子步骤：

• 红灯（Test First）：先按 ddev-pc-test 的测试 demo 大纲，把测试脚本/测试代码写完整、跑通红灯（被测代码未实现，测试必然失败）
• 绿灯（Implement）：再实现被测代码，跑通绿灯
• 重构（Refactor）：最后在测试保护下清理代码结构

覆盖拆分

计划必须把本次改动拆成两块：

1. 测试覆盖部分（TDD）：测试用例能覆盖的接口/状态/路径，按 TDD 红-绿-重构顺序编排
2. 测试未覆盖部分（直接开发）：硬件依赖、中断时序、板级外设等测试无法覆盖的部分，按常规实现 → 验证 → 一致性核对编排

计划文档中必须显式标明每个任务属于哪一块，以及为什么某个部分无法走 TDD。

TDD 任务引用

TDD 任务在"必读文档"中必须额外引用：

• docs/plans/.../detail/tests/<name>-overview.md：可测试性结论与覆盖范围
• docs/plans/.../detail/tests/<name>-cases.md：具体测试用例及输入/预期输出
• 对应的测试 demo 代码路径（如 test/YY-MM-DD-<feature>/）

文档依赖原则

• ddev-plan 不定义新的业务状态、接口契约、数据结构语义或流程分支
• 计划中出现的关键设计项，必须能追溯到已确认的 spec / detail / flow / dataflow 文档
• 每个任务都要明确列出执行前必须阅读的文档和章节，避免执行者只看计划不看设计
• 如果某个关键实现约束无法追溯到上游文档，就停止写计划，回到上游补文档，而不是在计划里临时补设计

代码现状验证（强制）

在编写计划的任务和文件结构之前，必须验证计划涉及的文件路径和符号是否存在于实际代码中。计划中的所有文件路径、函数名、结构体名必须能在源码中找到对应，或来自已确认的上游文档。

验证步骤

1. 文件路径验证：对计划中要新建/修改的每个文件——
   • 若是修改已有文件：用 Glob 或 codegraph_files 确认文件路径存在
   • 若是新建文件：确认其父目录存在，不存在则标注需要在哪个任务中创建
2. 符号验证：对计划中引用的函数名/结构体名/枚举名——
   • 用 codegraph_search 确认在源码中的实际签名
   • 如果符号来自上游 ddev-pc-test 的 API 签名清单或 ddev-detail 的代码分析，直接引用，无需重复搜索
3. TDD 任务 API 验证：TDD 任务的测试代码引用的 API 签名必须——
   • 来自 ddev-pc-test 产出的 API 签名清单，或
   • 来自 ddev-detail 的代码现状收集结果
   • 禁止在计划中凭空写出测试代码要调用的函数名

不通过时的处理

• 如果文件路径不存在且不是新建文件 → 回上游确认 spec/detail 是否覆盖了正确的代码范围
• 如果符号在源码中找不到 → 确认是拼写错误还是上游设计文档遗漏，修正后再继续

文件结构

在定义任务之前，先把需要创建或修改哪些文件、每个文件负责什么理清楚，并把它们和对应的上游设计文档绑定起来。这一步会把拆分决策固定下来。

• 设计边界清晰、接口明确的单元。每个文件都应该只有一个明确职责。
• 你最擅长处理能一次放进上下文里的代码，而且文件越聚焦，修改越可靠。优先小而专注的文件，不要用一个大文件做太多事。
• 需要一起变动的文件应该放在一起。按职责拆分，不要按技术层拆分。
• 在已有代码库里，要遵循既有模式。如果代码库本来就有大文件，不要擅自重构；但如果你要改的文件已经臃肿了，在计划里包含拆分是合理的。
• 如果存在 ddev-pc-test 产出的测试 demo 代码目录（test/YY-MM-DD-<feature>/），必须把测试脚本/测试代码文件列在对应的 TDD 任务里，并标注其为"红灯"阶段产物。

对于嵌入式 C / 纯 C 计划，还要把这些点写进任务拆分：

• 哪个步骤先定义 context / session / handle 结构体
• 哪个步骤把状态枚举和错误码落地
• 哪个步骤把长链条件改成 switch、状态机或表驱动
• 哪个步骤拆出私有 static 辅助函数，避免主函数吞下全部职责
• 哪个步骤验证没有新增业务全局变量和魔法状态值

对于其他语言项目，任务拆分应包含对应的结构约束（如 Rust 的 ownership 边界、Python 的类型注解策略、Go 的 error handling 约定等），由对应语言的编码规范 skill 决定具体约束项。

这个结构会影响任务拆分。每个任务都应该产出自包含、彼此独立、合理的改动，并能明确回答“本任务落实的是哪份设计文档的哪一部分”。

小步任务粒度

计划要拆到”可稳定执行、可独立验证、可明确对照设计”的粒度，但不需要把任务机械拆成 2-5 分钟的小动作，也不需要把上游文档已经写清楚的实现细节再重复展开成完整代码。

推荐的任务粒度是：

• 一个任务对应一个明确模块、流程段或一致性交付点
• 一个任务内可以包含”阅读文档 -> 实现 -> 验证 -> 一致性核对”这一组完整动作
• 如果两个步骤引用的设计文档、修改文件范围或验证方式明显不同，就拆成两个任务

计划文档头部

每个计划都必须以这个头部开始：

# [功能名] 实现计划

> **给代理型执行者：** 必需子技能：使用 `ddev-exec` 按任务逐步实现这个计划。步骤使用复选框（`- [ ]`）语法跟踪。

**目标：** [一句话描述这个功能做什么]

**架构：** [2-3 句说明方案，并注明设计以哪些已确认文档为准]

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

**设计依据：**
- `docs/plans/.../spec/...`
- `docs/plans/.../detail/...`
- `docs/plans/.../flow/...`
- `docs/plans/.../dataflow/...`（如有）
- `docs/plans/.../detail/tests/...`（如有，`ddev-pc-test` 产出）
- `ddev-c-pro` skill：编码规范、命名规范（C 项目必填，其他语言项目可选——如有对应 skill 则引用）
- `ddev-comment-gen` skill：Doxygen 注释标准（C 项目必填，其他语言项目可选——如有对应 skill 则引用）

**TDD 状态：** [存在测试用例 / 无测试用例]
- 若存在，标注测试覆盖范围：[接口/状态/路径]；未覆盖范围：[硬件依赖/中断时序/...]
- 若不存在，简述原因：[不可 PC 测试 / 未触发 ddev-pc-test / 跳过]

---

任务结构

### 任务 N： [组件名]

**依赖：** [Task X, Task Y / 无]

**目标：**
- [本任务要落地的模块、流程或交付点]

**必读文档：**
- `docs/plans/.../spec/...`：章节 / 图 / 接口定义
- `docs/plans/.../detail/...`：结构体 / 状态 / 错误码 / 数据约束
- `docs/plans/.../flow/...`：流程节点 / 分支 / 状态迁移
- `docs/plans/.../dataflow/...`：数据流约束（如有）

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

**实现约束：**
- 保持 [context / 状态机 / 表驱动 / 接口契约] 方案
- 不得新增 [业务全局变量 / 长链 `if/else` / 范围外接口]
- 实现命名、错误码、状态值必须与引用文档一致
- C 项目须遵守 `ddev-c-pro` skill：`_t` 类型后缀、模块前缀、显式返回码、所有权明确（其他语言项目由对应编码规范 skill 约束）
- C 项目须遵守 `ddev-comment-gen` skill：Doxygen 注释完整性（公开 API/@file/结构体成员）（其他语言项目由对应注释规范 skill 约束）

- [ ] **步骤 1：阅读并核对引用文档**

确认本任务覆盖的输入、输出、状态、接口、流程和边界条件都能在上游文档中找到依据。

- [ ] **步骤 2：按既定设计修改目标文件**

实现时只允许在本任务列出的文件范围内落地设计，不得在计划外扩展新设计。

- [ ] **步骤 3：补齐本任务需要的验证**

运行：`pytest tests/path/test.py::test_name -v`
预期：通过，且结果与引用文档描述一致

- [ ] **步骤 4：做一致性核对**

逐项核对代码实现是否与引用文档里的结构、状态迁移、接口语义和流程节点一致；若不一致，先修正代码或回上游补文档。

- [ ] **步骤 5：写入实现笔记**

在 `implementation-notes.md` 中追加本任务的推理记录，按 Design Decisions / Deviations / Tradeoffs / Open Questions 四个维度记录。Design Decisions 和 Deviations 为强制维度——必须检查并记入；Tradeoffs 和 Open Questions 有则必写，无则标注"无"。

- [ ] **步骤 6：记录结果与未覆盖风险**

记录本任务已经覆盖的设计点、验证证据，以及仍需后续任务或最终门禁覆盖的风险。

**验证：**
- 运行：`exact verification command`
- 预期：`expected result`
- 人工核对：`与哪份文档的哪几个点保持一致`

**完成标准：**
- 引用文档中的设计点已经落地到代码
- 没有引入文档中不存在的新设计漂移
- 验证通过，且一致性核对完成

对于 C 项目，如果任务涉及控制流或状态管理，步骤里不能只写”实现逻辑”，要明确写出：

• 先补或定义状态枚举 / 上下文结构体
• 再根据已确认文档落地状态迁移和错误路径验证
• 再落地分发方式，不允许默认写成长链 if/else
• 按 ddev-c-pro skill 要求遵循命名规范和风格偏好
• 按 ddev-comment-gen skill 要求补 Doxygen 注释
• 最后检查是否出现共享可变全局状态、参数过多未封装、注释缺失等违规

对于其他语言项目，同样需要将对应语言的实现约束明确写在步骤中，不允许含糊的”实现逻辑”占位。

TDD 任务结构

当上游 ddev-pc-test 已产出测试用例时，对应任务改用以下 TDD 模板。一个 TDD 任务对应一个或一组紧密相关的测试用例。

### 任务 N： [组件名]（TDD）

**类型：** TDD（测试覆盖）

**对应测试用例：** TC-01, TC-02（来自 `detail/tests/<name>-cases.md`）

**目标：**
- [本任务要落地的模块、流程或交付点]

**必读文档：**
- `docs/plans/.../spec/...`：章节 / 图 / 接口定义
- `docs/plans/.../detail/...`：结构体 / 状态 / 错误码 / 数据约束
- `docs/plans/.../detail/tests/<name>-overview.md`：可测试性结论与覆盖范围
- `docs/plans/.../detail/tests/<name>-cases.md`：测试用例 TC-0x 的输入/预期输出

**文件：**
- 测试代码：`test/YY-MM-DD-<feature>/host_sim/test_xxx.py`（红灯阶段产物）
- 被测代码：`src/path/to/module.c`（绿灯阶段产物）

**实现约束：**
- 保持 [context / 状态机 / 表驱动 / 接口契约] 方案
- 不得新增 [业务全局变量 / 长链 `if/else` / 范围外接口]
- 测试脚本的输入/预期输出来自 cases 文档，不得自行发明
- C 项目须遵守 `ddev-c-pro` skill（其他语言项目由对应编码规范 skill 约束）

- [ ] **步骤 1：阅读测试用例文档**

确认本任务覆盖的测试用例编号、输入数据、预期输出、前置条件都能在 cases 文档中找到。

- [ ] **步骤 2：红灯 — 先写测试代码**

按 cases 文档中的输入/预期输出，把测试脚本/测试 demo 代码写完整。**写入前必须先读取被测模块的头文件**，确认测试代码中调用的函数签名、结构体、枚举值与源码一致。运行测试，确认红灯（被测代码未实现，测试必然失败）。记录红灯输出。

- [ ] **步骤 3：绿灯 — 实现被测代码**

按 spec/detail 设计文档实现被测代码，用最小代码量让测试通过。运行测试，确认绿灯。

- [ ] **步骤 4：重构 — 测试保护下清理**

在绿灯保护下，清理重复代码、改善命名、拆分过长函数。每改一处就跑一次测试，保持绿灯。

- [ ] **步骤 5：做一致性核对**

逐项核对代码实现是否与引用文档里的结构、状态迁移、接口语义和流程节点一致；若不一致，先修正代码或回上游补文档。

- [ ] **步骤 6：写入实现笔记**

在 `implementation-notes.md` 中追加本任务的推理记录，按 Design Decisions / Deviations / Tradeoffs / Open Questions 四个维度记录。Design Decisions 和 Deviations 为强制维度——必须检查并记入；Tradeoffs 和 Open Questions 有则必写，无则标注"无"。

- [ ] **步骤 7：记录结果与未覆盖风险**

记录本任务覆盖的测试用例、红灯/绿灯输出摘要，以及本 TDD 任务无法覆盖的边界条件。

**验证：**
- 红灯验证：运行：`python test/.../test_xxx.py`，预期：FAIL（被测代码未实现）
- 绿灯验证：运行：`python test/.../test_xxx.py`，预期：PASS
- 人工核对：`与 cases 文档 TC-0x 的预期输出逐字段比对`

**完成标准：**
- 测试用例全部绿灯通过
- 被测代码实现与引用文档一致
- 没有引入文档中不存在的新设计漂移
- 测试输出可自动比对，无需人眼判断

不要留占位符

每一步都必须包含工程师真正需要的内容。以下都属于计划失败，绝对不要写：

• “TBD”“TODO”“后面再实现”“补充细节”
• “添加适当的错误处理” / “添加校验” / “处理边界情况”
• “参考前面的文档自行实现”（但没有写明具体文档和章节）
• “和任务 N 类似”（工程师可能不是按顺序读任务）
• 只说做什么、不说明要读哪些文档、改哪些文件、怎么验证一致性
• 引用了某个类型、状态、函数或方法，但这些东西无法追溯到已确认设计文档

记住

• 始终写清楚准确的文件路径
• 始终写清楚本任务依赖的文档路径、章节或图
• 命令要精确，预期输出也要精确
• 一致性校对点要精确，不能只写“和设计一致”这种空话
• DRY、YAGNI、频繁提交

自检

把完整计划写完后，要换个角度重新看一遍，对照规格和上游文档检查计划。这是你自己运行的清单，不是派发给子代理的任务。

1. 规格覆盖： 快速浏览规格的每个章节/要求。能不能指出一个对应的任务？把缺口列出来。

2. 文档映射： spec / detail / flow / dataflow 文档里的关键交付项、结构、状态和流程节点，能不能在计划里找到对应任务和验证动作？缺口列出来。

3. 占位符扫描： 在计划里找红旗 - 是否有上面“不要留占位符”里列出的模式？有就修掉。

4. 类型与约束一致性： 后续任务里使用的类型、方法签名、属性名、状态名、错误码，是否和上游文档里的命名一致？比如 detail 文档里叫 clearLayers()，计划里又变成 clearFullLayers()，这就是 bug。同时检查这些名称是否能在实际源码中找到对应的声明或定义。

5. 设计漂移检查： 计划里是否引入了上游文档没定义的新结构、新接口、新流程分支或范围外文件改动？如果有，删掉或回上游补设计，不要在计划里偷改架构。

6. 联动覆盖检查： 如果上游 spec/detail 文档中包含联动修改清单，计划是否已为每个联动点分配任务或明确说明为何不需要改？如果上游文档中没有联动修改清单，停止编写计划，回到 ddev-spec 阶段补充后再继续。计划中的任务是否覆盖了联动修改清单中的所有项目？

7. 代码路径存在性： 计划中列出的所有文件路径（新建/修改）是否真实存在于仓库中？新建文件的父目录是否存在？

8. 实现笔记步骤： 计划中每个任务是否都包含了"写入实现笔记"步骤？步骤描述是否指明了按 Design Decisions / Deviations / Tradeoffs / Open Questions 四个维度记录？

9. 语言结构纪律： 如果是 C 项目，计划里是否已经明确安排：

• 业务状态收敛到上下文结构体
• 状态值枚举化
• 长链 if/else 的替代方案
• 函数按职责拆分
• 对”未新增业务全局变量”的验证
• 对”实现是否仍与上游控制流文档一致”的核对
• 按 ddev-c-pro skill 要求遵循命名规范和风格偏好
• 按 ddev-comment-gen skill 要求补 Doxygen 注释

如果是其他语言项目，计划里是否已经明确安排该语言对应的结构约束（由对应编码规范 skill 决定）？

10. TDD 覆盖核对： 如果存在 ddev-pc-test 产出的测试用例：

• 每个测试用例是否都有对应的 TDD 任务？
• TDD 任务是否按红-绿-重构三步骤编排？
• 测试未覆盖的部分是否已显式标注为”直接开发”，并说明了不可测试的原因？
• TDD 任务的”必读文档”是否引用了 cases 文档和 overview 文档？
• 测试脚本的输入/预期输出是否来自 cases 文档，而非自行发明？
• 测试代码中调用的 API 签名是否能追溯到 ddev-pc-test 的签名清单或 ddev-detail 的代码分析？

如果发现问题，直接在原地修掉，不用重新审一遍，改完就继续。若发现某个规格要求没有对应任务，就补上任务。

执行交接

保存计划后，直接进入 ddev-exec。

执行要求：

• 使用 ddev-exec
• 按计划顺序逐步执行
• 在阶段性里程碑后做审查

默认收尾

当计划对应的实现完成后，不要只停在“代码写完”或“测试跑过”。

默认收尾顺序是：

1. 用 verification-before-completion 补齐本轮结论所需的验证证据。
2. 如需独立质量复核，用 ddev-code-review 做额外审查。
3. 最后进入 ddev-gate，按 spec 文档、detail 文档、代码实现、验证证据做最终一致性验收；之后根据项目语言执行对应的编码规范审查（C 项目经 ddev-c-pro）和注释审查。

如果没有经过 ddev-gate，默认不应宣称“实现已经按设计完成”。