doc-review

name	doc-review
description	从测试视角审查设计文档的完整性与精炼度，检查 API 定义、错误处理、配置格式、业务规则、跨文档一致性等维度
when_to_use	当用户希望检查设计文档是否足够完整，能支撑测试团队编写和执行用例
argument-hint	["doc_dir"]
arguments	["doc_dir"]
user-invocable	true
allowed-tools	Read Glob Grep
effort	high

设计文档审查

审查 $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：精炼度与可读性

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

第三步：输出审查报告

# 文档审查报告

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

## 维度评分

| 维度 | 评分 | 关键缺口 |
|------|------|----------|
| 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. 补充的工作量大小）