夜雨聆风
全方位审核 AI 写的文档:一个多智能体 Doc Quality Loop Skill 的设计
AI 现在写文档很快。
PRD、技术方案、接口说明、验收标准、测试计划，过去要拆几轮会才能凑齐的东西，现在一个 Agent 很快就能生成一版。
看上去还挺像样。
标题完整，术语正确，结构规整，甚至会主动写异常路径和验收标准。
麻烦也在这里。
很多 AI 文档的问题不会直接暴露在句子表面。它们藏在系统关系里：一个状态没闭合，一个字段前后叫法不一致，一个异常路径没有回到主流程，一个验收标准没有可执行条件，一个接口描述和 SSOT 对不上。
这些问题读起来不一定刺眼。
真正进入实现、测试、验收时，它们才开始制造返工。
我最近做的 zeng-doc-quality-loop，处理的就是这类问题。
它把文档审核做成一条质量收敛流水线：
-
多角色评审； -
冲突处理； -
定向修复； -
独立验证； -
过程审计； -
最终报告； -
全程落盘。
先提醒一句：它属于重型流程。
它会启动多轮 Agent，运行时间比较长，Token 消耗也比较大。适合关键 PRD、Spec、API 规范、技术设计文档、验收文档这类高风险文档。
普通小文档没有必要上这套流程。
30 秒快速阅读：
-
AI 文档的难点在隐蔽缺口：边界、异常、状态、数据模型、SSOT 对齐、测试可验证性。 -
人工审核当然重要，但 AI 文档的风险形态会显著抬高识别难度。 zeng-doc-quality-loop
用干净上下文和聚焦任务拆分审核目标，让不同 Agent 只盯自己的风险面。 -
整个流程围绕一个闭环：Review 发现问题，Fix 定向修复，Verify 独立确认，Audit 检查过程链条。 -
这套 Skill 成本不低，定位是关键文档质量门。
一、AI 文档的问题经常藏在“关系”里
一个例子。
文档里写：
系统应支持任务失败后的自动重试。
这句话本身没毛病。
但工程实现要继续追问：
-
哪些失败可以重试？ -
重试几次？ -
间隔怎么计算？ -
重试期间任务状态是什么？ -
用户看到什么提示？ -
重试失败后是否进入人工处理？ -
幂等键在哪里生成？ -
测试用例怎么证明这条路径走通？
如果这些问题没有答案，这条需求会在后面拆成很多临时决策。
开发临时补一个策略。
测试临时猜一个预期。
产品再临时解释一次。
最后系统里会出现几套口径。
AI 文档很容易把这种缺口包装成完整表达。它会写出顺滑的句子，也会补出看起来合理的段落。读文档的人如果只按自然语言阅读，很容易放过去。
文档审核最难的部分，已经转向“关系检查”：
-
字段和字段之间有没有冲突； -
状态和状态之间有没有断点； -
接口和 UI 有没有对齐； -
异常路径有没有回到可处理状态； -
验收标准能不能直接变成测试。
这类问题需要系统性扫描。
靠读感很难稳定覆盖。
二、传统人工审核的压力被放大了
人工审核仍然有价值。
关键需求、关键架构、关键验收口径，最后都需要人类判断。
但现在的压力比以前大很多。
第一，文档数量变多了。
AI 生成文档的速度提高后，一个项目里会很快出现更多 PRD、Spec、接口草案、验收清单、测试计划。每份都让人完整读一遍，时间和精力很快不够。
第二，AI 文档的缺陷形态更隐蔽。
人类很擅长识别明显的逻辑跳跃、表达混乱、章节遗漏。AI 文档的问题常常没有这么显眼。它会把结构补齐，把语气写稳，把术语用对，然后在关键关系上漏掉一环。
第三，审核者很难在一次阅读里同时保持多种敏感度。
产品要盯范围和用户价值。
架构要盯模型和系统边界。
开发要盯可实现性和异常路径。
测试要盯可验证性。
安全要盯失败模式和权限边界。
同一份文档，从不同角度看，风险完全不同。让一个人长期稳定覆盖所有视角，现实中很难。
所以，文档审核需要一套更稳定的外部结构。
三、zeng-doc-quality-loop 怎么跑
这个 Skill 的主流程大致是：
-
初始化，锁定 Rubric。 -
读取文档，判断文档类型。 -
为这份文档选择 2 到 4 个评审角色。 -
多个评审 Agent 并行输出问题。 -
Moderator 合并去重，识别冲突。 -
冲突进入讨论，必要时升级给人类裁决。 -
形成 review-consensus.json，作为权威问题清单。 -
Fixer 只按问题清单修复文档。 -
Verifier 独立检查修复是否成立。 -
Audit Agent 从磁盘重建全过程，检查审核链条是否可信。 -
Report Agent 生成最终质量报告。
这条流程的核心输出，不只是一份改过的文档。
它还会留下完整过程产物：
role-panel.jsonreviews/*.jsonconsolidated-review.jsonreview-conflicts.jsonreview-consensus.jsonfix-log.jsondraft.mdverdicts.jsonround-audit.jsonaudit-report.jsonquality-report.md
这些文件让每个问题都有来源，每次修复都有记录，每条验证都有证据。
四、多角色评审的核心是上下文隔离和目标聚焦
这里要讲清楚。
这里的“多角色”指任务分工和上下文隔离，和角色扮演没有关系。
真正有价值的是两件事。
第一，干净上下文。
每个评审 Agent 拿到的是自己的任务目标、Rubric 维度和文档内容。它不会被其他角色的判断提前污染，也不会在同一个长上下文里来回切换注意力。
第二，聚焦目标。
-
Developer Agent 只盯实现可执行性、边界、异常、伪闭环。 -
Architect Agent 只盯数据模型、状态流、系统边界。 -
Product Manager Agent 只盯需求完整性、范围和验收价值。 -
Security Agent 只盯失败路径、安全边界和权限风险。
这种拆分的意义在于降低任务混杂。
一个 Agent 同时检查十个维度，很容易写出宽泛意见。多个 Agent 各自盯住一个风险面，问题会更尖锐，也更容易追踪来源。
最后由 Moderator 做合并、去重和冲突处理。
这里的分工更像审计结构：
-
各自独立发现问题； -
主持人合并证据； -
分歧进入讨论； -
解决不了再交给人类。
五、Rubric 必须锁定
多轮审核最怕标准漂移。
第一轮很严格，第二轮为了让流程看起来收敛，Agent 开始放宽口径。
原来 P0 的问题，被解释成“当前阶段可以接受”。
原来要求验收标准可测试，后来变成“人工理解即可”。
原来要求对齐 SSOT，后来变成“后续再同步”。
所以这个 Skill 初始化时会把 Rubric 写入 rubric-locked.md。后续每一轮评审、修复、验证，都围绕同一套标准执行。
默认 Rubric 有十项：
-
R01 需求完整性 -
R02 主流程可执行性 -
R03 数据模型一致性 -
R04 边界与异常情况 -
R05 异常处理路径 -
R06 UI / API / 状态流一致性 -
R07 测试可验证性 -
R08 SSOT 对齐 -
R09 Mock / 伪闭环风险 -
R10 范围漂移
这十项覆盖的是文档作为工程输入的关键质量面。
文档能不能支撑实现，主要看 R02、R03、R04、R05、R06。
文档能不能支撑验收，主要看 R07。
文档会不会污染系统主线，主要看 R08、R09、R10。
六、分歧要留下证据
多 Agent 审核一定会产生分歧。
这很正常。
一个产品角色可能认为某个异常是低频场景。
一个开发角色可能认为这个异常会影响状态机闭环。
一个安全角色可能认为它会造成权限绕过。
这类分歧不能简单平均。
zeng-doc-quality-loop 会把冲突写入 review-conflicts.json。严重级别差异较大，或者一个角色认为是 P0 / P1、另一个角色明确认为无问题，就进入讨论。
讨论最多两轮。
如果仍然无法解决，进入人类裁决。
这一步的价值在于保留判断路径。
最后某个问题被降级、忽略、升级，都能看到依据。后面出了问题，也能回到当时的证据链，追到那个结论怎么来的。
七、Fixer 不能自己宣布完成
审核发现问题之后，流程进入 Fix Pass。
Fixer 的权限被刻意收窄：
-
只能修复共识问题清单里的条目。 -
不能顺手重写整篇文档。 -
不能改变章节顺序。 -
不能扩展原始范围。 -
每个 issue 必须有独立修复记录。
修完之后，Verifier 单独检查。
Verifier 不参与修复，只看三件事：
-
问题是否真正消失。 -
修复后文档里有没有证据。 -
Fixer 有没有引入新的 P0 风险。
每条验证结果写入 verdicts.json。
这个设计是为了避免 AI 工作流里最常见的自我放行：执行者说自己修好了，然后流程就结束。
在关键文档上，这个权限不能给执行者。
八、过程审计检查的是链条
Verifier 检查修复。
Audit Agent 检查流程。
这两个角色分开。
Audit Agent 不共享前面评审过程的上下文。它只拿到磁盘文件清单，然后从文件里重建全过程。
它会检查：
-
文件是否完整； -
issue ID 是否连续； -
P0 / P1 是否都有修复记录； action=FIXED
是否都有验证结果； -
关闭问题是否能被重建； -
冲突是否都有处理记录； -
人类裁决是否被记录； -
引入新 P0 是否触发升级。
这一步关心的是审核链条的可信度。
一个文档最终显示 APPROVED，还不够。系统要能回答：这个 APPROVED 是怎么来的，中间哪些问题被发现，哪些被修复，哪些被验证，哪些被人类裁决。
没有这条链，结论就很脆。
九、什么时候值得用
我会把它放在这些场景里：
-
核心 PRD 定版前； -
技术设计进入实现前； -
API 规范交给前后端并行开发前； -
验收标准交给测试前； -
AI 批量生成需求包之后； -
多份文档需要对齐同一个 SSOT 时； -
项目已经出现文档口径不一致，需要重建可信版本时。
我不会拿它处理错别字、格式调整、普通表达修改。
原因很简单：这些任务不在它的能力边界里。
它的输入、角色、Rubric、验证、审计，全部围绕工程质量收敛。拿它做文字编辑，方向就错了。
更合理的分层是：
-
普通文字修改，用编辑工具。 -
低风险说明文档，用轻量 Review。 -
关键工程文档，用 Doc Quality Loop。 -
轻量 Review 扫出结构性风险，再升级到 Doc Quality Loop。
十、使用方式
单文档审核：
zeng-doc-quality-loop spec.md
多文档一起审核：
zeng-doc-quality-loop prd.md api.md design.md --ssot PROJECT.md
指定最大轮次和 P1 阈值：
zeng-doc-quality-loop docs/*.md --max-rounds 5 --p1-threshold 3
多文档并行：
zeng-doc-quality-loop specs/*.md --parallel --output-dir .quality-loop
几个参数比较关键：
--ssot
：指定项目唯一事实源。 --rubric
：使用自定义审核标准。 --max-rounds
：限制最大收敛轮次。 --p1-threshold
：定义可接受的 P1 残留风险。 --parallel
：多文档批量处理。 --no-verify
：跳过独立验证，高风险文档慎用。
再次强调成本：
多角色、多轮次、修复、验证、审计都会消耗时间和 Token。
尤其是长文档、多文档并行、带 SSOT 对齐时，成本会明显上升。
十一、文档质量门会成为 Harness 的一部分
现在做 AI 工程，很多团队已经开始接受 Harness、Workflow、SSOT、Verifier、Audit 这些结构。
下一步会很自然：
把文档也纳入 Harness。
原因很直接。
文档是 Agent 执行、开发实现、测试验收的上游输入。上游输入含糊，下游自动化越强，错误扩散越快。
代码可以被 review。
测试可以被 verify。
运行过程可以被 audit。
文档也需要同等级的质量门。
zeng-doc-quality-loop 解决的是这一层：让关键文档在进入执行链条之前，先经历一轮结构化收敛。
哪些问题被发现。
哪些问题被修复。
哪些修复被验证。
哪些分歧交给人类。
最终结论由哪些磁盘证据支撑。
这些都应该成为文档交付的一部分。
如果你需要我自用的这套文档审核 Skill，可以在后台留言。