Context  背景

Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.
敏捷项目的架构必须以不同的方式来描述和定义。并非所有决策都会一次性做出，也并非所有决策都会在项目开始时完成。

Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.
敏捷方法并不反对文档，只反对无价值的文档。能帮助团队自身的文档是有价值的，但前提是它们能保持更新。大型文档永远无法及时更新。小而模块化的文档至少还有更新的可能。

Nobody ever reads large documents, either. Most developers have been on at least one project where the specification document was larger (in bytes) than the total source code size. Those documents are too large to open, read, or update. Bite sized pieces are easier for for all stakeholders to consume.
没有人会去读大型文档。大多数开发者至少经历过一个项目，其中的规格文档（以字节计）比整个源代码还要大。这些文档太大，无法打开、阅读或更新。小而精的片段对所有利益相关者来说都更容易消化。

One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices:
在项目生命周期中，最难以追踪的事情之一就是某些决策背后的动机。新加入项目的人看到过去的某个决策，可能会感到困惑、费解、欣喜，甚至恼火。在不了解其理由或后果的情况下，这个人只有两种选择：

1. Blindly accept the decision.
   盲目接受决策。

   This response may be OK, if the decision is still valid. It may not be good, however, if the context has changed and the decision should really be revisited. If the project accumulates too many decisions accepted without understanding, then the development team becomes afraid to change anything and the project collapses under its own weight.
   如果该决策仍然有效，这种回应或许还能接受。但如果情境已经改变、决策确实需要重新审视，那就未必妥当了。一旦项目中积累了太多未经理解就被接受的决策，开发团队就会变得什么都不敢改，最终项目会在自身重压下崩溃。

2. Blindly change it.  盲目更改。

   Again, this may be OK if the decision needs to be reversed. On the other hand, changing the decision without understanding its motivation or consequences could mean damaging the project's overall value without realizing it. (E.g., the decision supported a non-functional requirement that hasn't been tested yet.)
   再说，如果决策确实需要被推翻，这么做也无可厚非。但话又说回来，如果对决策的动机或后果缺乏理解就贸然更改，可能会在不知不觉中损害项目的整体价值。（例如，该决策支撑了一项尚未经过测试的非功能需求。）

It's better to avoid either blind acceptance or blind reversal.
不论是盲目接受还是盲目推翻，都应尽量避免。

Decision  决策

We will keep a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
我们会为"架构级重要"的决策保留一套记录：即那些影响系统结构、非功能特性、依赖关系、接口或构建技术的决策。

An architecture decision record is a short text file in a format similar to an Alexandrian pattern. (Though the decisions themselves are not necessarily patterns, they share the characteristic balancing of forces.) Each record describes a set of forces and a single decision in response to those forces. Note that the decision is the central piece here, so specific forces may appear in multiple ADRs.
架构决策记录（ADR）是一种简短的文本文件，格式类似于亚历山大模式。（虽然决策本身不一定就是模式，但它们同样具有对多种力量进行权衡的特点。）每条记录描述一组力量，以及针对这些力量所做出的一项决策。请注意，决策是这里的核心所在，因此特定的力量可能出现在多个 ADR 中。

We will keep ADRs in the project repository under doc/arch/adr-NNN.md
我们将把 ADR 保存在项目仓库的 doc/arch/adr-NNN.md 中。

We should use a lightweight text formatting language like Markdown or Textile.
我们应该使用像 Markdown 或 Textile 这样的轻量级文本格式化语言。

ADRs will be numbered sequentially and monotonically. Numbers will not be reused.
ADR 将按顺序依次编号，且编号只会递增。编号不会被重复使用。

If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.)
如果某个决策被推翻，我们会保留旧决策，但将其标记为已被取代。（了解它曾是既定决策仍有意义，但它已不再是当前决策。）

We will use a format with just a few parts, so each document is easy to digest. The format has just a few parts.
我们将采用一种仅包含少数几个部分的格式，这样每份文档都易于理解。该格式只有寥寥几个部分。

Title These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration"
标题：这些文档的名称均为简短的名词短语。例如，“ADR 1: Deployment on Ruby on Rails 3.0.10”或“ADR 9: LDAP for Multitenant Integration”。

Context This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.

Decision This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …"

Status A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.

Consequences This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.

The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer. This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.)

Status

Accepted.

Consequences

One ADR describes one significant decision for a specific project. It should be something that has an effect on how the rest of the project will run.
一份 ADR 描述了某个具体项目的一项重大决策。它应当对项目其余部分的推进方式产生影响。

The consequences of one ADR are very likely to become the context for subsequent ADRs. This is also similar to Alexander's idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into.
一个 ADR 的后果极有可能成为后续 ADR 的背景上下文。这和亚历山大关于模式语言的想法类似：大规模的反应为小规模的适配腾出了空间。

Developers and project stakeholders can see the ADRs, even as the team composition changes over time.
即使团队组成随时间变化，开发人员和项目干系人也都能看到这些 ADR。

The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context.
先前决策背后的动机，对当前和未来的每个人都是可见的。没有人会摸不着头脑地琢磨“他们当时是怎么想的？”，而何时该改变旧决策，也会从项目背景的变化中变得清楚。

Experience Report  经验报告

You may have noticed that this post is formatted like an ADR itself. We've been using this format on a few of our projects since early August. That's not a very long time in the global sense, but early feedback from both clients and developers has been quite positive. In that time, we've had six to ten developers rotate through projects using ADRs. All of them have stated that they appreciate the degree of context they received by reading them.
你可能已经注意到，这篇文章本身就是按 ADR 的格式写的。我们自八月初起就在几个项目中采用了这种格式。从全球范围看，这并不算很长，但来自客户和开发人员的早期反馈都相当积极。在那段时间里，有六到十位开发人员轮流参与使用 ADR 的项目。所有人都表示，通过阅读这些记录，他们很欣赏所获得的背景信息量。

ADRs have been especially useful for capturing longer-term intentions. We have several clients who are stabilizing their current systems, but looking toward a larger rearchitecture in the not-too-distant future. By writing these intentions down, we don't inadvertently make those future changes harder.

One potential objection is that keeping these in version control with the code makes them less accessible for project managers, client stakeholders, and others who don't live in version control like the development team does. In practice, our projects almost all live in GitHub private repositories, so we can exchange links to the latest version in master. Since GitHub does markdown processing automatically, it looks just as friendly as any wiki page would.

So far, ADRs are proving to be a useful tool, so we'll keep using them.

More Reading

Thanks to Philipe Kruchten for discussing the importance of architecture decisions. I'm told there is more about them in Documenting Software Architectures which is near the top of my reading queue.