document-review

文档审查

通过结构化审查改进头脑风暴或计划文档。

工作规则

• 先评估再编辑，保留与实现相关的约束和理由，并区分小幅修改与实质性决策。
• 仅要求审查的请求授权提出发现，不授权编辑文件。只有在用户要求编辑或批准拟议修改后，才能应用更改；对于已经授权的更改，不要再次询问。

步骤 1：获取文档

**如果提供了文档路径：**读取文档，然后继续步骤 2。

**如果未指定文档：**询问要审查哪份文档（在 Claude Code 中使用 AskUserQuestion，在 Codex 中使用 request_user_input，或在聊天中以编号选项作为后备方案），或者查找 docs/brainstorms/ 或 docs/plans/ 中最近的头脑风暴或计划文档。

步骤 2：评估

通读文档并思考：

• 哪些内容不清楚？
• 哪些内容没有必要？
• 哪项决策被回避了？
• 哪些假设没有明说？
• 哪些地方可能导致范围意外扩大？
• 结合当前架构，这在技术上可行吗？
• 文档对当前系统的描述是否属实？逐项追溯所有可核查的说法（文件路径、函数、命令或配置名称、端点、引用的 PR 或 issue、数字，以及「重试」等动词暗示的行为）并仅通过阅读进行核实。对于较长的文档，抽样检查并说明覆盖范围。
• 拟议内容是否存在安全影响？

这些问题有助于发现问题。先记录发现，不要立即修复。

步骤 3：启用审查视角

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

视角	信号	检查内容
产品	面向用户的功能、客户用语、市场宣传、范围决策	问题定义、价值主张是否清晰、范围是否符合既定目标
设计	UI/UX 相关内容、用户流程、线框图、交互说明	流程是否完整、交互是否存在缺漏、无障碍考量
安全	身份验证/授权、API 端点、PII、支付、令牌、加密	身份验证模型的缺漏、数据暴露风险、威胁考量是否缺失
范围守护	多个优先级层级（P0/P1/P2）、需求数量较多（>8）、扩展目标	范围蔓延、过早抽象、伪装成需求的功能
对抗性审查	>5 项不同需求、明确的架构决策、高风险领域	未明说的假设、过于乐观的估算、单点故障、缺失的故障模式

只要任何一项信号匹配，就启用相应视角。大多数文档会触发 1-2 个视角；头脑风暴笔记可能一个也不触发。启用某个视角后，应将其检查内容融入评估和评判步骤，而不是单独进行一轮审查。

步骤 4：评判

根据以下标准为文档评分：

标准	检查内容
清晰度	问题陈述清晰，没有含糊措辞（如「可能」「考虑」「尝试」）
完整性	必要章节齐全，约束明确，待解决的问题已标出
具体性	足以支持下一步工作（头脑风暴 → 可制定计划，计划 → 可开始实现）
YAGNI	没有假设性功能，并选择了最简单的方案
准确性	已核实的说法与来源相符（步骤 2）；与来源矛盾的说法属于缺陷，报告时须提供冲突所在的 file:line；超出声明覆盖范围的说法属于未经核实，而非已通过

如果在工作流中调用（在 /ia-brainstorm 或 /ia-plan 之后），还需检查：

• 忠实体现用户意图：文档反映讨论内容，假设已经过验证

步骤 5：找出最关键的改进

在步骤 2-4 发现的所有问题中，是否有一个问题尤为突出？如果某项内容能显著提升文档质量，它就是「必须解决」的问题。请将其突出标明。

第 6 步：进行更改

先呈现调查结果，然后：

1. 应用已授权的编辑，在请求的范围内进行，包括细微的措辞和格式修正。对于仅要求审查的请求，将这些内容作为建议报告。
2. 征求对授权范围之外更改的批准（重组、删除章节、更改含义）。通过 AskUserQuestion（Claude Code；如果尚未加载，则使用 ToolSearch select:AskUserQuestion 加载）或 request_user_input（Codex）征求批准；如果不可用，则在聊天中列出编号选项。提问前，先按下方约定呈现调查结果，让决策依据具体明确。
3. 更新文档：仅对已授权的更改进行行内修改；否则返回调查结果。

呈现供决策的调查结果

