别再忘记架构决策：让它们可执行

Source: Dev.to

问题：失踪的架构决策

大多数软件项目并不是因为开发者不会写代码而失败的。它们失败的原因是决策被遗忘了。

几个月或几年后，代码仍然可以运行，测试通过，系统看起来也很健康——但关键选择背后的理由已经消失。

• 为什么选择了这个库？
• 为什么这个服务会这样表现？
• 是性能优化、业务约束，还是一个临时变通方案却变成了永久的？

留下来的不是代码的清晰度，而是一套只有最初参与的人记得的未成文规则。这是组织记忆的问题。当意图消失时，每一次改动都变得更有风险、更慢、更昂贵。

团队并不是因为粗心而破坏架构；他们之所以破坏，是因为了解最初决策的人离职，截止日期带来持续压力，文档变得过时，关键决策埋在聊天记录和 Pull Request 中，而没有正式记录。

了解 为什么 建立某个东西和了解 它是如何 工作同样重要。没有这些知识，团队只能猜测——系统也会逐渐变得更难维护、更具风险。

如果让决策与代码分离，它们最终会被遗忘。架构决策记录（ADR）只有在成为开发者日常工作流的一部分、贴近代码、在评审时可见、并且在规则即将被破坏时能够被触发时才有效。否则，它们只会成为历史文档，而不是活的约束。

愿景：可执行的架构

想象一下，你可以问你的项目：

为什么这里禁止使用 ORM？

并得到一个清晰、一致的答案——不是来自可能正在度假的某个人，而是来自系统本身。这将意味着更少的重复解释、更顺畅的入职培训，以及更少的“架构传说”。

介绍 PHPDecide

PHPDecide 是一个 CLI 工具，它把架构决策视为：

• 版本化的制品，存放在你的代码库中
• 结构化、机器可读的知识
• 可解释的约束
• 可选的可强制执行规则

每条决策记录包括：

为什么要编写决策文件？

在一些团队中，领导或资深开发者会抵触，因为他们觉得这会失去控制。当知识只存在于他们脑中时，他们就会成为“守门人”。依赖会议和记忆会产生隐藏风险：

• 知识孤岛和单点故障
• 初级开发者不敢提问
• 决策被遗忘或被无意违规
• 评审变成关于意图的争论，而不是实现细节

决策文件把权威从个人转移到团队和代码库：透明、可解释、可共享。

入门指南

1. 使用 PHPDecide 在代码库中 记录 3–5 条高价值决策。
2. 在 CI 中 运行 lint 步骤，验证决策文件的正确性。
3. 在代码评审中 使用 explain，持续一个月以展示相关决策。
4. 衡量影响——观察重复提问是否减少、入职是否更快、评审是否更一致。

通过让架构决策可执行且易于发现，团队可以保留组织记忆、降低风险，并在长期内保持系统的健康。