架构决策记录 (ADR)
项目级架构决策记录。每条 ADR 描述一个有意识的取舍, 不是"做了什么", 而是"为什么这样做 + 当时考虑过的其他选项 + 接受的 tradeoff"。
ADR 一旦写入, 状态从 proposed → accepted → 可能后续 superseded by ADR-NNN。不删除历史 ADR, 即使被替代 — superseded 的 ADR 仍是项目记忆。
命名
ADR-NNN-<short-title>.md, NNN 自增, 不复用。
当前 ADR 清单
| # | 标题 | 状态 | 日期 |
|---|---|---|---|
| 001 | Multi-anchor 架构 | accepted (A + B 档已实施) | 2026-05-28 |
| 002 | B 档实施 · anchors/<slug>/ 子目录引入 | accepted | 2026-05-28 |
| 003 | Deployment as optional | accepted | 2026-05-28 |
| 004 | boss-skills as a product · HTTP API + cloud deploy | accepted | 2026-05-28 |
| 005 | Hybrid deployment · Cloudflare Pages + 腾讯云 | accepted | 2026-05-28 |
| 006 | 公开仓库脱敏 · 4 层防护 | accepted | 2026-05-28 |
| 007 | /boss 第 3 种模式 · REVIEW | accepted (实施完成) | 2026-05-28 |
| 008 | Handbook 站点框架 · VitePress on /handbook/ | accepted | 2026-06-01 |
| 009 | Internal-docs review workflow · 本地 diff + 飞书 + log.md 三件套 | superseded by ADR-014 (三件套 §2 仍作人写文档 review 沿用) | 2026-06-02 |
| 010 | Cloudflare 部署形态评估 · Pages 维持 / Containers 列 D4 提案 / Workers 不适配 | proposed (待双签) | 2026-06-11 |
| 011 | 独立私有 data repo · 访问控制粒度跟敏感分级走 | accepted (项目主理 06-11 通过) | 2026-06-11 |
| 012 | 多场景评委体系 · Scene 作为 Panel 的上层部署单元 | accepted (2026-06-25) | 2026-06-25 |
| 013 | 评审提交文档的受控 KB ingestion · 只进知识层, 不碰判断产出 | accepted (主理认可 + 零影响评审通过 · CTO 会签待补) | 2026-07-07 |
| 014 | 内部文档 review 分治 · bot 机械产出直推 / 人写文档保留三件套 | accepted (主理认可 · CTO 会签待补) | 2026-07-14 |
写新 ADR 的流程
- 复制
ADR-001作为模板 - 填以下段落:
- §1 Context (现状/问题)
- §2 Decision (做什么)
- §3 Consequences (取舍)
- §3.1 优势 · §3.2 接受的 tradeoff · §3.3 不变的承诺
- §3.4 Invariant impact ★ — 列举本变更让哪些既有 invariant 假设失效, 哪些需要新 invariant. 不写这一段是 ADR-005 实战暴露的盲点 (见下方"反例"段)
- §4 Alternatives Considered (考虑过的其他方案)
- §5 Migration Plan
- §6 关键反共识立场 (推荐, 见 ADR-005 §6 范例)
- 提 PR, 双人 review (CTO + 项目主理), merge 后状态置
accepted - 在本索引追加一行
反例 · ADR-005 漏写 §3.4 的代价
ADR-005 §3 列了 8 维 hybrid vs 全 VM 的优势, 但漏写了"本变更让 redact_check.py 的 docs/ allowlist 假设失效" (docs/ 历史定位是"内部方法论文档", ADR-005 把 docs/ 推公网 CF Pages, 此假设崩塌).
后果: 部署前夕才发现 128 个真名会随 CF Pages 上公网, 紧急 5 commit 拆 docs/internal/.
结论: 每个 ADR 必须问 "本变更让哪些既有 invariant 失效?" — 写下来才能在 PR review 阶段被同行抓到, 而不是部署前夕才被现实抓到.
与 CLAUDE.md / PRD 的关系
- CLAUDE.md — LLM 工作宪法, 描述"系统现在是什么样"
- PRD (internal) — 项目级需求, 描述"V0 期要做出什么"
- ADR — 架构决策, 描述"为什么这样设计、考虑过哪些其他选项"
冲突时优先级: ADR (设计原则) > CLAUDE.md (当前实现) > PRD (期望目标)。