ADR-009 · Internal-docs review workflow · 本地 diff + 飞书异步 + log.md 三件套
| 字段 | 值 |
|---|---|
| 状态 | accepted · 2026-06-02 |
| 日期 | 2026-06-02 |
| 决策者 | CTO + 项目主理 |
| 承接 | ADR-006 (公开仓库脱敏 4 层) |
| 相关 | CLAUDE.md §10.2 · docs/internal/ (gitignored) · _wiki/log.md · scripts/redact_check.py |
⚠️ 本 ADR 已
superseded by [ADR-014](./ADR-014-internal-docs-review-split)(主理 2026-07-14 认可 · CTO 会签待补)本 ADR 的地基是「
docs/internal/gitignored、没法走 Git PR」(承接 ADR-006 P1.5)。但 v0.6.1 (2026-06-10 · 私有 repo 全审计) 已放开docs/internal/入 git tracked, 反转了 ADR-006 P1.5, 本 ADR 的 gitignored 前提随之消失。ADR-014 据主理 2026-07-14「bot 机械产出直推 / 人写文档 保留三件套」的决定重定位内部文档 review, 已 supersede 本 ADR。 三件套的具体 flow (§2) 作为人写内部文档的 review 流程仍被 ADR-014 §2.2 承接沿用 (故本 ADR 保留为项目记忆, 不删)。
1. Context
1.1 · 起源 · CLAUDE.md §10.2 与 ADR-006 的流程冲突
CLAUDE.md §10.2 规定:
改的规矩: 走 Git PR, 标题前缀
claude.md:· CTO + 项目主理 双人 review · merge 后在_wiki/log.md追加## [日期] claude.md 修订 | summary
§10.1 / §10.2 写于 vault v3.0 (2026-05-22), 当时 PRD 与 dev-plan 都在 Git tracked 的 docs/ 路径下, "PR + 双人 review" 是可行的.
ADR-006 (2026-05-28) 公开仓库脱敏 P1.5 把 docs/internal/ (含 PRD / dev-plan / audit / security 文档) 移出 git tracking. 自此:
- PRD 改动没法走 Git PR (文件不在 git 里)
- CTO 没法在 PR 上 review/留 sign-off 痕迹
- 但 §10.2 的"双人 review"承诺仍在
1.2 · 实战暴露 · 2026-06-02 PRD v3.2 sync
PRD v3.1-r2 → v3.2 同步 session (14 处 diff) 第一次完整撞上这个冲突. owner 在 session 内被迫选路径:
- 路径 A: 承认 docs/internal/ gitignored 现状, review 走本地 diff 文件 + 飞书截图 +
_wiki/log.md审计条目 - 路径 B: 改 CLAUDE.md §10.2 让内部文档走非 Git review (即本 ADR)
owner 当场选了 A 跑通, 显式留 ADR-009 候选. 本 ADR 把路径 A 工程化、把流程冲突正式合上.
1.3 · 适用范围限定
冲突仅适用于 docs/internal/* 这一 gitignored 子树. 公开层文档 (CLAUDE.md / www/ / handbook-src/ / www/adr/) 仍是 git tracked, PR + 双人 review 仍是这些文件的工作流, 不在本 ADR 修订范围内.
2. Decision
采用"本地 diff + 飞书异步签 + _wiki/log.md 审计"三件套作为 docs/internal/* 文档的 review 流程, 不走 Git PR.
2.1 · 三件套 flow
┌─ Step 1 · Diff plan (owner) ────────────────────────────────┐
│ owner 起 diff plan, 列每块 edit 的 §/行号/前后对比/理由 │
│ 必要时 sanity check 3-5 个高风险点 │
└─────────────────────────────────────────────────────────────┘
┌─ Step 2 · Apply + render diff ──────────────────────────────┐
│ apply 14+ 处 Edit, redact_check PASS │
│ 渲 `docs/internal/<topic>-review-diff.md` (unified diff 格式)│
└─────────────────────────────────────────────────────────────┘
┌─ Step 3 · 异步通知 CTO (飞书) ───────────────────────────────┐
│ 飞书卡片含: diff 文件本地 path + 1-2 张关键对比截图 │
│ + 文字 summary (≤ 200 字) + 期望 turnaround (默认 ≤ 72h) │
└─────────────────────────────────────────────────────────────┘
┌─ Step 4 · CTO 异步 review ──────────────────────────────────┐
│ approved / requested-changes / async-pending (默认起始) │
│ 反馈方式: 飞书文字 + 截图 (有异议时连具体 §/行号) │
└─────────────────────────────────────────────────────────────┘
┌─ Step 5 · 审计闭环 (owner) ─────────────────────────────────┐
│ `_wiki/log.md` 追加 `## [日期] docs-internal 修订 \| <文件>` │
│ 必须含: owner sign-off 日期 + CTO status 三态之一 │
│ CTO 异议 → owner 起 vR+1 修订, 重跑 Step 2-5 │
└─────────────────────────────────────────────────────────────┘2.2 · 审计源 (SoT) · 三件套之间的分工
| 件 | 位置 | git tracked? | 角色 |
|---|---|---|---|
| 本地 diff plan | (chat / scratch) | 否 | owner 主观推理痕迹, 不强求保留 |
<topic>-review-diff.md | docs/internal/ | 否 | CTO 可看的 diff 对照 (unified format) |
_wiki/log.md 审计条目 | _wiki/ | 是 | 唯一 git tracked 审计 SoT |
| 飞书截图 / 文字 | 飞书 (B 端备份) | 否 | CTO 异步 review 痕迹 |
git 上能看到的就 _wiki/log.md 一行. 这是分布式但闭合的审计链, 不是漏洞.
3. Consequences
3.1 · 优势
- 流程冲突合上: §10.2 + ADR-006 不再矛盾
- 不破 ADR-006 4 层防护: internal docs 不入 git, history 不暴露
- 异步 review 不阻塞 owner 推进 (vs Git PR 同步阻塞)
- 审计仍可追溯: log.md 一行 + 本地 diff + 飞书截图三件套
3.2 · 接受的 tradeoff
- 审计痕迹分散: 不在单一 git 里, 跨设备 / 跨 collaborator 需协调
- CTO 异议没 git 留底: 只能靠 owner 在 log.md 诚实记录 status (依赖人不耍赖)
- review-diff 文件本地化: 本机丢失 = 历史 diff 丢失 (V1 后建私仓 mirror 解决, ADR-006 §4 row E)
- CTO 异步可能拖: turnaround 没有强制 SLA, 仅默认 72h soft target
3.3 · 不变的承诺
- 公开层文档 (CLAUDE.md / www/* / handbook-src/* / www/adr/*) 仍走 Git PR + 双人 review, §10.2 在这些文件上不变
_wiki/log.md仍是 git tracked, 仍是唯一审计 SoT- redact_check 不松绑: docs/internal/* 仍要 PASS (虽然 gitignored 不会泄漏, 但跨设备同步时可能裸传, fail-close 习惯保留)
- ADR-006 4 层防护不变
3.4 · Invariant impact ★
本变更让以下 invariant 失效:
- 失效 inv: "CLAUDE.md §10.2 'Git PR + 双人 review' 适用所有 vault 文档" → 失效. 对
docs/internal/*例外 - 失效 inv: "CTO sign-off 必有 git commit 痕迹" → 失效. 内部文档 CTO sign-off 走飞书 + log.md, 无 git commit 留底
本变更引入以下新 invariant:
- inv-1:
docs/internal/*任何非 placeholder 修订必有对应<topic>-review-diff.md同期生成 (本地存在) - inv-2:
_wiki/log.md内部文档审计条目必含 owner sign-off 日期 + CTO status (三态:approved/requested-changes/async-pending), 不能空白或缺字段 - inv-3: CTO status 为
async-pending超过 14 天 → owner 必须主动催 (飞书 ping), 不允许"挂着不管"
4. Alternatives Considered
| 方案 | 为什么没选 |
|---|---|
| B · boss-vault-internal 私仓 submodule | ADR-006 §4 row E 已 defer 到 V1, V0 期人手少, 私仓 + submodule + secret 管理复杂度过高 |
| C · 撤 ADR-006 让 docs/internal/ 重新入仓 | 违反 ADR-006 4 层防护承诺, history 真名暴露 risk 回归 |
| D · CTO 在飞书签字直接当 PR review 等价 | 与本 ADR §2 step 4 等价, 但缺 §2 step 2 的 review-diff 文件 + step 5 的 log.md 审计闭环, 本 ADR 是 D 的完整工程化 |
| E · 公开仓内放 review-diff (脱敏后) | 脱敏后 diff 失真, 反而误导 review (e.g. 真名替换成 placeholder 后 CTO 无法核对一致性) |
5. Migration Plan
5.1 · 本 ADR 落地时 (P1, 2026-06-02)
| 步骤 | 文件 | 改动 |
|---|---|---|
| P1.1 | www/adr/ADR-009-...md | 本文件 source, 新建 |
| P1.2 | handbook-src/adr/ADR-009-...md | 公开手册站镜像 (本 file), 加 VitePress frontmatter |
| P1.3 | www/adr/README.md + handbook-src/adr/index.md | 表格加 ADR-009 行 |
| P1.4 | CLAUDE.md §10.2 | 加例外条款指向 ADR-009 |
| P1.5 | _wiki/log.md | 追加本 ADR 审计条目 |
5.2 · 回填昨日 session (P2, 已完成)
2026-06-02 PRD v3.2 sync 已实际跑了三件套 (review-diff 在 docs/internal/prd-v3.2-review-diff.md, log.md 条目 status: 项目主理 signed off · CTO async pending). 这次跑实际是本 ADR 的 retroactive 实施, 无需补救.
5.3 · 持续监控
- 每月人工: 扫
_wiki/log.md找docs-internal 修订条目, 检查是否所有条目 CTO status 已离开async-pending(inv-3) - CTO
async-pending≥ 14d 的条目: owner 飞书 ping (inv-3 强制)
6. 关键反共识立场
6.1 · "无 Git PR = 无审计" — 错
git PR 是审计实现方式之一, 不是审计本身. 审计的本质是:
- 有可追溯的修订记录 (本 ADR:
_wiki/log.md) - 有可对照的修订前后 (本 ADR:
<topic>-review-diff.md) - 有第二人独立看过 (本 ADR: CTO 飞书签)
三件套覆盖了这 3 点. git PR 只是把这 3 点压缩进单一 git 工件, 不压缩进 git 不代表审计不成立.
6.2 · "内部文档应该也入 git" — 错
ADR-006 已论证 (§6 第 2 段): git history 真名暴露 risk 是不可逆的. 即便 PRIVATE 仓, history travel risk 仍在. 单租户场景下, internal docs 不需要 git 介入即可闭合 review, "也入 git" 是误把 git 当审计标配, 没看到 git 在公开仓场景里是 risk 来源.
6.3 · "CTO 异步会拖到死" — 部分对, 但本 ADR 给了 inv-3 兜底
owner 不主动 ping 才会拖到死. inv-3 强制 owner 在 14d 边界主动催, 把 "CTO 拖" 转化为 owner 推进义务. 实战 cadence 取决于议题密度, 默认 72h soft target.
7. 何时回看本 ADR
- V1 私仓 mirror 重启: 本 ADR 可能
superseded by ADR-NNN. internal docs 进私仓后, PR + 双人 review 工作流可恢复, 本 ADR 退役 - CTO
async-pending≥ 14d 不催: 触发 inv-3 修订, 收紧 SLA (e.g. 加自动飞书 reminder cron) - review-diff 文件丢失事故: 触发 ADR-009 修订, 引入本地备份机制 (e.g. 加密 1Password / iCloud)
- 跨设备协作需求: 触发私仓 mirror 提案
ADR-009 · accepted · 2026-06-02 · ADR 体系第 9 个 · 合上 §10.2 ↔ ADR-006 流程冲突 · docs/internal/ gitignored 路径专用 review 工作流*