ADR 工具链
生成、lint 和索引 ADR 的工具，让集合超过 20 条时仍保持一致。
为什么
5 条 ADR 可以手工管；50 条时编号漂移、状态过期、没人能找到关于队列的决策。工具自动化无聊的部分——编号、状态校验、交叉引用检查和索引页——让人力花在推理上。装了 adr-tools 的仓库能抓到一条实际已被替代却仍标 'Status: Accepted' 的 ADR，那是误导每个新人的谎言。
何时使用
一旦有 ≥10 条 ADR 或预期快速增长。搭建耗时 1-2 小时。仅当项目永远只有几条决策时可跳过。
如何做
1. 安装 adr-tools（npm i -g adr-tools）或用仓库内脚本 2. 加 CI 步骤，在每个触及 docs/adr/ 的 PR 上跑 'adr lint' - 检查：必填字段存在、状态是合法枚举、编号单调 3. 生成索引：'adr list' → docs/adr/README.md（CI 自动重生成） - 表格：编号 | 标题 | 状态 | 日期，按编号排序 4. 加 'adr graph' 命令（或小脚本），把替代链接渲染成 Mermaid 图 5. 把索引和图接入内部文档站，一键可达
示例
.github/workflows/adr.yml:
on: [pull_request]
jobs:
adr:
- run: npx adr-tools lint docs/adr/
- run: npx adr-tools list --format markdown > docs/adr/README.md
adr graph 输出（Mermaid）：
graph LR
ADR0007[PostgreSQL] -->|superseded by| ADR0012[ClickHouse 事件]
ADR0009[RabbitMQ] -->|superseded by| ADR0013[Kafka]常见问题
- ⚠自动生成的索引过期，因为 CI 只在触及 docs/adr/ 的 PR 上重生成——每次推 main 都跑，以抓手工编辑。
最佳实践
- ✓在 package.json 里锁定 adr-tools 版本，避免破坏性发布突然搞挂每个 PR。
- ✓让 'adr graph' 输出真正的 SVG 提交到仓库——非工程师读不了 Mermaid 源码但能读图。
- ✓给每条 ADR 加 'last reviewed' 日期，加季度 CI 任务标记 12 个月未评审的 ADR 做新鲜度检查。