漕运档案与代码注释——AI 时代的软件文档断舍离

楔子

清代漕运，是一桩极其讲究的差事。

从江南把粮食运到通州，沿途要过一千七百里运河、三十六道闸、十几个税卡。每一袋米、每一支船、每一处停泊、每一次损耗，都要造册登记。一艘漕船从苏州出发到通州交粮，路上要写的文书有多少？据《清史稿·食货志》记载，一艘船的报销册可以厚达三尺。

这三尺文书里写了些什么？大部分是套话——“风平浪静、舟楫安稳、漕丁勤勉、官吏廉明”。再就是各种过场账目，“某日某时过某闸、某地损耗几斗几升、某官查验签押”。乾隆年间已经有官员上书指出：这些册子根本没人看，写它的人不信、查它的人不看、收它的人只看封皮。但谁也不敢省。因为只要哪一艘船真出了事，没写册子的人就要负全责。

于是漕运档案越积越厚，每一艘船的文书越写越长，全国上下数以万计的胥吏一辈子做的事情就是抄这些没人读的话。乾隆五十年前后，仅漕运一项的文书工作，每年消耗的人力相当于一个中等省份的赋税。

这件事的可笑之处在于——它的存在不是为了被读，而是为了”万一被查”。它不创造价值，只规避责任。它消耗着整个系统最聪明的一批人，把他们困在重复劳动里，让他们一辈子无法做真正有价值的事。

我讲这个，是因为我最近一直在想软件行业的事。

我们今天的软件开发文档，已经走到了清代漕运档案的境地。只是我们这一行的”胥吏”，叫做程序员。

一、文档何以变成今日之累

要谈废除，先要谈来历。

软件文档这件事，最初不是用来折磨人的。它的起源，是一个非常质朴的需求——一群人要一起做一件事，得先把事情说清楚。

20 世纪 70 年代，软件项目第一次大到一个人脑子装不下的时候，工程师们模仿建筑业、机械业的做法，发明了一整套文档体系：需求规格书、概要设计、详细设计、接口文档、测试用例、部署手册、运维手册……每一份都有它的道理。

这套体系在当年是先进的。它解决了”几十上百人协作时如何对齐”的问题。微软 Windows 95 发布时，光是设计文档就有几万页——那个时代的程序员真的需要这些纸来确认自己写的东西和别人对得上。

但每一种制度，从产生那一刻起，就开始走向僵化。

软件文档体系的僵化路径是这样的：第一代人写文档，是因为真有用；第二代人写文档，是因为前辈这么做；第三代人写文档，是因为公司流程要求；第四代人写文档，是因为审计来查，不写要扣钱。

到了第四代——也就是我们现在——大量的软件文档已经退化成纯粹的合规品。它们不被读、不被信、不被引用。程序员痛苦地写着，项目经理虚伪地审着，审计敷衍地查着，最终归档进一个谁也不会再点开的文件夹。

这就是清代漕运的故事，原封不动地在 21 世纪的写字楼里重演。

二、AI 这一刀，斩在了什么地方

转折发生在最近这两年。

AI 编程工具的崛起，看起来是在替代程序员，其实它真正颠覆的是软件开发中”信息流转”的成本结构。

过去为什么要写详细的 API 文档？因为程序员 A 和程序员 B 之间需要传递信息，而口头传不准、邮件传不全，只能靠文档。文档是人和人之间昂贵的”翻译机”。

现在 AI 出现了。它能在毫秒级读完整个代码库，能从 schema 里推断出绝大部分接口含义，能根据上下文自动生成调用示例。人和人之间的翻译机，被一个不知疲倦的实时翻译员替代了。

这一刀斩下来，软件文档体系里一大半的内容，瞬间失去了存在的理由。

但要注意——只是一大半，不是全部。哪些被斩了，哪些还活着，这是接下来要谈的正题。

三、第一类文档：该斩的

我把这类东西叫做”漕运式文档”——它们的特征是只描述”做了什么”，不沉淀”为什么这么做”。它们是机械劳动的产物，是合规心理的产物，唯独不是判断的产物。

