boss

Appearance

ADR-014 · 内部文档 review 分治 · bot 机械产出直推 / 人写文档保留三件套 ​

字段值
状态accepted (主理认可 2026-07-14 · CTO 会签待补)
日期2026-07-14
决策者CTO + 项目主理 (主理 2026-07-14 定方向)
承接 / supersedesADR-009 (三件套 · gitignored 前提已被 v0.6.1 反转)
相关ADR-006 · ADR-011 · CLAUDE.md §10.2 · _wiki/log.md

1. Context ​

1.1 · ADR-009 的地基被 v0.6.1 抽掉 ​

docs/internal/* 的 review 工作流经历了三次翻转:

时间事件状态
2026-05-28ADR-006 P1.5 把 docs/internal/ 移出 git tracking(公开仓脱敏,防真名进 history)gitignored
2026-06-02ADR-009 定「三件套(本地 diff + 飞书异步签 + _wiki/log.md 审计)、不走 Git PR」建立在「gitignored、没法走 Git PR」之上
2026-06-10v0.6.1(私有 repo 全审计)放开 docs/internal/ 入 git tracked(现 110+ 文件)tracked · ADR-006 P1.5 反转 · ADR-009 前提消失

ADR-009 §1.1/§1.3 白纸黑字把三件套的存在理由锁在「文件不在 git 里 → 没法走 Git PR」。v0.6.1 让文件重新入 git 后,这个理由不再成立,但 ADR-009 与 CLAUDE.md §10.2 都还停在旧描述。

1.2 · 出现了第三类:机械 bot 产出 ​

2026-07 起 boss-daily-report bot(scripts/gen_daily_report.py / ops/systemd/boss-daily-report.timer)每天把 docs/internal/daily-report/<日期>.md 直接 commit+push 进 main。它:

  • 零 LLM、纯 git log + 规则分类,机械可复现(同输入 → 同输出);
  • 内容是已 commit 进 main 的 commit subject 的聚合,不产生任何新内容 / 新暴露;
  • 既不是 gitignored(ADR-006 已反转),也没走三件套(bot 无法飞书异步签)。

旧的二分法(公开层 Git PR / 内部 gitignored 三件套)容不下这类产出。

2. Decision ​

docs/internal/* 的 review 按产出性质分治:

2.1 · 机械 bot 产出 → 直推 main,免 pre-commit review ​

满足全部下列条件的产出,由 bot 直接 commit+push 进 main,不需要 review:

  • 零 LLM / 确定性:纯规则 / 模板 / 机械聚合,无模型自由发挥;
  • 可复现:同输入必得同输出,错了删掉重生成即可;
  • 纯已入库数据的聚合:只重组 main 里已有的内容(如 commit subject / _wiki/log.md 条目),不引入新的一手内容;
  • 内部私有、无公网路径:留在 docs/internal/,不经 www/ / handbook-src/ 外发。

依据:审计留痕由 git commit 本身承担(比三件套的分散审计更强);内容可复现使"错了"零成本可逆;无新暴露使 pre-commit review 无标的。当前唯一实例:boss-daily-report。

2.2 · 人写内部文档 → 保留三件套异步 review ​

PRD / dev-plan / handover / audit 等人写内部文档(含 LLM 协作起草但由人定稿的),保留 ADR-009 的三件套(本地 diff + 飞书异步签 + _wiki/log.md 审计)。tracked 之后,三件套的焦点从「绕过 gitignored」转为「内容质量 + 第二人过目」——审计条目、飞书签、本地 diff 三件仍要求,只是不再因"文件不在 git 里"而被迫如此。

是否把人写内部文档进一步升级为 Git PR 双签(既然已 trackable),留待人手富余 / 私仓 mirror(ADR-011 / ADR-006 §4 row E)落地时再议,不在本 ADR 强推——避免给 V0 期少人手团队套同步阻塞的 PR 流程。

3. Consequences ​

3.1 · 优势 ​

  • 现状被如实编码:bot 直推 + 人写异步签的 de-facto 实践,终于有了对应的成文规则;
  • bot 产出零摩擦:机械日报不必每天开 PR / 飞书签,契合无人值守 cron;
  • 人写文档仍有第二人把关:PRD / audit 这类有取舍的文档不因 bot 便利而丢掉 review。

3.2 · 接受的 tradeoff ​

  • 两类边界需人判断:"算不算机械产出"由 §2.1 四条硬性条件裁定,新增自动写 docs/internal/ 的流程须逐一自检,不满足则回落 §2.2;
  • bot 产出无 pre-commit 人审:靠「§2.1 四条硬门槛 + git commit 审计 + 可复现兜底 + redact_check 公网出口闸」四重替代,而非人眼。

3.3 · 不变的承诺 ​

  • 公开层(CLAUDE.md / www/* / handbook-src/* / www/adr/*)仍走 Git PR + CTO/主理 双签,§10.2 常规流程不变;
  • _wiki/log.md 仍是唯一 git tracked 审计 SoT;
  • redact_check 仍是公网出口闸(§9.2/§9.3),内部私有存储存原文 + 敏感度分级不变;
  • ADR-006 对公开层的 4 层脱敏承诺不变(本 ADR 只处理内部私有层的 review 流程)。

3.4 · Invariant impact ★ ​

失效的 invariant:

  • 「docs/internal/* 是 gitignored」→ 失效(v0.6.1 起 tracked);
  • ADR-009 「docs/internal/ 没法走 Git PR,所以只能三件套」的前提→ 失效(现可 track 可 PR,三件套改为"选择"而非"被迫")。

引入的新 invariant:

  • inv-1:任何自动写 docs/internal/ 的 bot 产出,须满足 §2.1 全部四条(零 LLM / 可复现 / 纯已入库数据聚合 / 无公网路径)才准免 review 直推;缺任一条 → 回落 §2.2 人写文档流程;
  • inv-2:bot 直推产出的 commit 必须可识别(如 chore: 日报 …),便于审计追溯与被 gen_daily_report.py 之类工具过滤为"自动任务";
  • inv-3(承 ADR-009 inv-2)：人写内部文档的 _wiki/log.md 审计条目仍须含 owner sign-off 日期 + CTO status 三态。

4. Alternatives Considered ​

方案为什么没选
A · 全恢复 Git PR(含 bot)bot 每天为机械日报开 PR + 双签,纯仪式;机械聚合无取舍可审,PR 无 review 价值
B · 全保留三件套(含 bot)bot 无法飞书异步签,三件套不适配无人值守 cron
C · 全部直推、无 reviewPRD / audit 这类有取舍的人写文档失去第二人把关,丢掉 ADR-009 真正的价值
D · 立即迁私仓 mirror(ADR-011 / ADR-006 §4 row E)结构性方案,V0 期人手少仍 defer;与本 review 分治正交,不阻塞本决策

5. Migration Plan ​

步骤文件改动
P1www/adr/ADR-014-...md + handbook-src/adr/ADR-014-...md本 ADR 新建(proposed)
P2www/adr/ADR-009-...md + handbook-src/adr/ADR-009-...md顶部加 banner:前提被 v0.6.1 反转,拟由 ADR-014 supersede
P3CLAUDE.md §10.2 例外条款改分治终稿,指向 ADR-014
P4www/adr/README.md + handbook-src/adr/index.md加 ADR-014 行;ADR-009 状态标 superseded by ADR-014(双签 accept 后生效)
P5_wiki/log.mdmerge 后追加审计条目

本 ADR 与 P2–P4 同在一个 claude.md: PR 里提交,走 §10.2 公开层双签。双签 accept + merge 后:ADR-014 状态置 accepted,ADR-009 正式 superseded by ADR-014。

6. 关键反共识立场 ​

6.1 · "机械产出也应该 review" — 错 ​

review 的价值在于第二人对有争议的取舍做独立判断。机械聚合(零 LLM、纯已入库数据、可复现)没有取舍可判——它不做决定,只重排既有事实。对它硬套 review 是仪式主义:既拦不住不存在的"错误判断",又给无人值守流程塞进人肉瓶颈。真正的护栏是 §2.1 的四条硬门槛 + git commit 审计 + 可复现 + 公网出口闸,而非人眼扫一遍机械输出。

6.2 · "tracked 了就该一律回 Git PR" — 过激 ​

能 track ≠ 必须同步 PR。Git PR 的同步阻塞对 V0 期少人手团队是实打实的成本(ADR-009 §3.1 已论证异步不阻塞的价值)。tracked 打开了"未来可升级 PR"的门,但升不升级取决于人手与协作规模,是 §2.2 留的可选项,不是本 ADR 此刻的强制项。

7. 何时回看本 ADR ​

  • 私仓 mirror(ADR-011)落地:内部文档进独立私有 repo 后,人写文档的 Git PR 双签可恢复,§2.2 相应升级,本 ADR 局部修订;
  • 新增自动写 docs/internal/ 的 bot:须按 inv-1 逐条自检;若某类产出不满足四条(如引入 LLM 生成的新内容),触发本 ADR 修订以厘清边界;
  • bot 产出出过一次脏数据事故(如 redact 出口闸漏网):触发收紧 §2.1 或给 bot 加 pre-push 校验。

ADR-014 · accepted (主理认可 · CTO 会签待补) · 2026-07-14 · ADR 体系第 14 个 · 承 ADR-009(gitignored 前提被 v0.6.1 反转)· 内部文档 review 按「机械 bot 产出 / 人写文档」分治

判断力工程化 · Judgement, Engineered · 主站 · GitHub

© 2026 boss-vault contributors