程序员最讨厌写文档,直到我开始用AI来做这件事

我跟你说，写文档这件事，在程序员圈子里的地位，大概相当于公司聚餐要轮流敬酒。

你知道要做，知道跑不掉，但就是不想面对。

我之前有个老同事，技术能力挺强的，结果每次他负责的模块上线，后面接手的人都要花一倍时间去看代码才能搞清楚逻辑。不是代码写得差，是完全没有文档。问他，他说，「注释不是写着呢吗。」

注释和文档是两件事，这件事对很多程序员来说是个盲区。

我自己以前也差不多。能跑通的代码就是好代码，文档这个东西么，等有空了再说。然后就没有然后了。

后来有一段时间换团队，接手了一个老项目，密密麻麻全是代码，一行文档没有，接口注释也极其稀少。那两周我是真的心情很差，感觉在读一本没有目录的字典。

从那之后我开始认真对待文档这件事。但认真对待和真的愿意花时间去写，中间还有一段距离。

直到我开始用AI写文档，这个距离才真正消失了。

以前写文档是怎么个感觉

开一个markdown文件，对着代码，想着「这里要解释什么」，然后开始打字。写着写着开始走神，写着写着开始想「这段到底怎么描述」，写着写着觉得自己写的太啰嗦了，删掉重写，写出来又觉得太简单了，不够完整。

一个接口的文档，写一个小时很正常。

不是因为难，是因为那种「坐在空白页前面不知道从哪里开始」的感觉太消耗精力了。

我后来把这个问题丢给Claude Code，问它「你能帮我写文档吗」。

它说可以。

然后我把一段函数代码贴过去，加了一句「帮我写这个函数的文档注释」。大概十秒钟，文档出来了。格式规范，参数说明完整，返回值类型写清楚了，边界情况也提到了一句。

我看了看，改了两个地方，觉得不够准确的地方加了一句背景说明，然后粘回去。

整个过程，两分钟不到。

那一刻我有点愣住，因为感觉太不对称了。这个我拖了三天的工作，就这么解决了？

第一个发现：上下文比代码本身更重要

然后我开始系统地把这件事做起来。

AI写文档的质量比我预期高很多，但有一个前提，你得给它足够的上下文。

光把代码贴过去是不够的。或者说，只贴代码，它能写，但写出来的东西会停在「技术描述」这一层，缺乏背景。

我举个例子。有一次写一个权限校验模块的文档，把代码贴给AI，它写出来的注释是「校验用户是否具有对应资源的访问权限，返回布尔值」。技术上没错，但如果你是第一次接手这个项目，这句话其实没什么用，因为你还不知道这个「权限」是怎么分级的，跟哪个业务模块挂钩，出错了会怎样。

后来我换了一种方式。把代码贴过去之前，先加一段背景，「这是一个SaaS系统的权限校验函数，我们有三个角色，普通用户、管理员和超级管理员，不同角色对不同资源的读写权限是分开控制的，这个函数是做什么的，写文档时需要说明它在整个鉴权流程中处于什么位置」。

这次出来的文档质量明显不同，有了架构定位，有了使用场景说明，还给了一个简单的调用示例。

这个体验让我意识到，AI写文档本质上是一个协作关系，你提供背景，它提供表达。你知道这段代码在系统里是干什么的，它知道怎么把这件事说清楚。

两个人各有所长，合在一起才能出好文档。

第二个发现：API文档效果出奇地好

API文档以前是我最头疼的，因为写API文档有一套相对固定的格式，请求方式、路径、参数说明、返回结构、错误码，每个字段都要写到，格式稍微乱一点接手的人就看不下去。

我试了一下，把一个接口的代码贴给AI，加一句「帮我写OpenAPI格式的文档」，出来的结果让我有点惊讶，它直接给了一份符合OpenAPI 3.0规范的YAML，参数类型、必填项、描述、返回示例，基本都对。