注释里那些复述代码的话

// 把 a 加 1，赋值给 b
b = a + 1;

这种东西如果还有人在写，应该被同事请去喝茶谈谈了。它不仅没用，还侮辱代码读者的智商。AI 读代码不需要它，人读代码也不需要它。唯一保留它的理由是”我们部门规范要求每行都要有注释”——而这种规范本身就是该被打破的。

手写的 API 接口文档

凡是能被代码自己说清楚的事，就不要让人再说一遍。OpenAPI、tRPC、GraphQL 的 schema 已经能完整描述接口的输入输出。一份代码生成的 API 文档，永远比一份手维护的 Word 文档更准确、更新鲜。

几十页的 UML 图

特别是那种连每个类的私有方法都画出来的详细类图。它们的命运通常是这样的：在架构评审会上被展示一次，被打印出来贴在墙上一周，然后永远地躺在 SharePoint 的某个角落。真正接手项目的人，宁可去看代码，也不会去看这种图。AI 能从代码反推出比这更准确的结构，速度还快一千倍。

详尽到每个按钮的功能规格说明书

那种”用户点击登录按钮后系统应当显示用户名输入框，输入框的最大长度为 20 个字符，超过时应当显示红色提示……”的文档。它的根本问题是——它的形式选错了。这种东西用一份可执行的 BDD 测试（Cucumber、Playwright）来表达，比 Word 文档准确十倍，且永不过时。

部署运维步骤手册

“第一步：在服务器上安装 Java 1.8，注意不要装 11；第二步：配置 Tomcat 的 server.xml……”——这种文档现在还在大量公司里流通。它们的存在本身就是一种技术债。正确的做法是把所有这些步骤写进 Dockerfile、docker-compose、Terraform、Ansible。代码即文档，且代码可执行。手写步骤永远会被人忘了更新某一步。

会议纪要、周报、月报

这是另一类漕运档案——它们的存在不是为了沟通，是为了证明开会的人确实在工作。一份洋洋洒洒的月报，往往是从 Jira、GitHub、Slack 里复制粘贴拼凑出来的。AI 现在能从这些原始数据自动汇总，比人写得更全面、更客观、更省时。让一个工程师每周花两小时写周报，是工程师的浪费，也是周报的浪费。

内部系统的几百页操作手册

LLM 接入产品后，用户直接问 AI 就行。“请问怎么修改我的报销分类？“——AI 当场答复，比翻手册快得多。面向 C 端产品的手册仍然有价值（涉及法律责任、用户教育），但内部工具的厚手册可以扔了。

这一类文档加起来，在大多数公司里占了文档总量的 70% 以上。斩掉它们，是 AI 时代软件管理者最容易拿到的”绩效”。它们不创造价值，只消耗人力，且让真正有价值的东西被淹没。

四、第二类文档：该瘦身的

这一类不能彻底扔，但传统的形式太重了，需要”瘦身”。

需求文档

过去的需求文档是几十页起步的”产品需求说明书”，里面塞满了背景、市场分析、竞品研究、用户画像、功能列表、优先级矩阵……现在的做法应该简单得多：一页纸的用户故事，加上一组验收标准，配几张关键交互的草图。

为什么能这么短？因为需求的核心永远是三件事——给谁用、解决什么问题、做完了怎么验收。其他那些”市场分析”、“竞品研究”——它们的真正归宿是商业计划书或战略报告，不是需求文档。把它们塞进需求文档，是过去几十年最大的形式主义之一。

架构文档

过去是几十页的”系统架构设计书”，里面把每个模块的内部细节都写一遍。现在该有的是一份 5-10 页的 ARCHITECTURE.md，只讲三件事：边界（系统包含什么、不包含什么）、依赖（依赖哪些外部服务、被哪些上游调用）、关键决策（为什么是这套架构而不是另一套）。

模块内部细节？看代码。AI 帮你看，比读文档快。

设计评审文档

