Documenting Architecture Decisions — 导读 未开始

题记与说明

这篇讲什么

这是 ADR（Architecture Decision Record，架构决策记录）的开山之作。Michael Nygard 2011 年发表此文，回答一个具体问题：敏捷项目里，架构决策该记在哪、记成什么样。他的方案是把每个"影响结构、非功能特性、依赖、接口或构建技术"的重大决策，写成一篇编号的短 Markdown 文件，放在代码库 doc/arch/adr-NNN.md 下，用 Title / Context / Decision / Status / Consequences 五段式模板。有趣的是，这篇文章本身就按 ADR 格式写成——Context 部分陈述问题，Decision 部分给出方案，结尾还有一段真实的"使用体验报告"。

核心观点

1. 反对的不是文档，而是"没有价值的文档"：大文档永远没人更新、也没人读，小的模块化文档才有机会保持鲜活。
2. 不记录动机的代价是"盲接受或盲推翻"：新人面对历史决策，不理解来龙去脉，只能盲目接受（团队变得不敢改动，项目被自己压垮）或盲目修改（在不知情中破坏项目价值）。
3. ADR 要像"与未来开发者的对话"：写完整句子的段落，编号不复用，被推翻的决策标记 superseded 但保留——"它曾是决策"这件事本身仍是重要信息。

最值得记住的金句与数据

• "Agile methods are not opposed to documentation, only to valueless documentation."（敏捷不反对文档，只反对没有价值的文档。）
• "We will write each ADR as if it is a conversation with a future developer."（把每篇 ADR 写成与未来开发者的对话。）
• 数据：上线使用数月内，团队已有 6–10 名开发者轮换过项目，所有人都反馈从 ADR 中获得了充分的项目上下文——"no one is left scratching their heads, 'What were they thinking?'"

对我的启发

• Agent 系统 / AI 编程工具：ADR 天然是 Agent 的上下文文件——每篇几百字的"为什么这样设计"，正是 LLM 缺失的那种决策背景。让 Agent 读取 ADR 理解项目，甚至让 Agent 起草 ADR 初稿、人来定稿，就能把人机协作中的取舍沉淀成可检索的历史。
• 个人知识管理：ADR 是"决策日志"的极简模板——编号、小文件、放在决策发生的地方而不是远处的大文档里。这个原则可以直接迁移到个人的技术选型记录、笔记系统设计上。
• 写作：文中的警告值得贴在墙上——bullet 只是视觉手段，不是逃避写完整句子的借口；"Bullets kill people, even PowerPoint bullets."

适合谁读

所有写代码、做技术选型的人：想引入 ADR 的团队直接抄模板即可；个人开发者可用它记录自己项目的取舍；做 Agent 系统的人可以把它当作"项目长期记忆"的最小可行格式。全文两千余词，十五分钟读完，性价比极高。