让Claude Code写了一下午文档，说说真实体验

团队协作中，文档缺失和注释不规范是代码可维护性的头号杀手。但写文档这件事，开发者拖延率极高——代码都写完了，还要花大量时间补API文档、写函数注释、更新README。之前在leadhi.cn上对比各AI编程工具的能力时就注意到，文档生成这类执行型任务是AI工具最稳定的输出区间。上周五下午，我拿Claude Code把积压了三周的文档任务全清完了。今天把四个场景的实测体验写出来。

为什么文档生成是AI的甜区

写文档的核心流程：读懂代码→理解意图→组织语言→保持格式统一。除了"理解意图"需要业务判断，其他全是模式化执行。模式化执行恰好是Claude Code最擅长的。

而且1M token上下文让它写注释时能理解文件之间的关系。给Service函数写注释时，它知道函数被哪些Controller调用、返回的数据会被前端怎么用。这种跨文件理解能力，单文件工具做不到。

场景一：API文档生成

让Claude Code读取所有Controller和路由配置，按OpenAPI规范生成完整接口文档。

32个接口，8分钟完成。参数描述和返回值结构基本准确。只有两个接口的业务描述不够精确——技术行为能从代码推断，但业务用途代码里看不出来。

结论：技术信息一键可用，业务描述需人工补充。

场景二：函数注释批量生成

让Claude Code一次性处理40多个函数。参数说明、返回值、异常说明、功能描述全有。格式统一，跟项目已有注释风格一致。

意外收获：它从参数校验逻辑中推断出约束信息写进注释——"page从1开始，pageSize最大100"。有代码依据，不是编的。但偶尔会写一些无法完全确认的推断性描述，必须人工核对。

结论：格式准确，推断性内容要过一遍。

场景三：README从零生成

让Claude Code扫描项目结构、读取配置文件。生成的README包含项目简介、技术栈、目录结构、安装步骤、启动方式、API概览。

安装步骤和启动方式非常准确——直接从配置文件的scripts字段提取。项目简介写得比较泛，业务上下文需自己补充。

结论：技术信息准确，业务信息人来定。

场景四：变更日志自动生成

让Claude Code读取最近10次Git commit，按"新增/修复/优化"分类整理。两分钟搞定，描述比原始commit message更清晰完整。

结论：效率最高的场景——人写半小时，它两分钟。

四个场景总结

规律：Claude Code提取的技术信息准确率高，业务信息需人补充。AI覆盖约70%的工作量。

必须警惕的一个问题

Claude Code会推断代码意图，但推断不总是对的。更隐蔽的是——推断性描述太"自信"，看起来跟真实描述一样流畅。不仔细核对很容易把错误文档当成正确的。

文档是给其他人看的。错误的文档比没有文档更危险。 没有文档别人会自己看代码，错误的文档会直接误导团队。

提升输出质量的工程化建议

CLAUDE.md里写清文档规范。 注释格式（JSDoc/JavaDoc）、API规范（OpenAPI/Swagger）、README模板——提前定义好。不定义的话它会按默认风格来，跟项目可能对不上。这是影响质量最大的因素。

告诉它模块的业务用途。 "这个模块是用户积分系统，面向C端用户"——一句话就够。有了上下文，业务描述准确度明显提升。

精确引用目标文件。 用路径指定要处理的文件。不遗漏不误触。

按模块分批处理。 一次处理太多质量会下降。每批确认质量再继续。

跟同类工具的能力差距

Copilot只能补全当前函数的注释片段，单文件级别。Cursor能辅助重写注释，同样是单文件操作。

Claude Code能一次性扫描整个项目，批量生成所有注释和完整文档。1M上下文让它理解文件间的关系。项目越大，差距越明显。

趋势：文档从"以后再说"走向"自动进化"

当生成一份API文档从花半天变成花十分钟，文档缺失的成本就变得不可接受了。MCP协议让Claude Code能对接代码仓库和CI/CD流水线，代码变更后自动更新文档正在成为可能。

与其纠结文档格式怎么写，不如把时间花在审查AI生成的内容是否准确上。 审查永远比从零写更高效。Claude Code已经能帮你做到80分了，剩下20分的业务判断才是你该花时间的地方。