Menu
在代码修改前需要编写 spec 文档且应优先用图表达边界、入口、流程和改动关系时使用（仅限代码改动场景，非项目级架构文档初始化）
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
在当前会话里按已写好的实现计划顺序执行任务时使用
在已有规格或多步骤任务需求、且在动代码之前使用。若上游 ddev-pc-test 已产出测试用例，自动走 TDD 流程：先实现测试 demo 代码（红灯），再实现被测代码（绿灯），测试覆盖不到的部分直接开发。
文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。
代码修改场景下，spec 文档确认后，需要继续以图优先方式梳理结构体定义、数据流和流程时使用
在代码实现完成后、准备结束任务或进入发布前使用，用来核对代码实现是否与 spec 文档以及 detail 文档一致，并通过代码质量审查、清理、编码规范和注释审查后给出最终验收结论
当需要基于仓库代码推导刷写参数，并复用统一流程完成固件探测、分包或刷写时使用。
| name | ddev-spec |
| description | 在代码修改前需要编写 spec 文档且应优先用图表达边界、入口、流程和改动关系时使用（仅限代码改动场景，非项目级架构文档初始化） |
在进行代码修改（新增、重构、修复）前，先出 spec 图，用图讲清改动边界、模块关系、接入点和主流程，再进入编码。本 skill 仅用于代码改动场景，项目的整体架构文档初始化请使用 ddev-arch。
边界声明：本 skill 仅产出设计文档，不得直接修改代码。所有代码修改必须在本 skill 产出 spec 文档并获得确认后，通过 ddev-plan 拆解执行计划，再由执行计划驱动编码实现。
如果仓库已存在 docs/architecture/，本 skill 必须先读取项目级架构规范，并让本次 spec 显式遵守其中的模块职责、允许依赖、状态所有权和允许修改范围。
spec 文档默认采用”图优先，文辅佐”表达。只保留两类内容：
能画图说明的内容，不要改写成长段文字。文字只补图里不适合承载的约束、判定条件和验收口径。
不要专门写“明确不做什么”“范围外什么不做”这类反向清单。文档里没有写到的事项，默认就是这次改动不做，不需要额外声明。
如果某件事容易和本次改动混淆，不要写“这个不做”；直接补一张边界图、入口图或对比图，正向说明这次实际落地范围。
图怎么画、怎么命名、怎么渲染、怎么同步维护：
在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。加载完成前禁止写任何 ASCII 图。
spec 文档默认落到 docs/plans/YY-MM-DD_name/spec/<feature-name>.md。
默认优先用于嵌入式 C / 纯 C / Rust / HTML / Python 的改动，尤其是 BSP、驱动、协议、板级初始化和静态页面这类需要看边界的工作。
对于 C 项目（.c / .h），本阶段必须加载 ddev-c-pro 和 ddev-comment-gen skill，将其中的设计规范、命名规范、注释规范作为 spec 约束一并写入文档，不得留到编码阶段临场决定。对于其他语言项目，如果有对应的编码规范 skill，也应在本阶段加载并写入 spec 约束。
对于嵌入式 C / 纯 C 改动，这一步不只是”把模块关系画出来”，还要提前约束 AI 和实现者的结构选择，避免后续编码阶段直接滑向全局变量、长链 if/else 和职责混杂的大函数。对于其他语言，同样需要提前约束模块边界和职责划分。
docs/architecture/，先阅读 01_架构总览.md 和相关模块文档，确认本次改动是否在项目级架构规范允许范围内。ddev-diagram，按规范手写 ASCII 图到 .md。ddev-pc-test，判断本次修改是否可在 PC 上写测试 demo 直接验证；如果可以则产出测试用例文档和 demo 代码。若不需 PC 测试或不可测试，直接跳过本步骤。ddev-detail 继续细化结构体和数据流；若步骤 6 已产出测试，仍可按需进入 detail 补充实现细节。ddev-plan，把已确认设计拆成执行计划。ddev-gate，按图对照代码实现是否一致。若步骤 6 产出了测试 demo，ddev-gate 阶段必须跑通该 demo。implementation-notes.md 中；spec 最终定版时，写入设计依据摘要。docs/architecture/，先做项目级架构越界检查：
ddev-diagram 绘制规范手写所有 ASCII 图。在画任何图之前，必须先从源码中理解”代码现在长什么样”。spec 图里画的模块边界、接口方向和文件路径必须与代码实际结构一致。
*.h）和关键源文件优先使用 CodeGraph 结构化查询：
codegraph_files 了解涉及的目录和文件结构codegraph_context 理解模块的架构角色和关键符号codegraph_explore 批量查看相关源码CodeGraph 未初始化时回退方案：
Glob 查看目录结构grep 搜索关键符号和 include 关系Read 打开关键头文件确认接口不要求单独文档，但 spec 文档中必须包含：
在代码现状分析完成后、开始画图之前，必须回答一个核心问题：本次设计是在现有框架里扩展，还是在现有框架之外另起炉灶？
原则：默认扩展，例外新建。优先在现有模块、现有接口、现有模式上扩展；新建模块/接口/模式必须有充分理由。
CMakeLists.txt、Makefile 中的源文件列表）.c/.h、模块目录结构、测试文件位置）在画图之前，必须搜索并识别本次改动需要联动修改的所有位置。不完成此步骤不得开始画图。
当改动属于以下类别之一时，必须执行联动分析：
.c/.h）进入联动搜索前，必须用 Read 读取 references/cross-cutting-patterns.md，加载完整的模式列表、搜索关键词和判断标准。禁止凭记忆或猜测选择搜索模式。
从已加载的 cross-cutting-patterns.md 中提取模式列表，按模式逐一搜索：
cmd_table, extra_cmd, msg_handler 等）callback_register, event_handler, hook_list 等）driver_list, module_init 等）default_config, cfg_default 等）#ifdef FEATURE_* / #if defined(HAS_*)）CMakeLists.txt, Makefile, Kconfig, *.mk）参考文档：ddev-spec/references/cross-cutting-patterns.md，包含每种模式的详细搜索关键词、grep 正则和判断标准。
优先使用 CodeGraph 结构化查询：
codegraph_search 搜索已知符号模式codegraph_callers 逆向追踪：找到引用同名模块/同目录文件的所有调用者grep 搜索模式关键字和正则（CodeGraph 未初始化时的回退）联动修改清单，每个联动点标注：
根据项目语言，在 spec 阶段将对应的编码规范约束前置写入 spec 文档，不得留到编码阶段临场决定。
.c / .h）必须先加载 ddev-c-pro skill，本阶段把以下约束写进 spec 文档：
context / session / handle 结构体，禁止把业务状态设计成全局变量switch、表驱动、状态机还是策略函数，不接受默认长链 if/else_t 后缀）、API 前缀、错误码枚举必须按 ddev-c-pro 规范提前约定@brief / @param / @return）在 spec 文档中就要明确要求，参照 ddev-comment-gen skill如果这些点在 spec 阶段说不清，说明还不该进入实现计划。
对于 C 项目，spec 文档至少要额外回答：
if/elsestatic 私有_t 后缀、宏命名规则是否已按 ddev-c-pro 规范约定ddev-comment-gen skill）如果不确定，优先选“架构规划”，再补接入点和流程图。
在实现开始前，文档至少要通过图讲清楚：
如果仓库存在 docs/architecture/，还必须讲清楚：
docs/architecture/ 再进入实现计划如果是 C 项目，还必须能看出：
switch、表驱动或状态机，而不是含糊留给实现时发挥ddev-c-pro skill 在 spec 约束中明确；Doxygen 注释要求是否已按 ddev-comment-gen skill 在 spec 约束中明确对于其他语言项目，必须能看出模块边界、接口契约和关键流程分发策略。具体编码规范由对应语言的审查 skill 决定，不需要在 spec 中堆砌语言无关的编码规范。
spec 文档完成后，必须逐项核对：
如有任一项不通过，必须在修复后再交给下游。