メニュー
代码修改场景下，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-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。