ADR 链接到代码
决策记录与实现它的代码之间的双向链接。
为什么
docs/adr/ 里没人指向的 ADR 是孤儿；一个选择不明显却没有 ADR 链接的代码模块是谜题。双向链接——ADR 提及文件路径，代码注释回链 ADR 编号——意味着读者能从任一方向导航。当工程师打开配置文件看到 '// see ADR-0012 for why ClickHouse here'，一键就拿到理由，而非从代码反推。
何时使用
当 ADR 被 Accepted 且实现代码落地时。每条链接 2 分钟。仅当决策没有单一明确代码位置时可跳过。
如何做
1. 在 ADR 里加 "Implemented in" 字段，列出关键文件路径 2. 在每个关键文件加头注释："// ADR-NNNN: <一行决策摘要>" 3. 配置文件（yaml/toml）若支持注释字段则用它 4. 跑 CI 检查：每个有 "Implemented in" 的 ADR，回链是否存在 5. 代码重构/移动时，在同一个 PR 更新 ADR 的文件列表
示例
ADR-0012 "Implemented in"：
- src/events/writer.ts
- infra/clickhouse/schema.sql
src/events/writer.ts：
// ADR-0012: 事件写入走 ClickHouse（替代 Postgres ADR-0007）
export class EventWriter { ... }常见问题
- ⚠加了回链注释却忘了在 ADR 被替代时更新——过时链接比没链接更糟。
最佳实践
- ✓在 CI 里自动化双向检查，移动文件后构建失败直到 ADR 更新。
- ✓代码注释保持一行；完整理由在 ADR 里，注释只是路标。