用 AI 写代码注释与项目文档：把文档活交给 AI

文档是最容易被拖到最后、又最容易被骂的一件事。 AI 擅长读代码、补注释、从函数签名反推接口文档、把一次改动写成人话变更说明；但它也会把没发生的逻辑写得很笃定，写错比不写更糟。本文给出用 AI 写代码注释与项目文档的实战法：哪些该让 AI 写、怎么喂料、哪些必须人来审。

先分清：哪类文档 AI 写得动，哪类写不得

文档分两类。一类是「描述既有事实」的：函数做了什么、参数含义、返回值、异常分支——这类 AI 读源码就能写，准确率最高。另一类是「描述意图与约束」的：为什么这么设计、当时为什么放弃另一种方案、哪些坑不能踩——这类只有写代码的人知道，AI 编出来的「意图」多半是脑补。务实做法是把第一类交给 AI 批量生产，第二类只让 AI 列「需要补充的 TODO 清单」提醒人写。就像 AI 辅助做 JS 到 TypeScript 迁移 时，类型签名就是现成的文档来源，AI 顺着类型补说明最稳。

让 AI 基于真实代码补注释，而不是凭空编

最忌讳把函数名甩给模型让它「写注释」。正确姿势是把函数本体（连同它调用的两三个相关函数）一起贴进去，明确要求：只描述这段代码实际做了什么，不要补充代码里没有的行为。给一个反面约束比给十个正面要求更管用——直接写「如果看不出某段的目的，就标 // TODO: 需原作者确认，不要猜」。新人接手老仓库时，这种「基于真实代码」的注释比 AI 上手陌生代码库 时生成的概览更有用，因为它钉在具体函数上。

接口文档让 AI 从签名和类型反推

REST 接口、 SDK 方法、内部 RPC 的文档，最适合让 AI 从函数签名、类型定义、示例调用反推。给它路由、参数类型、一个成功响应样例，让它产出「参数表 + 正常/异常返回 + 最小可运行示例」。注意让它区分「代码里声明的」和「约定俗成的」：超时、鉴权方式、幂等性这些往往不在签名里，要单独追问，别让模型默认填。和 AI 生成 API 文档 的打法一致——喂得越具体，幻觉越少。

变更说明是 AI 的强项：PR 描述、 CHANGELOG 、发布注记

一次提交改了哪些文件、 diff 是什么，AI 读得比人快。把 git diff 喂给它，要求按「用户可见变化 / 内部变化 / 破坏性变更 / 迁移步骤」四段输出，就是一份合格的 PR 描述。 CHANGELOG 则让它汇总近 N 次提交、按语义化版本分组。这类文档描述的是「这次到底改了啥」，属于事实总结，AI 几乎不会跑偏。发布前把它和 AI 做代码重构 的改动清单对照一遍，能少漏很多「改了但没说」的破坏性变更。

审核三件事：事实、范围、时效

AI 产出的文档必须过三关。事实关：凡是它写了「这个函数会……」却没在代码里体现的行为，一律删或标 TODO 。范围关：接口文档别顺手写进「未来计划支持」的功能，那会误导调用方。时效关：代码一改，相关注释和文档就可能过期，建立「改函数顺手让 AI 重生成相邻文档」的习惯，而不是攒到季度大扫除。把审核交给 AI 代码审查工具 做第一道语法和一致性扫描，人只盯意图和事实，效率最高。

常见问题