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-detail |
| description | 代码修改场景下，spec 文档确认后，需要继续以图优先方式梳理结构体定义、数据流和流程时使用 |
当 spec 文档已被确认，需要在编码前继续细化结构体、数据流、流程图等实现细节时使用。默认先出图，再补极少文字。本 skill 仅用于代码改动场景。
detail 文档默认采用“图优先，文辅佐”表达，只写本次改动需要落地的结构体、数据流、流程和约束：
不要把本可画清的关系翻写成长段说明。文字只补限制、例外和阅读提示。
不要写“明确不做什么”“这部分不负责什么”的清单。凡是 detail 文档没有写到的结构、数据流、流程和约束，默认都不属于这次改动范围。
它负责把 spec 文档进一步拆成三类图文产物：
在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。加载完成前禁止写任何 ASCII 图。
详细拆解文档默认落到 docs/plans/YY-MM-DD_<topic>/detail/，按职责拆成：
<name>-overview.mdstructures/<name>.mddataflow/<name>.mdflows/<name>.mdtests/<name>.md（可选，由 ddev-pc-test skill 产出）overview / index 类总览文档必须放在 detail/ 根目录，不要放进 structures/、dataflow/、flows/ 或 tests/。子目录只放对应职责的详述文档和图源。
根目录 overview 必须包含一张"文档分布与说明"文本图，把本次 detail 下生成的所有文档、目录层级、阅读顺序和文档用途可视化出来。
如果某一类文档过长，不要继续往单文件里堆，先在 detail/ 根目录保留短总览，再把详述、错误路径、状态迁移、图文说明拆到对应子目录。
默认处理结构体、缓冲区、协议帧、配置和数据流等实现细节。支持 C / Rust / C++ / Python / TS 等多种语言，输出重点是”状态归属、数据边界、流程分发”。
对于 C 项目（.c / .h），本阶段必须加载 ddev-c-pro 和 ddev-comment-gen skill，将设计规范、命名规范、Doxygen 注释标准落实到结构体定义、API 签名和文档约束中。对于其他语言项目，如果有对应的编码规范 skill，也应在此阶段加载并落实。
只有在下面条件基本成立时才进入：
如果还在反复改模块边界、职责切分或接入方式，先回到 ddev-spec，不要在这里提前堆细节。
这个 skill 只细化本次改动真正相关的结构体、数据流和关键流程。
这里写出来的内容，应当能直接支撑下游实现计划和最终验收；没有写进 detail 文档的部分，默认不进入这次实现拆解。
开始前至少定位这些输入：
以下为强制步骤，不可跳过：
.h）中搜索并读取优先使用 CodeGraph 结构化查询：
codegraph_search 搜索对应结构体名/枚举名/typedef 名codegraph_node 获取完整定义（含字段类型、注释）codegraph_explore 批量获取相关符号源码CodeGraph 未初始化时回退方案：
grep 在头文件（*.h）中搜索 typedef struct / enum / typedef 声明Read 打开搜索到的头文件，确认精确定义收集结果必须体现在 detail 文档中：
src/module/xxx.h:42）建议按下面顺序落盘，避免前后反复打架：
detail/<name>-overview.mddetail/structures/*.mddetail/dataflow/*.mddetail/flows/*.mddetail/<name>-overview.md 必须索引所有子文档。dataflow 和 flows 文档必须引用对应结构体文档名，保证后续 ddev-gate 能做一一映射。总览先给图，再给一句话导航。
拆分目标是避免单份 detail 文档过长，确保 AI 和后续实现者都能快速定位，优先按图的职责拆。
出现下面任一情况，就不要继续维持单文件：
detail/ 根目录保留一个短总览文件，负责入口、边界、索引和导航final-v2、misc 这类无语义命名dataflow/、flows/ 或 structures/ 目录里创建 *-overview.md；这些目录里的文档应当是具体详述、错误路径、状态迁移、主流程图或结构体说明如果主题较复杂，先建立总览入口：
<name>-overview.md其中 overview 只放范围、主链路、边界、引用关系、文档分布图、简图、子文档列表和阅读顺序。
如果数据流较复杂，优先把细节拆成：
dataflow/<name>-details.mddataflow/<name>-errors.mddataflow/<name>-states.md其中：
details 放逐步骤转换、字段流转、模块协作细节errors 放错误入口、回退、重试、异常出口states 放状态迁移、状态持有者、枚举含义、并发边界如果规模更大，再按子链路拆，例如：
dataflow/rx-details.mddataflow/tx-details.mddataflow/rx-errors.mddataflow/tx-errors.md如果单张流程图已经覆盖多个问题，优先把图和路径拆成：
flows/<name>-main.mdflows/<name>-exceptions.md其中：
main 放主流程图和必要简述exceptions 放异常路径、超时、失败处理、回退流程如果结构体很多，不要做一个超长总表。优先按模块或职责拆：
structures/<module>-context.mdstructures/<module>-payloads.mdstructures/<module>-buffers.mdstructures/<module>-states.md如果仍需总入口，再补一个：
detail/<name>-overview.md总览文件必须位于 detail/ 根目录，至少要包含：
文档分布图使用手写 ASCII / text 图，不依赖 PlantUML 渲染。示例：
detail/
├── printer-job-overview.md # 总入口：范围、阅读顺序、文档分布
├── structures/
│ ├── job-context.md # 作业上下文与状态所有权
│ └── page-buffer.md # 页面缓冲区生命周期
├── dataflow/
│ ├── rx-details.md # 输入到作业上下文的数据转换
│ ├── rx-errors.md # 输入错误、回退和状态复位
│ └── rx-states.md # 状态迁移和持有者
├── flows/
│ ├── main.md # 主流程图与简述
│ ├── exceptions.md # 异常路径流程
└── tests/ # 可选，由 ddev-pc-test 产出
├── protocol-overview.md # 测试总览与可测试性结论
├── protocol-cases.md # 测试用例清单
└── protocol-env.md # 测试环境与依赖
阅读顺序：overview -> structures/job-context -> dataflow/rx-details -> flows/main
如果图本身不复杂，但文字说明很长，优先采用：
detail/<name>-overview.md 放图和 3-8 行说明dataflow/<name>-details.md 或 flows/<name>-main.md 放长解释如果图本身就复杂到需要独立维护，则采用：
.md 只放 ASCII 图和用途说明不要把几十行图源、ASCII 图和长篇解释混在同一个 markdown 里。
拆分后必须保证：
detail/<name>-overview.md 文件能跳到所有子文档details/errors/states 文件明确回指 detail/<name>-overview.mdflows 文档明确指向对应 dataflow 文档dataflow 文档明确指向对应 structures 文档如果拆完之后还需要靠全文搜索才能知道去哪里看，说明拆法失败。
根据项目语言，在 detail 阶段强化对应语言的结构约束。
.c / .h）必须先加载 ddev-c-pro skill，这一步必须把”禁全局变量、禁分支失控、禁职责混杂”落实到结构体和数据流层，同时加入 ddev-c-pro 的通用编码规范：
/**< */，参照 ddev-comment-gen skill），公开 API 必须有 @brief / @param / @return_t 后缀，公开 API 统一模块前缀，宏全大写 + 模块前缀，私有函数用 static在结构体文档和数据流文档里，至少要明确：
switch、状态机还是表驱动ddev-comment-gen skill 在文档中明确；模块命名前缀、类型 _t 后缀、错误码枚举是否已按 ddev-c-pro skill 在文档中明确建议按职责拆成这些目录：
references/：规则、模板、判断标准structures/：结构体定义文档dataflow/：数据流规划文档flows/：流程图文档tests/：PC 测试用例文档（由 ddev-pc-test skill 产出，可选）如果内容复杂，可以在这些目录下继续使用“入口索引 + 分主题子文档”的方式，而不是强行维持单层平铺。
如果是 C 项目，还要额外满足：
ddev-c-pro skill 在文档中明确；Doxygen 注释标准已按 ddev-comment-gen skill 在文档中明确，可直接作为编码和审查依据对于其他语言项目，需要满足：状态所有权清晰、数据边界明确、关键流程分发策略可在图中直接读出。具体编码规范和注释标准由对应语言的审查 skill 决定。
完成这一步后，至少应能直接交给下游使用：
ddev-plan 可以据此拆出精确的实现步骤ddev-gate 可以据此对照“结构体、状态、数据流、关键分支”是否按设计落地如果当前 detail 文档还做不到下面任一项，就不算完成：
overview / index 总览文档放进 dataflow/ 或 flows/，导致 detail 根目录没有统一入口detail 文档完成后，必须逐项核对：
ddev-plan 是否能据此拆出精确的实现步骤？ddev-gate 是否能据此对照验收？如有任一项不通过，必须在修复后再进入下一步。
这一步确认完之后：
ddev-pc-test，判断本次修改是否可在 PC 上写测试 demo 直接验证；如果可以则产出测试用例文档和 demo 代码。如果不需 PC 测试或不可测试，直接跳过。ddev-plan 把已经确认的内容拆成可执行步骤。如果实现已完成、准备验收，则把这些 detail 文档作为 ddev-gate 的直接输入。若此前通过 ddev-pc-test 产出了测试 demo，ddev-gate 阶段必须跑通该 demo。