把那种 60 页的精装 PPT 砍掉，换成 RFC 风格的 markdown。3-5 页就够。重点不是”我设计了什么”，而是”我考虑了哪些方案、为什么选这个、放弃了什么”。

工程界有一个常被忽视的事实——好的设计文档，价值不在描述方案本身，而在记录被否决的方案。被否决的那些方案，半年后会以各种形式卷土重来，到时你需要这份记录来回答”为什么我们当年没这么做”。

Bug 报告

过去要填二十个字段的繁琐表单。现在的做法：核心三项——现象、复现步骤、期望行为。其他字段让 AI 从用户描述里自动补全。

五、第三类文档：必须留下，且要加强的

讲到这里，可能有人以为我要全盘否定文档。恰恰相反。

AI 时代越是发达，有些文档反而越值钱。它们的特征是——它们沉淀的不是”代码做了什么”，而是”人做了什么判断”。

架构决策记录（ADR）

每个重要的技术选型，留一段简短的记录：“我选了什么、不选什么、为什么”。

## 2026-04-20  小暖记忆架构选型
- 决定：Mem0 做事实抽取，自建 MongoDB 存事件流
- 不选 Zep：时间图谱对当前场景过度设计
- 不选纯 Mem0 自托管：缺乏结构化事件 schema
- 复审条件：用户量过 1 万，或出现明显时间敏感漏召

就这么短。三五行字。但这三五行，是项目最值钱的东西。两年后接手的人（无论是人还是 AI），看到这段，立刻知道”原来当年是这么想的”，从而避免重蹈覆辙或盲目推翻。

ADR 是 AI 推不出来的。代码里没有”我考虑了 Zep 但放弃了”这种信息。这就是它必须由人写下来的原因。

业务领域词典

软件项目里最常被低估的文档。

什么叫”订单”？在你这个业务里它有几种状态？谁能创建？谁能修改？什么情况下会作废？退款和取消有什么区别？——这些业务语义没有任何代码能告诉你，没有任何 AI 能从代码里反推出来。

我做 HRIS 这么多年，最深的感受是——业务术语的歧义，是所有需求误解的根源。“假期”在不同公司的定义就有十几种。一个清晰的业务领域词典，能让所有的开发、所有的协作、所有的 AI 协助效率翻倍。

失败模式与应急预案

系统会怎么挂、挂了之后人和 AI 怎么协作处理。这种知识极其宝贵，因为它通常是用真实事故换来的。

我见过太多团队——一个核心工程师离职后，半年内系统就开始频繁出问题，因为他脑子里那些”这种情况要这么处理”的隐性知识全带走了。把这些写下来，不是给 AI 看，是给一年后凌晨三点被报警叫醒的同事看。

安全、合规、隐私的硬约束

“用户的身份证号必须加密存储”、“医疗数据不能离开境内”、“未成年人数据必须独立加密”——这些是 hard constraint，违反一条就是事故。它们必须显式写下来，且必须放在 AI 一定会读到的地方。

不要指望 AI 从代码里自己悟出来。也不要指望它从 GDPR 全文里推断你这个项目该怎么做。直接告诉它。

项目的”为什么”

每个项目应该有一份升级版的 README。它不讲怎么编译怎么运行，它讲——这个项目为什么存在、解决谁的什么问题、不解决什么问题、未来什么样。

这是新人（无论人还是 AI）最该读的第一份东西。读完它，AI 接手项目的速度能提升五倍。

六、AI 时代的新规矩

更有意思的是，AI 来了之后，多出来一批过去根本不存在的文档类型。它们是新规矩，是过去几十年没人写过的东西。

AI 协作上下文（AI_CONTEXT.md）

专门写给 AI 看的项目简报。每次开新对话粘给它，比让 AI 重新摸索快十倍。

# 小暖 — AI 协作上下文

## 当前阶段
MVP 验证期，重点是验证治未病闭环

## 硬约束
- 老人语音交互必须流式响应 < 800ms
- 隐私默认级别：自己 > 主照护者 > 家属
- 不存任何医疗结论，只做提醒和陪伴

