文档结构化审查

技能文档

---
name: compound-eng-document-review
title: 文档结构化审查
category: 办公效率
description: 对头脑风暴记录、方案、规格说明、架构决策记录（ADR）等各类文档做结构化审查，检查缺口、清晰度、完整性与组织结构，输出评分与关键改进项并直接修订。当用户需要审查文档、给方案挑毛病、检查文档是否完整清晰、文档定稿前打磨时触发。触发词：文档审查、方案评审、文档打磨、检查文档、文档定稿。
---

# 文档审查

通过结构化审查改进头脑风暴记录或方案文档。从零探索新想法不属于本技能范围。

## 技能工作流

### 步骤1：获取文档

- **用户提供了文档路径**：直接读取，进入步骤2。
- **未指定文档**：询问要审查哪份文档，或在 `docs/brainstorms/`、`docs/plans/` 中查找
  最近一份头脑风暴/方案记录。

### 步骤2：评估

通读文档并回答：

- 哪里不清晰？
- 哪些内容没有必要？
- 正在回避什么决策？
- 哪些假设没有说明？
- 哪里可能意外扩大范围？
- 按当前架构在技术上是否可行？
- 提案中是否存在安全影响？

这些问题用于暴露问题。此时只记录发现，先不修改。

### 步骤3：启用审查视角

根据文档内容启用专门的审查视角。扫描信号并应用匹配的视角：

| 视角 | 触发信号 | 检查内容 |
|------|---------|----------------|
| **产品** | 面向用户的功能、客户语言、市场主张、范围决策 | 问题界定、价值主张是否清晰、范围与目标是否匹配 |
| **设计** | UI/UX 描述、用户流程、线框图、交互描述 | 流程完整性、交互缺口、可访问性考量 |
| **安全** | 认证/授权、API 端点、个人信息、支付、令牌、加密 | 认证模型缺口、数据暴露风险、缺失的威胁考量 |
| **范围守卫** | 多级优先级（P0/P1/P2）、需求数量大（>8）、弹性目标 | 范围蔓延、过早抽象、伪装成需求的功能点 |
| **对抗** | 独立需求 >5 条、明确的架构决策、高风险领域 | 未说明的假设、乐观估计、单点故障、缺失的失败模式 |

任一信号命中即启用对应视角。多数文档触发 1-2 个视角；头脑风暴笔记可能一个都不触发。
视角启用后，把它的检查项融入评估与打分步骤，而不是单独跑一遍。

### 步骤4：打分

按以下标准给文档评分：

| 标准 | 检查内容 |
|-----------|---------------|
| **清晰度** | 问题陈述清晰，无含糊用语（「可能」「考虑一下」「试试」） |
| **完整性** | 必需章节齐全、约束条件明确、开放问题已标注 |
| **具体性** | 对下一步足够具体（头脑风暴 → 可以规划；方案 → 可以实施） |
| **YAGNI** | 无假想功能，选择了最简方案 |

如果审查发生在某个工作流内（头脑风暴或规划之后），还要检查：
- **用户意图还原度**——文档反映了讨论内容，假设经过确认

### 步骤5：找出关键改进项

在步骤2-4 发现的所有问题中，是否有一个特别突出？如果某项修改能显著提升文档质量，
它就是「必须处理」项，要醒目标出。

### 步骤6：执行修改

先呈现发现，然后：

1. **自动修复**小问题（含糊用语、格式），无需询问
2. 实质性修改（重排结构、删除章节、改变含义）**先征得同意**
3. **就地更新**文档——不另建文件、不加元数据章节

#### 精简指引

精简是有目的地移除不必要的复杂度，不是为短而短。

**应该精简：**
- 内容只为假想的未来需求服务，与当前无关
- 章节重复了其他地方已有的信息
- 细节超出下一步所需
- 抽象或结构增加了负担却没有带来清晰度

**不要精简：**
- 影响实施的约束或边界情况
- 解释为什么否决了其他方案的理由
- 尚待解决的开放问题

### 步骤7：读者测试（可选）

对必须自成一体的独立文档（入职指南、ADR、对外文档），可选做「新读者测试」：从文档
声明的目标出发生成 5 个读者问题（每个主要章节或决策一个），然后**只带着文档本身**、
不带任何对话上下文地逐题自问作答。

如果这些问题都能正确回答，说明文档自成一体；答不上来说明存在需要补齐的缺口。这是
「 Fresh eyes（全新视角）」测试的自动化版本。

依赖上下文的文档（头脑风暴笔记、方案文件、内部工作文档）跳过此步——读者本就有背景
上下文。

### 步骤8：提供下一步选项

修改完成后询问：

1. **再审一轮** —— 再来一次审查
2. **审查完成** —— 文档已就绪

#### 迭代指引

2 轮打磨之后建议收尾——边际收益大概率递减。但用户想继续就继续。

选择后把控制权交回调用方（工作流或用户）。

## 约束

- 修复有问题的具体章节，不重写整个文档。如果结构从根上就有问题，指出结构问题并征得
  同意后再重构。
- 审查中指出缺失的章节，但不擅自添加。由用户决定写什么。
- 保持改动最小。段落需要收紧就收紧，不扩大范围。
- 就地审查。不产出单独的审查文件或元数据章节。

## 成功标准

- 文档已通读并按四项标准打分
- 相关审查视角已启用并应用检查
- 关键改进项已带具体建议标出
- 用户拿到了清晰的下一步选项（再审或完成）
- 改动获准后文档已更新保存

使用说明

# 文档结构化审查

对方案、规格说明、ADR、头脑风暴记录等文档做结构化审查：五类审查视角 + 四项质量评分，输出关键改进项并就地修订。

## 使用

```text
帮我审查一下 docs/plans/支付重构方案.md
审查这份 ADR，看有没有缺口和含糊的地方
```

## 工作原理

按「获取文档 → 评估 → 启用审查视角 → 打分 → 找关键改进 → 执行修改 → 读者测试 → 下一步」
流程执行。产品/设计/安全/范围守卫/对抗五类视角按文档信号自动启用；清晰度、完整性、
具体性、YAGNI 四项标准逐项评分；小问题自动修复，实质性修改先征询确认。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。