메뉴
在代码修改前需要编写 spec 文档且应优先用图表达边界、入口、流程和改动关系时使用（仅限代码改动场景，非项目级架构文档初始化）
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
在当前会话里按已写好的实现计划顺序执行任务时使用
在已有规格或多步骤任务需求、且在动代码之前使用。若上游 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 文档完成后，必须逐项核对：
如有任一项不通过，必须在修复后再交给下游。