跳到主要内容

文档 review 范式

1. 什么时候用​

任何文档 review / 跨文档审计 / PR review / 工程化前置准入评估时。

特别必须使用本 playbook 的场景：

  • 单文件 > 100K chars 或 > 2000 行（如核心架构主文件）
  • 跨多份文档的"事实源一致性"审计
  • 涉及战略不变量 / 产品立场 / 合规底线的决策 review
  • 上一轮 review 已发现 N 个问题但下一轮仍有新发现（提示根因没解决）

2. 前置条件​

  • 仓内 verify-kb 通过基线已建立
  • review 对象的事实源边界已识别（哪些文档是"权威定义"vs 哪些是"叙述引用"）
  • review 角色已分工（治理 reviewer / 主控 / 工程实施 主力 三视角至少有一个）

3. 复杂度阈值 → review 范式映射​

文档大小推荐 review 范式抽查可信度
< 30K chars / < 600 行单 agent 抽查或通读均可高
30K-100K chars / 600-2000 行优先通读；抽查需在 review 报告显式声明覆盖率 + 抽查章节列表中
> 100K chars / > 2000 行强制完整通读，抽查决议无效低 — 仅适合定位单点问题，不能作为整体评估依据

3.1 复杂度阈值的依据​

FinBayes 2026-05 第 10 步 review 的实测教训：

  • architecture.md 269K chars / 6057 行 抽查 review 发现 ~30 个问题
  • 同一文件完整通读 review 发现 ~60 个问题（问题数比 = 1:2.5）
  • 完整通读独有的发现集中在跨章节一致性类（编号错位、状态机数量错位、ADR namespace 漂移、并发语义冲突、字段动静态错位）— 这类问题根本不可能抽查发现，因为必须连续读 N 章节才能看出

3.2 大文件 review 实施技巧​

  • 单 agent 1M context（Claude Opus）：可一次性 Read 完整文件，无需拆段
  • 200-250K context agent（Codex CLI GPT 系列）：可一次 Read 完整文件但 budget 紧；建议不用 OMX $analyze skill（会触发多轮工具调用累积 context，触发远程 compact），改用直接 codex exec + 精简 prompt
  • 250K context 仍装不下（超 300K 文件）：分段并行（每段 ~80-100K），最后合并 — Step 10 实践证明可行

4. 三视角 review 协议​

每个核心文档 review 至少覆盖三视角中的两个（最佳是三个全覆盖）：

视角关心的事决策颗粒不变量校验
治理 reviewerADR audit trail / 文档一致性 / glossary 同步 / 形式层（frontmatter / namespace / promoted_to / 链接通）文字层 / 字段层 / 链接层形式层（frontmatter / namespace / promoted_to）
主控 / 项目负责人项目能否真启动 / 团队协同就绪度 / 战略-工程对齐 / 长期可持续 / 决策权启动决议 / 资源分配 / 跨工作流总指挥 / 风险接受语义层（战略不变量 / 用户主权 / 持续构建 / 合规底线）
工程实施主力真要写代码会撞到什么 / 文档能否直接转译 / fixture 可 validate / 测试跑起来会不会红 / context window 会不会爆文件级 / 字段级 / 测试断言级可执行性（import 路径单一 / fixture 完整 / 测试 DSL 兼容）

4.1 视角选择建议​

  • L1 战略文档 review：治理 + 主控（工程实施视角不适用）
  • L2 产品定义 review：主控 + 工程实施
  • L3 架构 review：三视角全覆盖
  • L4 工程包 review：工程实施 + 治理
  • 跨文档对齐 review：三视角全覆盖

5. AI 三方互审协议（P1 级决议）​

承接 ADR-003 fresh-eyes 二阶原则（参考 FinBayes 工程化首发应用）（FinBayes 工程化首发应用）。

5.1 流程​

[1] Claude 主控起草 spec / 决策方案
   ↓
[2] Codex 工程实施 review（fresh-eyes 一阶 — 实施可行性视角）
   ↓
[3] 第三方 AI (OOSO / Cursor / Hermes 选一) 独立 review（fresh-eyes 二阶 — 跳出 Claude/Codex 内部互审）
   ↓
[4] 三方一致 → 决议落盘 audit trail
   ↓
[5] 三方不一致 → Claude 主控汇总分歧 → 升级到人类用户审（可能转 P0）

5.2 关键约束​

  • 每方独立产 brief：不允许 sequential 顺序读上一方结论再写自己结论；每方必须基于事实源独立产出，最后比对
  • 第三方 AI 不可省略：仅 Claude + Codex 互审 = 一阶 fresh-eyes 不够，必须有外部视角
  • 不一致升级路径明确：三方分歧 > 30% → 人类用户审；分歧 ≤ 30% → 主控汇总后继续

5.3 不适用场景​

  • P0 决策（战略不变量 / 合规底线）：不走 AI 三方，必须人类签字
  • P2 决策（工程实施细节）：AI 双签即可，不强制 OOSO

6. 问题驱动 vs 根因驱动 review 切换​