作出决策的读者没有打开文档，也不记得其中的标识符。本规则仅适用于审批流程（上文第 2 步）；交由自动修复的调查结果可跳过。任何需要批准的调查结果都须按以下顺序呈现：

1. 不作更改的后果：用一句话说明会出什么问题，以及会影响谁。不要包含读者需要查找的标识符。
2. 建议措施：以明确无误的方式标出。
3. 更改意图：用一句话说明目的。
4. 实现方式：最多两句话，且最多包含两个不透明锚点（定义见下文）。

更深入的内容（文件追踪、多跳调用路径、相互竞争的调用点）不予展示；可在结尾用一句话说明可提供这些内容。限制：每句话最多使用两个行内代码片段；不使用差异代码块；仅在确实需要新增内容且不超过五行时，使用原始代码块。

根据作用而非词汇对不透明锚点进行分类：

• 导航锚点（文档自身定义的 ID）保留 ID，并在首次提及时附上简短说明：R6（在低风险调用时抑制对等面板），不得只写 R6。
• 来源锚点（工单 ID、PR 编号）仅当所引用的事件会改变决策时，才注明其作用；否则移至追踪内容。
• 实现锚点（函数、文件、行名称）转换为其在决策中的作用（例如“终止失败判断条件”）；仅当决策取决于精确范围时，才保留确切符号。对于被证伪的准确性声明，应保留相互矛盾的 file:line，作为唯一的实现锚点。

如果调查结果只有通过“去看某个章节”才能作出决策，那么无论内容多正确，都不合格。

简化指南

简化的目的是去掉不必要的复杂性，而非一味缩短内容。

适合简化的情况：

• 内容只服务于假设中的未来需求，而非当前需求
• 章节重复了其他部分已经涵盖的信息
• 细节超出采取下一步行动所需
• 抽象或结构增加了负担，却没有提升清晰度

不应简化的内容：

• 会影响实现的约束或边缘情况
• 解释为何否决其他方案的理由
• 需要解决的未决问题

第 7 步：提供下一步操作

完成更改后，询问：

1. 再次完善——再进行一轮审查
2. 审查完成——文档已就绪

迭代指导

经过 2 轮完善后，仅当不存在重大问题时才建议完成。如果用户想继续，最多允许总计 4 轮。只有当某一轮发现无需进行重大修改时，才能认定已收敛。达到 4 轮后停止。报告“审查次数已达上限；如需继续，请提供新的方向。”在交接时列出尚未解决的发现和未经验证的说法。即使用户提出要求，未获得新的任务框架也不得超过 4 轮。

撤回先前答复已解决的问题。从第 2 轮起，提出任何尚存发现之前，都要根据本次会话已作出的决定逐一判断。如果先前的答复已解决或否定某项发现，就不要再次提出：用一行说明该发现是什么，以及由哪条答复将其撤销，然后继续，并在摘要中将其记录为 withdrawn，注明撤销该发现的决定。关键区别在于：由用户决定（跳过、推迟或确认某项事实）导致的撤回是永久的，之后每一轮都不再提出该发现；由待处理的修复导致的撤回则是暂时的，如果下一轮再次出现该发现，就必须重新提出，不能继续将其压下。按需评估：只有在某项发现即将提出时才进行判断；不要在每次答复后都重新扫描。（代码审查同样适用此规则；关于如何协调先前讨论，请参阅 ia-code-review。）

在用户选定后，将控制权交还给调用方（工作流或用户）。

约束

• 只修改目标部分，不要重写整份文档。如果文档结构存在根本性问题，应指出结构问题并征求重构许可。
• 在审查中指出缺失的部分，但不要添加，由用户决定是否纳入。
• 尽量减少改动。若段落需要精简，就精简；不要扩大范围。
• 在文档中直接审查，不要创建单独的审查文件或元数据部分。

成功标准

• 阅读文档，并依据全部五项质量标准进行评分
• 启用相关审查视角并完成检查
• 找出关键改进点并给出具体建议
• 为用户提供明确的下一步选择（完善或完成）
• 获得批准后保存修订后的文档

特定任务参考

实施或审查相应行为前，请先阅读相关参考资料：

• 关于独立文档的可选零上下文读者测试： reader-test.md。