# Ddev Doc Review

> 文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。

- Skill: `docevilock/ddev-doc-review` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add docevilock/ddev-doc-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/docevilock/ddev-doc-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: docevilock (https://skillmd.com/u/docevilock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/docevilock/ddev-doc-review

---


# 文档审查

将文档审查任务派发给独立子代理，以独立视角审视文档质量，而不是让主 agent 自审自评。

> ⚠️ **HARD GATE — 禁止主代理自审**
>
> 加载本 skill 后，**必须派发 General 子代理执行审查**。主代理在任何情况下都**禁止**自行阅读文档并产出审查结论。
> 跳过派发 = 违规。无例外。不得因为"文档较短""只改了一点""时间紧"等理由绕过。

## 何时使用

- 写完 spec / design / plan 文档后，需要确认文档质量
- 代码改动完成后，需要确认关联文档是否准确反映改动
- 执行完成后，需要审查 `implementation-notes.md` 中 AI 自行记录的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致
- 用户要求"审查这个文档""帮我看下文档有没有问题"
- 准备合并或发布前，做文档质量门禁

## 核心流程

0. **⚠️ 硬门禁**：主 agent **必须先 `Read` `implementation-notes.md`**（如存在），了解 AI 在执行阶段的 Design Decisions / Deviations / Tradeoffs，作为审查上下文的一部分。
1. 主 agent 定位待审查的文档路径和关联的代码改动范围
2. 主 agent 读取文档和代码改动，整理审查上下文
3. ⚠️ 主 agent **必须**派发 **General 子代理**执行审查（**禁止主 agent 自行审查**，见上方 HARD GATE）
4. 子代理返回审查报告
5. 主 agent 汇总问题、评估严重度、向用户呈现
6. **主 agent 在同一轮对话中立即逐项修复所有阻塞和重要问题**——不得推迟到后续步骤或下一轮对话。
7. **⚠️ 写入决策文档**：修复完成后，**必须**将本轮审查中发现的未记录决策、遗漏取舍、新偏离写入 `implementation-notes.md`（按 ddev-exec 的四维度格式：Design Decisions / Deviations / Tradeoffs / Open Questions）。此步骤不可跳过——即使本轮未发现新决策，也须追加一条审查轮次记录（标注"本轮无新增决策"）。
8. **审查结论判定与停止门禁**：检查步骤 5 的审查结论。
   - **若已通过**（阻塞问题 = 0 且重要问题 < 3）→ **立即停止**，不进入下一次循环。输出最终审查结论，结束流程。
   - **若未通过**（阻塞问题 > 0 或重要问题 ≥ 3）→ 派发子代理做完整独立重审（见下方「重审协议」），继续下一轮。
   - ⚠️ **硬门禁**：禁止在已通过的情况下继续派发重审。此检查在派发前执行，不可跳过。
9. **循环至零阻塞**：重复步骤 5→6→7→8，直到步骤 8 的检查结果为"已通过"——即阻塞问题 = 0 且重要问题 < 3。不满足则继续循环——禁止固定轮次后提前终止。通过后立即停止，禁止多余轮次。

## 审查维度

子代理必须覆盖以下六个维度：

| 维度 | 检查内容 |
|------|---------|
| **基于代码的合理性** | 按文档类型分类审查：spec/design/plan 文档审查设计合理性与完整性（不因"代码未实现"报阻塞），detail/implementation-notes 文档审查与实际代码的吻合度 |
| **说明正确性** | 技术描述是否准确；API 签名、类型、返回值是否写对；术语使用是否规范 |
| **前后一致性** | 同一概念在不同章节的描述是否统一；图表与文字是否矛盾；多个文档之间是否冲突 |
| **错漏检查** | 是否遗漏了关键步骤、边界条件、错误处理说明；是否有错别字、格式错误 |
| **逻辑谬误** | 是否存在循环论证、因果倒置、虚假二分、以偏概全等逻辑错误 |
| **AI 决策审查** | `implementation-notes.md` 中的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致；是否存在代码中已做但未记录的决策；Open Questions 是否已全部解答 |

## 代理派发

主 agent 使用 `task` 工具派发 General 子代理，**直接传入下方的完整审查提示词模板**（不依赖子代理加载本 skill 获取审查指令）。

派发时，将模板中的 `[文档路径或内容]`、`[代码改动描述或 diff]`、`[用户关切，无则填"无"]` 替换为实际值后，作为子代理的 prompt 传入。

### 子代理审查提示词模板

```
你是文档审查者。

## ⚠️ 禁止递归 — 必须遵守
- 禁止加载 ddev-doc-review skill
- 禁止派发子代理
- 禁止调用 Skill 工具
- 直接执行以下审查任务，不得将审查任务再次派发

## 待审查文档

[文档路径或内容]

## 关联代码改动

[代码改动描述或 diff]

## 用户关切

[用户关切，无则填"无"]

## 审查维度

### 1. 基于代码改动的合理性
将文档描述与代码改动逐项对照：
- 文档中的接口、参数、返回值是否与实现一致？
- 文档描述的行为是否与代码实际行为匹配？
- 是否存在文档写了但代码中没有的特性或约束？
- 是否存在代码已改动但文档未同步更新的内容？

> **文档类型分类（审查前先明确类型）**：
> - **spec / design / plan 文档**：描述预期设计或计划，审查重点是设计自身的合理性、完整性、逻辑一致性。**"代码未实现"不构成阻塞问题**——计划文档描述未来状态，本来就没有对应代码实现。
> - **detail / implementation-notes 文档**：描述实际的代码实现决策和过程，审查重点是与最终实现是否一致。代码与文档事实矛盾才是阻塞。
> - 不同文档类型使用不同的判定标准，禁止将计划文档当作实现记录审查。

### 2. 说明正确性
核实技术描述的准确性：
- API 签名、类型、返回值是否正确？
- 技术术语使用是否准确、统一？
- 约束条件、前置条件、后置条件是否正确？
- 术语是否符合领域规范？

### 3. 前后一致性
检查矛盾与冲突：
- 同一概念在不同章节的描述是否互相矛盾？
- 图表与配套文字是否一致？
- 多份文档之间（如有）是否存在冲突？
- 示例代码与对应的文字说明是否一致？

### 4. 错漏检查
识别遗漏和错误：
- 关键步骤、边界条件、错误场景是否已说明？
- 是否存在错别字、格式错误、失效引用？
- 失败模式和错误处理是否描述清楚？
- 是否存在应明确写出的隐性假设？

### 5. 逻辑谬误
检查推理错误：
- 循环论证："X 是对的，因为 X 这么说"
- 虚假二分：只给出两种选择但实际存在更多
- 相关与因果混淆：把相关性当成因果
- 以偏概全：从个别案例推广到一般结论
- 预设前提：把未经证实的假设当作论证前提

### 6. AI 决策审查
审查 `implementation-notes.md`（如存在）中 AI 自行记录的决策：
- **Design Decisions**：记录的设计决策是否与最终代码一致？是否有代码中已做但未记录的决策？
- **Deviations**：记录的偏离是否确实发生？偏离理由是否成立？是否存在未记录的偏离？
- **Tradeoffs**：记录的取舍是否与最终实现吻合？是否遗漏了重要的替代方案考量？
- **Open Questions**：是否全部已解答？未解答的问题是否会影响代码正确性？
- **产出**：审查中发现的未记录决策、遗漏取舍、新发现的偏离 → **必须写入 `implementation-notes.md`**（按 ddev-exec 的四维度格式追加），不只是标记问题

## 判定标准

**只标记会误导读者、引发实现错误或阻碍理解的问题。** 措辞偏好和风格瑕疵不算问题。
但文档与代码事实矛盾**永远是阻塞级问题**（适用于 detail/implementation-notes 文档；不适用于 plan/spec/design 文档）。

> **文档类型判定校准**：
> - **spec / design / plan 文档**：审查焦点为设计合理性、完整性、逻辑一致性。"代码与文档不符"不适用——计划文档描述未来状态，不存在对应代码实现。**禁止以"代码未修改"为由标记阻塞**。
> - **detail / implementation-notes 文档**：审查焦点为记录与实际实现的吻合度。代码与文档矛盾为阻塞。
> - 审查开始时先声明文档类型，所有问题标注以此为基准。

## 输出格式

## 文档审查报告

**审查文档：** [列表]

**关联代码改动：** [摘要]

**问题清单：**

| # | 严重度 | 位置 | 问题描述 | 建议修复 |
|---|--------|------|---------|---------|

**未记录决策（需写入 implementation-notes.md）：**

| # | 类别 | 内容 | 建议写入维度 |
|---|------|------|-------------|
|   | Design Decision / Deviation / Tradeoff / Open Question | 具体描述 | — |

> 即使本轮未发现新的未记录决策，也必须输出"本轮无新增"。

严重度定义：
- **阻塞**：文档与代码事实矛盾，会误导读者或引发实现错误
- **重要**：描述不准确、关键信息遗漏、前后矛盾
- **建议**：措辞优化、格式修正、补充说明

**审查结论：** 通过 / 需要修改

- 通过：阻塞 = 0 且重要 < 3
- 需要修改：阻塞 > 0 或重要 ≥ 3

若结论为"需要修改"，须逐项列出必须修复的内容。
```

## 输出格式

审查报告应包含：

```
文档审查报告
============

审查文档：[文档路径列表]
关联代码改动：[改动范围描述]

问题清单：
- [严重度] 文件:区域 — 问题描述 → 建议修复

未记录决策：
- [Design Decision/Deviation/Tradeoff/Open Question] 描述 → 建议写入位置

严重度定义：
- 阻塞：文档与代码事实矛盾，会误导读者或引发实现错误
- 重要：描述不准确、关键信息遗漏、前后矛盾
- 建议：措辞优化、格式改进、补充说明

审查结论：[通过 / 有条件通过 / 需要修改]
```

## 重审协议

修复后重新派发子代理审查时，**必须**遵守以下规则：

1. **从零完整审查**：子代理必须覆盖全部六个审查维度，与首次审查标准相同，不可退化为仅验证上轮问题的修复状态
2. **禁止引导性提示**：不得告诉子代理"上一轮发现了 N 个问题，检查是否修了"——这会让子代理退化为修复验证器，遗漏修复过程中新引入的问题
3. **传递完整上下文**：向子代理传递文档路径、代码改动范围、用户关切，与首次审查的输入完全相同
4. **独立判断**：子代理可能发现修复过程中新引入的问题，这正是完整重审的价值
5. **每轮写入**：重审后修复时同样要将本轮新发现的未记录决策/偏离/取舍写入 `implementation-notes.md`，不只在首轮写

## 约束

- ⚠️ **主代理禁止自行审查**——必须派发子代理，任何情况无例外
- ⚠️ **防递归**：主代理派发子代理时**必须**传入上方内嵌的完整审查提示词模板（含递归禁令），禁止让子代理加载本 skill 自行获取审查指令
- 子代理必须是独立视角，不能复用主 agent 的判断
- 发现文档与代码事实矛盾时，必须标记为阻塞
- 不允许用"看起来没问题""基本正确"等模糊表述放行
- 如果缺少代码改动信息，先向用户索要，不要退化成纯文档校对
- 子代理审查报告返回后，主 agent 必须在同一轮对话中立即修复阻塞和重要问题，不得仅记录或推迟
- 修复后重审必须是完整独立审查（覆盖全部六维度），禁止退化为仅验证上轮修复点
- **审查为补充而非推翻**：对 `implementation-notes.md` 的写入仅限于补充遗漏的决策、取舍和偏离，不得修改或推翻 spec/detail/plan 中已确定的大体路径、架构决策和核心设计。审查发现的问题修复也必须服从上游文档的既定方向