# Doc Review

> 从测试视角审查设计文档的完整性与精炼度，检查 API 定义、错误处理、配置格式、业务规则、跨文档一致性等维度

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

---


# 设计文档审查

审查 `$doc_dir` 目录下的设计文档，从测试视角评估其完整性和精炼度。未传 `$doc_dir` 时，默认审查当前 workspace 的 `docs/` 目录。

## 审查流程

### 第一步：文档盘点

读取 `$doc_dir` 下所有文件，将每份文档分类为：
- **系统总览**：描述整体架构、API 列表、流程
- **迭代变更**：描述增量改动
- **接入指南**：描述组件/SDK 的使用方式
- **其他**：标注类型

### 第二步：按 7 个维度逐项检查

每个维度给出评分：
- **PASS**：覆盖充分
- **PARTIAL**：有覆盖但存在缺口（列出具体缺什么）
- **MISSING**：完全未覆盖

#### 维度 1：API 契约完整性

对文档中提到的每个 API 端点检查：

- 请求字段是否列出：字段名、类型、是否必填、默认值、取值范围
- 响应结构是否以表格或结构化方式定义
- 是否有错误响应的定义（错误码、触发条件、响应格式）
- 是否至少有一个调用示例

**常见缺口**：迭代文档新增了字段但从未汇总成完整 Schema；字段只列了名字没标必填/可选/默认值；响应结构只有文字描述没有结构化定义。

#### 维度 2：错误处理与降级

对文档中涉及的每个外部依赖（缓存、下游服务、文件系统等）检查：

- 依赖不可用时的行为是否说明
- 超时和重试策略是否定义
- 降级/兜底逻辑是否描述
- 错误是否会传播给调用方，以什么形式

**常见缺口**：只描述了正常流程；"读 Redis"但没说 Redis 不可用或 key 不存在时怎么办；下游服务故障完全未提及。

#### 维度 3：配置与数据格式

对文档中提到的每个配置文件、数据文件、数据存储检查：

- 格式是否说明（JSON/YAML/TSV 等），是否有结构示例
- 每个字段的名称、类型、含义、取值范围是否定义
- 键值存储（如 Redis）的 Key 格式和 Value 类型是否说明

**常见缺口**："从配置读取"但没给配置结构；"存入 Redis"但没给 Key 格式；引用了特征字段数量但没列出字段名。

#### 维度 4：业务规则精确度

对文档中的每条业务规则检查：

- 是否精确到可以直接编写测试断言
- 数值边界是否明确（左闭右开？包含还是不包含？）
- 多规则冲突时的优先级/执行顺序是否定义
- 涉及计算的公式是否显式给出

**常见缺口**："按条件过滤"但没列出条件；"按优先级排序"但没定义优先级计算方式；区间表示不明确。

#### 维度 5：跨文档一致性

- 同一字段在不同文档中名称是否一致
- 默认值在不同文档中是否矛盾
- 流程描述在总览和详细文档中是否一致
- 总览文档是否已同步所有迭代变更（是否过时）

**常见缺口**：总览文档仍然描述迭代前的行为；迭代文档说"改 X 为 Y"但总览还写着 X；同一概念在不同文档中命名不同。

#### 维度 6：辅助/管理接口覆盖

- 所有管理类、查询类 API 是否列出
- 每个接口是否有请求/响应定义
- 用途是否清晰（用于数据初始化、状态查询还是调试）

**常见缺口**：管理接口只在表格中列了一行但无任何详细定义；测试基础设施接口（初始化数据、查询结果）完全没有文档。

#### 维度 7：精炼度与可读性

- 同一信息是否在多处重复且措辞不一致
- 关键信息是否使用表格/列表呈现（而非埋在大段文字中）
- 单篇文档是否聚焦一个关注点，不过长
- 读者能否快速定位某个主题的信息

### 第三步：输出审查报告

```markdown
# 文档审查报告

## 文档盘点
（文档列表及分类）

## 维度评分

| 维度 | 评分 | 关键缺口 |
|------|------|----------|
| API 契约完整性 | PASS/PARTIAL/MISSING | ... |
| 错误处理与降级 | PASS/PARTIAL/MISSING | ... |
| 配置与数据格式 | PASS/PARTIAL/MISSING | ... |
| 业务规则精确度 | PASS/PARTIAL/MISSING | ... |
| 跨文档一致性 | PASS/PARTIAL/MISSING | ... |
| 辅助接口覆盖 | PASS/PARTIAL/MISSING | ... |
| 精炼度与可读性 | PASS/PARTIAL/MISSING | ... |

## 详细发现

（对每个 PARTIAL/MISSING 维度，列出具体缺口：
 - 缺什么
 - 应该补充在哪份文档中
 - 补充后应该长什么样（给出示例片段））

## 优先修复项

（按影响面排序的 Top 5 待修复项，说明：
 1. 修复后能解锁多少测试场景
 2. 补充的工作量大小）
```