6.1 默认问题驱动​

每次 review 找 N 个具体问题 + 修 N 个。这是 90% 场景的默认范式。

6.2 切到根因驱动的触发条件​

满足以下任一条件时强制切换到根因驱动 review：

  1. N+1 轮 review 仍发现新问题且数量未明显下降（问题—修复循环不收敛）
  2. 同一类问题在不同位置反复出现 ≥ 3 次（暗示结构性根因）
  3. 修复完一类问题后下一轮 review 发现"类似但稍微变形"的问题

6.3 根因驱动 review 流程​

[1] 汇总过去 N 轮 review 发现的所有问题
[2] 按问题"性质"而非"位置"重新分类（不按章节，按类型如"字段漂移"/"ADR stale"/"决策权空洞"等）
[3] 找类别共同根因（通常 5-10 个根因可解释 60+ 个具体问题）
[4] 每个根因设计一个"整改包"，关闭一片问题而非一个 patch
[5] 不再追求"修复每个具体问题"，追求"消除产生这类问题的结构性原因"

6.4 实例（FinBayes Step 5 + Step 11）​

  • Step 5 RCA：31 个问题 → 8 类 → 6 根因 → 6 整改方案
  • Step 11：60+ 问题 → 7 类 → 4 根因 → 4 整改包

切到根因驱动后，问题数下降斜率从「线性递减」变为「阶梯式断崖下降」，因为一个整改包能关闭十几个问题。

7. 核心契约文件清单（强制完整通读）​

任何项目的 review 都应当显式列出本项目的"核心契约文件"，对这些文件强制完整通读：

7.1 一般原则​

核心契约文件 = 满足以下任一条件的文档：

  • 字段 / 状态机 / 枚举 / 路径的权威定义源
  • 战略不变量 / 产品立场的声明源
  • 跨多个下位文档被引用为"事实源"的文档

  • 100K chars 的架构主文件

7.2 FinBayes 实例​

文档性质
projects/finbayes/strategic-whitepaper.mdL1 战略不变量源
projects/finbayes/engineering/product-definition.mdL2 产品立场源
projects/finbayes/engineering/architecture.mdL3 架构事实源（269K，必须完整通读）
engineering-packs/cognition-1.1-contract.mdStructuredCognitionResult 契约源
subsystems/{eval-harness,mca-classifier,consistency-middleware,knowledge-graph-service}.md4 子系统契约源
governance/workstreams/*/decisions/ADR-*.mdADR 状态源

8. 验证（review 范式做完后怎么知道做对了）​

  • review 报告明确声明使用的范式（抽查 / 完整通读）+ 覆盖率（章节列表 + 行段）
  • review 视角明确（治理 / 主控 / 工程实施 中至少 2 个）
  • 大文件（> 100K chars）的 review 明确显示完整通读 evidence（章节号 + 行号级）
  • 如启用 AI 三方互审，三方 brief 各自独立产出 + 一致 / 不一致结论明确
  • 如切到根因驱动，根因数 ≤ 10 + 整改包数 ≤ 6（避免根因层也膨胀）
  • review 报告 evidence/inference/unknown 显式标注

9. 回滚（出错怎么办）​

  • 完整通读发现问题数远超预期（> 200）→ 可能 review 标准太松，先按"工程实施可执行性"压一遍优先级
  • AI 三方互审分歧 > 50% → 升级到人类用户审 + 重新审视 P0/P1/P2 分级是否正确
  • 根因驱动后整改包数仍 > 6 → 根因没找到深层共性，重做根因分析

10. 关联资产​

  • FinBayes ADR-003 工程实施栈与协作（fresh-eyes 二阶原则首发声明）：governance/workstreams/finbayes-arch-rewrite/decisions/ADR-003-工程实施栈与协作.md
  • meta-playbook 文档工作流（上位决策矩阵）
  • FinBayes Step 11 整改包详细方案（本 playbook 来源）：governance/workstreams/finbayes-arch-rewrite/2026-05-28-step11-remediation-plan-detail.md
  • FinBayes Step 5 RCA 实例（问题→类别→根因模式首次应用）
  • FinBayes Step 10 完整通读 review 实例（抽查 vs 通读 1:2.5 教训来源）

11. 元 review​

本 playbook 来源于 FinBayes 项目 2026-05 长达 11 步 review 的痛切教训：

  • 前 9 步全是"问题驱动"，9 轮不收敛
  • Step 5 引入 RCA 一次（31→8→6），但没有把"RCA"作为可复用的范式，而是当作"本次专用工具"
  • Step 10 才暴露大文件抽查无效的根本问题（架构主文件 269K 抽查 vs 完整通读问题数 1:2.5）
  • Step 11 才正式把"根因驱动 review"和"复杂度阈值禁止抽查"沉淀为可复用范式

给后续工作流的核心建议：不要等 10 轮 review 才发现 review 范式本身错。在工作流启动时显式声明"用本 playbook"，按 §3 复杂度阈值 + §4 三视角 + §5 三方互审 + §6 切换协议执行。