上下文
对于敏捷项目的架构来说，它们必须有不一样的描述和定义。不是所有的决策都会立即做出，也不会在项目开始时做出全部决策。
敏捷方法不是反对文档，而是反对没有价值的文档。只要文档能保持到最新，则能帮助团队的文档都是有价值的。大型的文档永远不会保持最新，而小型的模块化文档至少有机会被更新。
也没有人喜欢阅读又长又大的文档。大多数开发人员至少在规范文档比源代码总大小（以字节为单位）至少有一个项目。这些文档太大，无法打开、阅读或者更新。一次能阅读完的文档，更容易让所有利益相关者去消费。
项目在其生命周期中，最难追踪的事情之一就是：某些决定背后的动机。一个参与项目的新人。可能会因过去的决定而困惑、迷惑、高兴或者激怒。如果不能了解其原因或者后果，此时这个人只有两个选择：
1. 一味地接受这个决策
如果决定仍然有效，这个响应可能是正确的。然而，如果情况发生了变化，这个决定应该真正重新审视，这可能并不好。如果项目积累了太多无法让人理解的决定，那么开发团队就会害怕改变任何事情，项目会在自己的体量下崩溃。
2. 盲目地改变它
同样，如果这个决策需要扭转的话，这也许是可以的。另一方面，不理解其动机或者后果而改变决策，可能意味着在：没有意识到的情况下，损害项目的总体价值。（例如，该决策支持尚未测试的非功能性需求。）
能避免盲目接受或盲目改变就更好。
决策
我们将保留一系列 “重大架构” 决策的记录：影响架构、非功能需求、依赖关系、接口或构造技术的记录。
架构决策记录，是一个类似于亚历山大模式（即：设计模式）的短文本文件。（虽然决策本身不一定是模式，但它们分享着力量的特征平衡。）每个记录都描述了一组力量和一个响应这些力量的决策。请注意，决策是这里的核心部分，所以特定的力量可能出现在多个 ADR（架构决策记录） 中。
我们将 ADR（架构决策记录） 保留在 doc/arch/adr-NNN.md 下的项目源码库中
我们应该使用像 Markdown 或 Textile 这样的轻量级文本格式化语言。
ADR（架构决策记录）将按顺序和数字编号。数字将不会被重复使用。
如果一个决策被逆转过去，我们会保留旧的决策，但将其标记为 “已取代”。（知道这是决策，但已经不再是决策。）
我们将使用只有几个部分的格式，因此每个文档都易于消化。格式只有几个部分:
标题，这些文件的名称是短名词短语。例如，“ADR 1: Deployment on Ruby on Rails 3.0.10” 或 “ADR 9: LDAP for Multitenant Integration
上下文，这一节描述了当前的技术、政治、社会和项目。这些力量可能处于紧张状态，应该这样说。本节中的语言是价值中立的，只用于描述事实。
决策，这一节描述我们对这些力量的回应。这是充分的句子，以及积极的声音。 “我们会…”
状态，如果项目利益相关方尚未同意，或者一旦达成一致，则 “决定” 可能被 “提议”。如果以后的 ADR （架构决策记录）更改或撤消决定，则可能会将其标记为 “已弃用” 或 “已取代”，并参考其替换。
后果，这部分描述了应用决策后产生的上下文。所有的后果应该列在这里，而不仅仅是 “积极的”。一个特定的决策可能会产生积极的、消极的和中性的后果，但是它们都会影响未来的团队和项目。
整个文件应该是一两页长。我们将把每个 ADR（架构决策记录）写成与未来开发者的对话。这需要良好的写作风格，以及完整的句子组织成段落。列表（原文：子弹）只能用于视觉风格，不能作为写作句子的借口。（列表杀人，甚至 PowerPoint 的列表。）
状态
Accepted
后果
一个 ADR（架构决策记录）描述了一个特定项目的重大决策。 这应该是对项目其他部分运行有影响的东西。
一个 ADR（架构决策记录） 的后果很可能成为后续 ADR（架构决策记录） 的背景。 这与亚历山大关于模式语言的想法也类似：大规模的反应为较小的规模创造空间。
即使团队组成随着时间的推移而变化，开发人员和项目干系人都可以看到 ADR（架构决策记录）。
以前的决策背后的动机是每个人，在现在和未来都是可见的。没有人搔着头理解，“他们在想什么？改变旧的决策的时间，将从项目背景的变化中清楚。
体验报告
您可能已经注意到，这篇文章被格式化为 ADR （架构决策记录）本身。自八月初（2011年）以来，我们已经在一些项目中使用这种格式。从全球来看，这不是一个很长的时间，但是来自客户和开发商的早期反馈是相当积极的。在那个时候，我们有六到十个开发人员轮流使用 ADR（架构决策记录）进行项目。他们都表示，他们欣赏能通过阅读来知道上下文。
ADR （架构决策记录）对于获取长期意图尤其有用。我们有几个客户正在稳定他们目前的系统，但是在不远的将来，他们正在寻求更大的架构。通过写下这些意图，我们不会不经意间使这些未来的变化更难。
一个潜在的反对意见是：使用代码控制版本控制，它会使得项目经理、客户利益相关者以及其他不像开发团队一样生活在版本控制中的人们，不能访问它们。在实践中，我们的项目几乎都在 GitHub 的私有存储库中，所以我们可以将链接交换到 master 中的最新版本。由于 GitHub 会自动处理 markdown ，因此它与任何维基页面一样友好。
到目前为止，ADR（架构决策记录）被证明是一个有用的工具，所以我们将继续使用它们。
扩展阅读
感谢 Philipe Kruchten 讨论架构决策的重要性。 我被告知，在我的阅读队列顶部附近的 Documenting Software Architectures 中有更多关于他们的信息。