Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
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.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/docevilOck/agent-skills-hook --skill ddev-specThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
| 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 最终定版时，写入设计依据摘要。本 skill 完成后，禁止 agent 自动进入下游阶段（ddev-detail / ddev-plan / ddev-exec / ddev-gate）。
docs/architecture/，先做项目级架构越界检查：
ddev-diagram 绘制规范手写所有 ASCII 图。在画任何图之前，必须先从源码中理解”代码现在长什么样”。spec 图里画的模块边界、接口方向和文件路径必须与代码实际结构一致。
*.h）和关键源文件优先使用 CodeGraph 结构化查询：
codegraph_files 了解涉及的目录和文件结构codegraph_context 理解模块的架构角色和关键符号codegraph_explore 批量查看相关源码CodeGraph 未初始化时回退方案：
Glob 查看目录结构grep 搜索关键符号和 include 关系Read 打开关键头文件确认接口不要求单独文档，但 spec 文档中必须包含：
Read 目标函数的完整代码（不是 grep 片段、不是 codegraph 摘要），确认完整 if-else 分支结构和已有错误/异常处理块后，再定插入位置在代码现状分析完成后、开始画图之前，必须回答一个核心问题：本次设计是在现有框架里扩展，还是在现有框架之外另起炉灶？
原则：默认扩展，例外新建。优先在现有模块、现有接口、现有模式上扩展；新建模块/接口/模式必须有充分理由。
识别现有扩展点：当前涉及的模块已提供了哪些扩展机制？
CMakeLists.txt、Makefile 中的源文件列表）识别现有模式：同类功能在代码库中是怎么组织的？
.c/.h、模块目录结构、测试文件位置）识别参考实现：找到仓库中与本次改动最相似的已有功能作为设计模板，标注其文件路径和关键符号。找不到时显式声明"本仓库无类似实现可参考"。
功能等价搜索：对本次设计中每个核心功能点（按功能语义，不是按模式），在代码库中搜索已有实现——
搜索结果写入 功能复用决策清单：
| 功能点 | 候选已有实现 | 决策 | 理由 |
|---|---|---|---|
| 打印机状态管理 | prt_ctx_t.status in prt_core.h:45 | 扩展已有 | 新增枚举值即可，不需新字段 |
| 命令解析 | 无 | 新建 | 仓库中无类似命令格式解析器 |
决策分三档：复用（直接调用已有）/ 扩展已有（修改已有接口或结构体）/ 新建（确认无等价实现）。新建必须给出"为什么不能复用/扩展"的理由。
逐项对齐检查：对本次设计的每个关键决策，核对——
在画图之前，必须搜索并识别本次改动需要联动修改的所有位置。不完成此步骤不得开始画图。
当改动属于以下类别之一时，必须执行联动分析：
.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 规范提前约定N * 1024 / N * 1024 * 1024 可读表达式并命名宏（如 MOD_TX_BUF_SIZE (16 * 1024)），禁止在示例代码或接口契约里裸写大数@brief / @param / @return）在 spec 文档中就要明确要求，参照 ddev-comment-gen skill如果这些点在 spec 阶段说不清，说明还不该进入实现计划。
对于 C 项目，spec 文档至少要额外回答：
if/elsestatic 私有_t 后缀、宏命名规则是否已按 ddev-c-pro 规范约定ddev-comment-gen skill）如果不确定，优先选”架构规划”，再补接入点和流程图。
spec 文档头部必须包含一张 Delta Summary 表，用 ADDED / MODIFIED / REMOVED 三段显式列出本次改动相对现有代码的变更面。这张表的数据来自前面已完成的代码现状分析和联动影响分析——不引入新分析，只做格式化汇总。
## Delta Summary
| 类型 | 对象 | 说明 | 复用决策 |
|------|------|------|---------|
| ADDED | `usb_hid_report_ctx_t` | 新增上下文结构体，管理 HID report 生命周期 | 扩展 `usb_core_ctx_t` 不可行：生命周期不同（HID report 在 EP 回调内，core ctx 跨请求） |
| ADDED | `src/usb/usb_hid.c` | 新增 HID 类驱动实现文件 | 新建：仓库无 HID 类驱动可复用 |
| MODIFIED | `usb_ep_handler()` in `src/usb/usb_core.c` | 增加 report ID 分派逻辑，原数据路径不变 | — |
| MODIFIED | `CMakeLists.txt` | 追加 `usb_hid.c` 到 SRC_FILES | — |
| REMOVED | `g_usb_tx_buffer` in `src/usb/usb_core.c` | 全局发送缓冲废弃，改为 ctx 内嵌 | — |
在实现开始前，文档至少要通过图讲清楚：
如果仓库存在 docs/architecture/，还必须讲清楚：
docs/architecture/ 再进入实现计划如果是 C 项目，还必须能看出：
switch、表驱动或状态机，而不是含糊留给实现时发挥ddev-c-pro skill 在 spec 约束中明确；Doxygen 注释要求是否已按 ddev-comment-gen skill 在 spec 约束中明确对于其他语言项目，必须能看出模块边界、接口契约和关键流程分发策略。具体编码规范由对应语言的审查 skill 决定，不需要在 spec 中堆砌语言无关的编码规范。
spec 文档完成后，必须逐项核对：
如有任一项不通过，必须在修复后再交给下游。
Based on SOC occupation classification