返回资讯中心
外部精选
软件工程
#开发者实时流

开发者提出用决策记录取代传统文档

来源标题:Docs Are Dead, Long Live Decisions

有人主张停止手写记录系统现状的文档,改用受架构决策记录(ADR)启发的通用决策记录(General Decision Records)来记录每项重要决策。作者认为代码已能说明系统做什么,编码工具可按需解释实现方式,因此文档应聚焦于解释和论证决策,且必须由构建系统的工程师撰写以保证问责和共识。

Hacker News 最新lokilokus2026/11/18 · 今天21 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

TL;DR:代码展示系统做了什么,却不解释为什么。你的编码助手可以按需解释“怎么做”,所以别再手写文档来描述现状了。改为记录你的决策:用 General Decision Records(受 Architecture Decision Records 启发)来解释和论证每一个具有战略重要性的决策。这些记录必须由构建系统的工程师来写,以确保责任明确和共识一致。

现在代码很便宜,文档也一样。但许多项目里的文档要么过时,要么帮助不大。要么完全由 AI 生成,仅仅描述现状;要么是手写的,不管有没有 AI 辅助,都很快落后,而且仍然只是在描述现状。

再记录现状已经没什么意义了。要理解一个项目的架构或编码规范,能访问代码的编码助手给出的答案比任何文档都更精确。好的助手还会逐渐了解你的资历深浅、你如何看待软件,从而用适合你的层次来解释问题,这是静态页面做不到的。新人或许仍能从几个入门问题中受益,但一个 onboarding skill 就能轻松覆盖这一点。

当然,你仍然需要用户文档,因为用户(只要你不是在做开源项目)无法访问你的代码。所以给他们你惯常的 AI 生成 Docusaurus 页面,配上必不可少的“Getting started”,一个提供概览的 llms.txt,以及一个细节多到爆炸的 llms-full.txt,这样他们的助手就能回答任何可能的问题。

不行,因为有些沟通问题光靠代码解决不了。代码在解释程序流程方面非常精确,在展示东西实际怎么构建方面甚至更强。但它无法告诉你某样东西最初为什么被造出来。它也不适合战略思考:它是所有抽象层级中最低的一层。

这不是什么新见解。我们早就知道这一点,并尝试用不同方法解决,比如代码里的注释或某种“文档”。文档的整个理念就是让信息比通读并理解整个代码库更容易、更快速地获取,同时传达代码中未体现的东西,比如环境约束或历史遗留原因(例如历史依赖)。我们可以用 arc42 之类的文档框架覆盖大部分内容,但即便是它们通常也说不清事情为什么是现在这个样子。

项目要往哪里走也是同样的情况。假设我们正在从单体架构迁移到微服务,所以眼下架构有点乱。让一个全新的 agent 看这个仓库,它会提出一大堆改动,因为在它看来,这个架构就是坏的。有良好记忆系统的编码助手能跨会话捕捉到你的意图,但项目上其他团队成员(以及他们的 agent)收不到这个信息。

因此,我们需要一种清晰的方式,告诉我们的最佳编码伙伴我们打算做什么,尤其是为什么这么做。幸运的是,我们已经有了解决方案:它叫 Architecture Decision Records¹。我用的是一个略微扩展、不局限于架构的版本,我称之为 General Decision Records(GDR)。

基本思路类似于 RFC:在仓库里为每个重要的架构决策放一个 Markdown 文件,解释关于架构的某一个决策。通常一个 ADR 包含标题、状态(Draft、Proposed、Accepted、Rejected 或 Superseded)、决策、由此产生的后果以及一些上下文信息,这些在与 agent 协作时尤其方便。所以基本思路是掌握项目中每个重要决策的上下文知识。我要特别强调“重要”这个词:你用 React 还是 Svelte 很可能没那么重要(也许有一点),但你为什么用关系型数据库而不是 NoSQL 数据库,这很重要,因为它直接影响你的应用,进而影响你打算解决的业务问题(如果你生活在一个社会主义国家,那就把“业务”划掉,直接谈问题)。另外,在我看来,GDR 不应由 agent 自行撰写。应该允许它们提议 GDR,但 GDR 是一个非常非常慎重的决策,必须由人来做出。

这样我们就解决了多个问题:借助代码和进行中的 GDR,我们了解系统的当前状态;借助版本控制以及被拒绝或取代的 GDR,我们了解系统过去的样子;借助提议中的 GDR,我们了解未来会是什么样。如果你在做一个非常复杂的系统,你可能需要更精细的流程,比如 RFC,作为迭代某个想法的工作文档。这与 GDR 完全兼容。先写你的 RFC,一旦它达到稳定状态,就创建一个引用该 RFC 的 GDR,同时也在 GDR 中写明上下文和决策。是的,这有些冗余,但 RFC 会随时间变化,而 GDR 保持不变。

0001-ux-reduced-mobile-feature-set

Status: Accepted Context: The mobile app is used on small screens, where a full feature set hurts clarity. Decision: The mobile app only offers viewing data and approving requests. Everything else stays on desktop. Consequences: Clarity on mobile wins over feature parity. Requests like "add the settings page to mobile" should be rejected.

GDR 很合适,因为它们聚焦于“为什么”,并且带有状态。即便是一个被拒绝的决策也保留了其理由,这样 agent 就不会再提出团队已经考虑过并否决的改动。根据我的经验,把 GDR 加入助手的上下文就能解决这个问题。

(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →