夜雨聆风2026 年 7 月,Matt Pocock 发布了一条两分钟的视频,标题是《删掉你的大部分文档》。他提出了这么几个观点:
代码应当是唯一真相源。
为此代码本身要承担解释自身的责任——格式规范、目录结构合理、拆分成大小适当的模块,接口与实现分开放置,使 AI 在探索代码库时只读取它需要的部分。
在代码之外再搭一整套文档去解释代码,是一种反模式,应当删掉。
这些文档通常不可执行,也无法对照代码做测试,会随着时间与代码产生偏差。
当文档描述一种状态、而代码处于另一种状态时,就出现两个相互矛盾的真相源,AI 无法判断该依据哪一个。
有三类文档仍然值得保留:
架构决策记录(ADR) 术语表 一层薄的导航文档
它们承载的是代码表达不了的信息——决策时考虑过的备选方案、代码库中的领域语言、以及帮助定位代码主要部分的信息。
这些观点其实代表了敏捷软件开发的最佳实践。
目的是为了获得易读、易理解、易维护的代码和文档，而这些实践，恰恰也适用于AI时代。
被误读的敏捷宣言
敏捷宣言(Agile Manifesto,2001)其中一条是这样说的:
"Working software over comprehensive documentation." (工作的软件高于详尽的文档)
这一条常被误解为反对写文档。
其实还有宣言中还有一项被大多数人忽略了：
"That is, while there is value in the items on the right, we value the items on the left more." (虽然右项也有价值,我们更重视左项。)
意思是：承认文档有价值,只是把"工作的软件"排在了"详尽的文档"前面
"我们拥抱文档,但不是几百页没人维护、几乎没人用的厚卷宗"
"工作的软件是衡量进度的主要标准(primary measure)"
这也充分说明，代码是主要标准，而非唯一标准。
"代码即设计"，"代码即文档"
之所以把代码看得比文档重,源自Jack Reeves 1992 年的文章《What Is Software Design?》
Reeves 的观点分两层：
第一层:编程不是建造软件,而是设计软件。
"唯一似乎能满足工程设计标准的软件文档,就是源代码清单本身。"
如果源代码是设计,那么真正"建造"软件的是编译器和链接器,建造几乎是免费的。
第二层常被引用者省略:Reeves 明确保留了辅助文档。
他指出,辅助文档对软件项目和对硬件项目一样重要,只是不能把它和软件设计本身混淆——"永远不要忘记,真正决定设计的,是源代码,而不是辅助文档。"
代码是主设计文档,辅助文档服务于它,但不能取代它。
Martin Fowler 在2005年写过一篇题为《Code As Documentation》的文章中说， 把代码归为一个软件系统的主要文档。
但他也同时指出：并不是说代码是唯一文档，在软件开发中，通常都需要补充文档。
"代码是文档"不等于说"某个具体的代码库是好文档"。
代码可以写得清楚,也可以写得晦涩难懂,它并不天然清晰。
这恰恰是 Matt Pocock 在视频里强调的——代码要承担解释自身的责任,前提是它能够清晰的表达意图。
架构决策文档（ADR）
Martin Fowler 在 《Architecture Decision Record》 里专门推荐过 ADR 这种文档形态。
他对 ADR 的定义是:一份简短的文档,记录并解释一个与产品或生态系统相关的决策。
文档应当简短,只有几页,包含决策本身、做出决策的背景、以及重要的影响。
决策一旦做出,ADR 不再修改;如果决策被推翻,旧 ADR 链接到取代它的新 ADR。
他还对 ADR 的存放方式有明确建议:放进它所适用的代码仓库里(常见路径是 doc/adr),用 markdown 这样的轻量标记语言来写,这样它可以像代码一样被阅读和 diff。
ADR 之所以重要,在于它只记录代码本身记录不了的东西：为什么做了这个决定、当时考虑过什么、背景是什么。
它不记录代码怎么写,那部分由代码自己负责。
他还指出写 ADR 有两个作用:一是作为决策的记录,二是写的过程本身会帮助澄清思考。
这与Matt视频里"保留 ADR"的建议一致。
删掉无用的文档
kent beck写过一篇叫《The Documentation Tradeoff》的文章，他对文档为什么会失效的诊断,和 Matt Pocock 是一致的。
他的原话是:"等你读到文档时,它已经和代码脱节了,所以你最后还是去读代码。"
"文档越多,负担越重;负担越重,文档越没用。"
大模型（LLM）最擅长的事情就是“看懂代码并解释代码”，然而很多人却还在强制工程师花大量时间去写那些原本可以由 LLM 代劳的解释性文档，这极其讽刺。
现在 LLM 成了最顶级的“代码解释器”，就不必再把生命浪费在用文字去重述代码这种低效劳动上了。
真正的设计思想（Why）需要记录，而代码细节（What/How），直接交给 LLM 去读即可。
写在最后
Matt Pocock 的观点其实是把软件工程中的最佳实践,用 AI 时代的语境重新描述了一遍。
最佳实践并没有改变，改变的是受众，在 AI 之前，是为人和团队服务；在 AI 之后，是为了让 AI 也能读懂你的代码。
