Coding agents love decision records编程智能体青睐决策记录。

Architectural Decision Records (ADRs) help human teams establish rules and carry context forward in software projects. They capture significant design choices, the context behind them, and the reasons they were made. Like many tools built for human software teams, ADRs work remarkably well for coding agents too.架构决策记录（ADR）能够帮助人类团队在软件项目中建立规则并传承背景信息。它们记录了重大的设计选择、背后的背景以及做出这些选择的原因。正如许多为人类软件团队打造的工具一样，ADR 对编程智能体也非常有效。

Agents often arrive with little or no memory of yesterday and only a narrow view of a codebase. Even systems with persistent memory may preserve context without establishing whether it is accurate, current, or accepted by the human team. Decision records help them understand the intent behind the code rather than having to infer it. Keeping them in a project repository also spares agents from having to trawl through issues, search chats, and perform code archaeology. When intent is recorded explicitly, an agent is less likely to mistake an implementation detail for a foundational rule.智能体在开始任务时，往往对昨天发生的事情知之甚少甚至一无所知，对代码库的了解也十分有限。即使是拥有持久记忆的系统，也可能在无法确定信息是否准确、最新或已被人类团队采纳的情况下保存背景。决策记录能帮助它们理解代码背后的意图，而无需自行推断。将这些记录保存在项目仓库中，还可以让智能体免于翻阅问题单、搜索聊天记录和进行“代码考古”。当意图被明确记录下来时，智能体就不太可能将实现细节误认为是基础规则。

Once a decision enters an agent’s context window, the agent may adhere to it even more rigidly than a human would. In my own work, I’ve seen agents fight tooth and nail to apply an accepted decision even when it is obsolete. In one case, an agent preserved an outdated storage abstraction across a new feature because an ADR still described it as mandatory. Instead of flagging the mismatch, it added another layer to keep the new requirement technically compatible with the old ruling.一旦决策进入智能体的上下文窗口，它对决策的执行可能比人类还要刻板。在我的工作中，我见过智能体为了应用一项已采纳的决策而极力抗争，即便该决策已经过时。有一次，一个智能体在开发新功能时，因为 ADR 中仍将其描述为强制性要求，便强行保留了一个过时的存储抽象。它没有标记出这种不匹配，而是增加了一层封装，以使新需求在技术上兼容旧的规定。

The first remedy is to give agents explicit permission to question decisions that no longer fit — and to watch for signs that they are overfitting. But that solves only half the problem. When you invite an agent to update a decision, a second tendency appears: preserving the deliberation. Every clarification becomes an amendment explaining its own existence at the expense of clarity. Small implementation details become rules, and cross-references acquire their own restatements and justifications. The result is overlitigated prose that is hard for humans to read.第一个补救措施是明确授权智能体质疑那些不再适用的决策，并观察它们是否存在过度拟合的迹象。但这只解决了问题的一半。当你邀请智能体更新决策时，会出现第二种倾向：保留审议过程。每一处澄清都变成了为了解释自身存在而进行的修订，这反而牺牲了清晰度。微小的实现细节变成了规则，交叉引用也带上了各自的重述和论证。结果就是产生了一堆难以阅读、过度辩论的文字。

ADRs should absolutely be readable by humans, especially as we lean on agents to generate more and more code. To counter this, I’ve become explicit in my projects’ AGENTS.md files about how agents should apply and maintain ADRs. Here’s an excerpt from one:ADR 绝对应该保持人类可读，尤其是当我们越来越依赖智能体生成代码时。为了应对这一问题，我在项目的 AGENTS.md 文件中明确了智能体应如何应用和维护 ADR。以下是其中一段摘录：

Architectural Decision Records (ADRs) are stored as Markdown files in the docs/decisions directory. Treat accepted ADRs as binding. Proposed ADRs are non-binding context. Superseded ADRs are historical context and do not govern current work. If a given task conflicts with an accepted ADR, stop and discuss whether the task or ADR should change and propose the change that you think should be made. Propose new ADRs or updates to existing ones when a change introduces or revises a durable product or architectural decision.架构决策记录（ADR）以 Markdown 文件形式存储在 docs/decisions 目录中。已采纳的 ADR 应视为具有约束力。拟议中的 ADR 仅作为非约束性的背景参考。被取代的 ADR 属于历史背景，不用于指导当前工作。如果某项任务与已采纳的 ADR 冲突，请停止工作并讨论是应更改任务还是更改 ADR，并提出你认为应该做的修改。当变更引入或修订了持久的产品或架构决策时，请提议新的 ADR 或更新现有的 ADR。

Keep ADRs succinct. Each ADR carries only its current text; Git history is its changelog, so do not add or maintain amendment logs in ADR headers. When substantively changing an accepted ADR, add or update a single Updated: date line after Date: — its presence signals that history exists and Git has the details. A superseded ADR records a Superseded-On: date instead of Updated:, matching the Supersedes: line on the ADR that replaced it. State each rule once in the ADR that owns it and cross-reference it from other ADRs instead of restating it.保持 ADR 简洁。每个 ADR 只承载其当前文本；Git 历史记录即是其变更日志，因此不要在 ADR 标题中添加或维护修订日志。当对已采纳的 ADR 进行实质性更改时，在 Date: 行之后添加或更新一行 Updated: 日期——它的存在表明历史记录存在，且 Git 中有详细信息。被取代的 ADR 记录一个 Superseded-On: 日期来代替 Updated:，并与取代它的 ADR 中的 Supersedes: 行相匹配。每条规则应在其所属的 ADR 中陈述一次，并从其他 ADR 中进行交叉引用，而不是重复陈述。

These instructions are still evolving in my projects, and different projects will need different conventions. Some teams will prefer immutable ADRs that are superseded rather than revised; in my projects, I’m happy to have Git carry that history.这些说明在我的项目中仍在不断演进，不同的项目需要不同的规范。有些团队可能更喜欢使用被取代而非修订的不可变 ADR；而在我的项目中，我很乐意让 Git 来承载这些历史记录。

If you do something similar, adapt the guidance to your own needs. The essential principle is that each governing ADR should describe the decision currently in force, with enough rationale to apply it. An agent doesn’t need the transcript of every argument. It needs the ruling that governs today and clear permission to stop when the ruling no longer fits.如果你也做类似的事情，请根据自己的需求调整指导原则。核心原则是，每一项管辖性的 ADR 都应描述当前生效的决策，并提供足够的理由以供应用。智能体不需要每一次争论的笔录。它需要的是当下的准则，以及当准则不再适用时可以停止工作的明确许可。