## 最近的坑（避免重复）
- Sherpa-ONNX 的唤醒词模型对方言敏感度不够
- LiveKit 在 4G 网络下 jitter buffer 要单独调

## 当前禁区
- 不要建议接入云端 LLM（合规原因）
- 不要建议加视频功能（隐私原因）

这就是 AI 时代的”系统设计文档”。它不是给人读的几百页 word，是几页 markdown，专门为 AI 优化的高密度上下文。

Prompt 资产库

prompt 是新时代的代码。它应该被版本管理、被复用、被测试、被审查。一个公司里关键业务的 prompt，价值堪比核心算法——它们值得一份独立的资产库。

AI 输出验证规则

哪些任务 AI 可以全自动跑？哪些需要人审？人审什么？这些规则必须显式定义。否则要么 AI 闯祸（无人审），要么 AI 没用（什么都人审）。

七、一张速查表

让我把上面这些落成一张表，方便贴在墙上：

底下加一行口诀：机械描述代码或流程的，斩；沉淀人的判断和取舍的，留。

八、给开发管理者的几句逆耳之言

道理讲完了，给一线管理者几句实在话。

第一，斩文档比写文档难十倍。

写一份新文档，是加法，没人会反对。砍一份旧文档，是减法，每一次砍都会有人跳出来说”万一审计来查呢、万一甲方要呢、万一新人接手呢”。

清代漕运的文书没人能砍掉，就是因为每一份都有”万一”在背后撑着。但所有”万一”加起来，就成了让最聪明的人一辈子做无价值劳动的牢笼。

身为管理者，必须有勇气砍。砍不动的，先停止生产新的——让旧的自然消亡。

第二，砍完之后必须立新规矩。

不要只砍不立。如果你只砍掉旧文档而不引入新规范（ADR、AI_CONTEXT、领域词典），团队会陷入”无文档放养”，半年后你会怀念那些垃圾文档。

第三，文档质量胜于文档数量。

过去的考核是”项目结束时文档齐全度”。这个指标该改了。改成”关键决策的可追溯性”——一年后有人问”为什么这么做”，能在三分钟内找到答案吗？能，就是好文档；不能，就算写了三百页也是废纸。

第四，把人从漕运档案里解放出来。

软件行业最大的隐性浪费，是把高薪资、高潜力的工程师按在重复文书工作上。斩掉无用文档，不是为了省时间，是为了让团队最聪明的脑子去做最难的事——做判断、做权衡、做架构、做对客户最有价值的决策。

这才是 AI 时代管理者的真正使命：让人去做只有人能做的事，让 AI 去做 AI 能做的事。

结语

回到开头那个清代漕运的故事。

乾隆年间没人敢砍漕运档案。直到光绪年间，海运取代了河运，漕运体系整个崩溃，那些三尺厚的报销册子才一夜之间作废。结构不变时，没人能改；结构变了，谁都挡不住。

我们今天软件行业的处境，正是结构剧变的时刻。AI 编程工具的崛起，相当于当年海运取代河运——不是某一项技术的进步，而是整个生产关系的重组。在这种时刻，管理者最该做的事不是”等等看”，而是主动审视存量、果断斩掉冗余、建立适应新结构的新规矩。

那些不肯改的团队，会变成 21 世纪写字楼里的清代漕运衙门——文书堆积如山、效率每况愈下、最聪明的人一个个出走，直到某一天被一个用 AI 武装到牙齿的小团队彻底超越。

那些敢改的团队，会迎来软件工程史上最好的时代——少数最聪明的脑子，配合最强大的工具，做出过去十倍人力都做不出来的东西。

文档不会消失。它只会蜕变。从机械描述蜕变为判断沉淀，从人际翻译机蜕变为人与 AI 的契约，从合规摆设蜕变为真正的项目资产。

该斩的斩，该留的留，该立的立——这是 AI 时代软件管理的十二字真言。

至于那些舍不得砍的”万一”——把它们留给清代的漕运吏吧。我们这一代人，应该有更值得做的事情。

献给所有还在挣扎于”该不该砍这份文档”的开发管理者