docevilOck
docevilOck/agent-skills-hook
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/docevilOck/agent-skills-hook --skill ddev-plan命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| 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 里提前写实现细节。
范围写法也必须保持正向：只列本计划实际覆盖的子系统、文件、任务和验证。没有写进计划的内容，不补充、不顺带、不默认实现。
如果上游 ddev-pc-test 已产出测试用例文档（detail/tests/）和测试 demo 代码大纲，计划必须走 TDD 流程。如果不存在测试用例，跳过本节，按常规流程直接规划实现。
docs/plans/YY-MM-DD_<topic>/detail/tests/ 目录是否存在测试用例文档TDD 模式下的任务必须按红-绿-重构拆成三个连续子步骤：
ddev-pc-test 的测试 demo 大纲，把测试脚本/测试代码写完整、跑通红灯（被测代码未实现，测试必然失败）计划必须把本次改动拆成两块：
计划文档中必须显式标明每个任务属于哪一块，以及为什么某个部分无法走 TDD。
TDD 任务在"必读文档"中必须额外引用：
docs/plans/.../detail/tests/<name>-overview.md：可测试性结论与覆盖范围docs/plans/.../detail/tests/<name>-cases.md：具体测试用例及输入/预期输出test/YY-MM-DD-<feature>/）ddev-plan 不定义新的业务状态、接口契约、数据结构语义或流程分支在编写计划的任务和文件结构之前，必须验证计划涉及的文件路径和符号是否存在于实际代码中。计划中的所有文件路径、函数名、结构体名必须能在源码中找到对应，或来自已确认的上游文档。
Glob 或 codegraph_files 确认文件路径存在codegraph_search 确认在源码中的实际签名Read 读取目标函数的完整代码（不是 grep 片段、不是 codegraph 摘要）在定义任务之前，先把需要创建或修改哪些文件、每个文件负责什么理清楚，并把它们和对应的上游设计文档绑定起来。这一步会把拆分决策固定下来。
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 有则必写，无则标注"无"。
- [ ]
记录本任务已经覆盖的设计点、验证证据，以及仍需后续任务或最终门禁覆盖的风险。
运行：
预期：
人工核对：
引用文档中的设计点已经落地到代码
没有引入文档中不存在的新设计漂移
验证通过，且一致性核对完成
对于 C 项目，如果任务涉及控制流或状态管理，步骤里不能只写”实现逻辑”，要明确写出：
if/elseddev-c-pro skill 要求遵循命名规范和风格偏好ddev-comment-gen skill 要求补 Doxygen 注释对于其他语言项目，同样需要将对应语言的实现约束明确写在步骤中，不允许含糊的”实现逻辑”占位。
当上游 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 有则必写，无则标注"无"。
[ ]
记录本任务覆盖的测试用例、红灯/绿灯输出摘要，以及本 TDD 任务无法覆盖的边界条件。
红灯验证：运行：，预期：FAIL（被测代码未实现）
绿灯验证：运行：，预期：PASS
人工核对：
测试用例全部绿灯通过
被测代码实现与引用文档一致
没有引入文档中不存在的新设计漂移
测试输出可自动比对，无需人眼判断
每一步都必须包含工程师真正需要的内容。以下都属于计划失败，绝对不要写：
把完整计划写完后，要换个角度重新看一遍，对照规格和上游文档检查计划。这是你自己运行的清单，不是派发给子代理的任务。
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 产出的测试用例：
如果发现问题，直接在原地修掉，不用重新审一遍，改完就继续。若发现某个规格要求没有对应任务，就补上任务。
保存计划后，向用户报告计划文档路径、任务数量和关键里程碑。
禁止 agent 自动进入 ddev-exec。 必须等待用户明确确认后再加载 ddev-exec 开始执行。
提示模板：
执行要求（用户确认后）：
ddev-exec当计划对应的实现完成后，不要只停在“代码写完”或“测试跑过”。
默认收尾顺序是：
verification-before-completion 补齐本轮结论所需的验证证据。ddev-code-review 做额外审查。ddev-gate，按 spec 文档、detail 文档、代码实现、验证证据做最终一致性验收；之后根据项目语言执行对应的编码规范审查（C 项目经 ddev-c-pro）和注释审查。如果没有经过 ddev-gate，默认不应宣称“实现已经按设计完成”。