当然也有需要修改的地方，主要是两类。一是业务逻辑类的描述，它不知道某个字段的业务含义，写的比较泛。二是一些特殊的返回情况，比如我们有一个「软删除」的设计，删除操作返回的状态码是特殊的，它不知道这个，要手动补上。

但框架给出来了，剩下的就是填细节，这跟从零开始写完全是两种工作量。

我大概估了一下，一个中等复杂度的接口，以前写完整文档要四五十分钟，现在大概十到十五分钟，而且最后的质量比我以前写的还稳定。

稳定这个词很重要。我以前写到第五个接口可能就在敷衍了，因为写文档是个体力活，中间会出现精力衰减。AI不会，第一个和第五十个接口出来的文档格式是一样整齐的。

第三个发现：意外发现了代码里的问题

这个让我觉得最有意思。

有一次写完一个功能模块，我让AI帮我写一份Readme，介绍这个模块是什么、怎么用、有什么注意事项。

它写完之后，我在看的过程中发现了一个之前没注意到的问题。

它在「注意事项」那里写道，「初始化这个模块时，需要确保XXX已经完成配置，否则会静默失败」。

静默失败这四个字让我停了一下。我回去翻代码，发现确实是，有一段逻辑如果配置缺失，只是return了一个默认值，没有任何报错或日志。这是个隐患，在测试环境不会发现，但某些生产场景下会出问题。

AI之所以写出这一句，是因为它在分析代码逻辑的时候发现了这个路径，然后在文档里如实描述了。

这件事之后我开始意识到，让AI写文档有一个意外的副产品，就是它的「如实描述」会帮你发现代码里的一些暗角。当你让它解释代码在做什么的时候，它的视角是中立的，它不会因为觉得「这里大概没问题」就跳过去，它会老老实实说「这里在某个条件下会走这条路」。

我后来养成了一个习惯，写完一个模块，让AI帮我生成文档，顺便多问一句「这里有没有什么边界情况或者潜在问题没有在文档里提到的」。

命中率大概三分之一，不是每次都有收获，但有的时候真的会挖出来一两个值得关注的点。

它搞不定的情况，也要说清楚

当然也有局限，说实话必须说。

最大的限制是长文档。如果你有一个很复杂的系统，需要写一份架构设计文档，涉及多个模块的协作关系、历史设计决策、某些反直觉的设计背后的原因，这种东西AI帮不了多少。

原因很简单，历史决策和反直觉设计背后的上下文，只存在于参与者的脑子里，没有办法从代码里读出来。你可以让AI帮你组织语言、整理格式，但那些「为什么这么设计」的回答，必须是你自己来写。

这块我后来的做法是，先把「为什么」的部分自己写成几个要点，然后把这几个要点和代码一起交给AI，让它来负责扩写和格式化。人负责思考，AI负责表达，分工清楚。

另一个限制是跨团队的文档。如果文档里需要描述跟外部系统的对接逻辑、某些外部依赖的行为特性，AI不知道那些外部系统是什么脾气，这类信息还是要人来补。

但这两个限制，跟整体带来的效率提升比起来，其实是少数情况。大多数日常的技术文档，它是能打的。

最后说一点比较底层的东西

程序员不爱写文档，其实有两个原因。

一个是「写文档本身很无聊」，这个AI能解决，它帮你把无聊的工作做掉。

另一个是「我写的文档别人也未必看」，这个AI解决不了，但它解决了第一个之后，第二个问题会自动变小一点。因为文档质量提升之后，文档被看的概率也会上升，正向循环就开始了。

我们团队现在有个不成文的规矩，新功能上线必须附文档，用AI生成也算，只要内容准确。

这个规矩推行以来，没有人抱怨过写文档麻烦，因为确实不麻烦了。

写代码的时间没变，后面接手的人顺畅了很多，这笔账是算得过来的。

以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～

谢谢你看我的文章，我们，下次再见。