夜雨聆风学习资料网

ARTICLE · 1373807

Claude Code 第23期|文档生成:README 与 API 文档自动化

Claude Code 第23期|文档生成:README 与 API 文档自动化

开篇:那个永远“明天再写”的 README

每个项目里都有一份永远“明天再写”的文档。

新同事小林入职第一天,主管把仓库地址发给他,说了一句“你先看 README”。他打开仓库,README 只有三行:项目名、一句含糊的介绍、一条已经跑不通的启动命令。他花了一上午翻代码、问同事、试命令,才勉强把项目跑起来。更糟的是,他后来发现,仓库里的接口文档和代码早就对不上了:文档说某个接口返回三个字段,实际返回了五个;文档里的鉴权方式,还是两年前废弃的那套。

这不是某个团队的个例,而是大多数项目的常态。代码每天都在变,文档却停在项目刚开始的那一天。不是没人知道文档重要,而是写文档这件事,永远排在“先把功能做完”后面。等到功能做完了,人也累了,文档就又拖到了下一个“明天”。

这一期要讲的,就是怎么把文档从“靠自觉”变成“靠流程”:用 Claude Code 从代码里把信息抽出来,自动生成 README 和 API 文档,再用一道人工校验和一道自动化检查,把文档的新鲜度钉住。文档不是写出来的,是长出来的——长在代码旁边,跟着代码一起变。


第一节:README 先写给“第一次来的人”——从代码里抽,而不是凭印象编

README 写不好,往往不是文笔问题,而是视角问题。写的人对项目太熟了,熟到忘了“第一次来的人”什么都不知道。于是 README 里写满了“众所周知”的假设,却唯独没有新人真正需要的东西:这项目是干什么的、怎么跑起来、出了问题找谁。

案例:小林的团队决定换个做法。他们不再让任何人“凭印象写 README”,而是给 Claude Code 下了一个任务:“读这个仓库,不要改任何代码。先告诉我四件事:第一,这个项目是干什么的,用一句话说清;第二,从零到跑起来,需要哪些前置条件和命令——命令必须来自真实的配置文件和启动脚本,不许编;第三,环境变量有哪些,哪些是必填的,对照示例配置文件逐条列出;第四,项目顶层目录结构,每一级是干什么的。”

Claude Code 交回来的初稿,让团队吃了一惊。启动命令里有一条早就失效了——因为启动脚本三个月前改过,README 没跟上;环境变量清单里多出了两个新变量,是上个月新功能加的,也没人写进文档。更重要的是,初稿里有一处是 AI 猜的:它把某个内部工具的用途说错了。团队没有直接采用初稿,而是对着初稿逐条核对:命令逐条跑一遍,变量逐条对照配置,猜错的地方改掉。核对完的 README,新人照着做,半小时就能跑起项目。

分析:用 AI 生成 README,关键在“信息来源”二字。好的指令不是“写一份 README”,而是“从这些文件里抽信息”。要指明它读什么:包管理配置文件、启动脚本、示例环境变量文件、入口文件、顶层目录。命令和变量必须来自这些文件,因为 AI 凭空编一条命令,编得再像样也是假的。同时要给它立一条规矩:不确定的地方标出来,不许用猜测填空。猜测是 AI 生成文档时最危险的毛病——它永远能给你一个看起来合理的答案,哪怕那个答案是错的。标出不确定的地方,人工核对时才有靶子。

结论:README 不是写给自己人看的,是写给第一次来的人看的。从代码里抽信息,再由人逐条验证,README 才能既快又真。


第二节:API 文档要跟着接口走——从路由和类型里生成,而不是手抄

如果说 README 过期是慢刀子,API 文档过期就是快刀子。接口一改,调用方立刻遭殃:前端按旧字段调接口,拿到新字段不知道怎么处理;联调时两边各执一词,一个说“我按文档调的”,一个说“代码早就改了”。手抄的 API 文档,注定跟不上接口变化的速度。

案例:小林团队的后端有二十多个接口,文档是半年前手写的,早就没人敢信了。他们换了打法:给 Claude Code 的任务是“读路由文件和类型定义,生成一份接口文档”。指令写得很具体:每个接口要包含路径和方法、请求参数和请求体、返回结构、错误码;参数和返回字段必须从校验代码和类型定义里推断,不许凭空编字段;还要给每个接口配一个能直接复制使用的请求示例——示例里的数据要是真实样子的数据,比如像真的邮箱、像真的日期,而不是“string”“0”这种占位符。

第一版文档出来后,团队发现了两个老问题:一个接口的错误码文档里漏了 401——因为鉴权中间件不在路由文件里,AI 没看到;另一个接口的返回字段多了一个,是类型定义里有、但文档里从来没写过的。团队补上了鉴权说明,并且立了一条新规矩:以后每个接口的文档,必须同时标注“成功”和“失败”两种情况——开发者花在排错上的时间,远比花在成功调用上的多。

分析:API 文档生成的核心,是“从代码里生成,而不是从记忆里抄”。路由文件告诉你有哪些接口,类型定义和校验代码告诉你参数长什么样,错误处理中间件告诉你会出哪些错。指令要写到这个粒度,否则 AI 就会给你一份看起来完整、实则缺胳膊少腿的文档。还有两点容易被忽略。第一,真实示例比字段表更重要。一个能直接复制粘贴跑通的请求示例,胜过十行干巴巴的字段说明。第二,错误响应要和成功响应一样详细。调用方最需要文档的时候,恰恰是接口报错的时候。

结论:接口文档的权威来源只能是代码本身。从路由、类型和校验代码里生成,文档才有可能跟上接口变化的速度。


第三节:文档不是一次性产品——让“过期”自己暴露出来

就算第一版文档写得再好,三个月后它还是会过期。代码在变,文档不动,差距只会越拉越大。真正的问题从来不是“第一版怎么写”,而是“以后谁来管”。

案例:小林的团队吃过这个亏。他们花了一周时间把文档补齐,半年后一看,又过期了一半。于是他们把文档写进了开发流程,而不是写进某个人的待办事项。做法有三条。第一,规则写进项目的 CLAUDE.md:“接口变了,接口文档必须一起改;新增环境变量,README 必须一起改;文档的更新和代码改动放在同一次提交里。”规则写给 AI,也写给人——每次改代码,Claude Code 都会被提醒顺手改文档。第二,提交前加一道检查:改动了路由文件却没动文档,就提醒一次。不是强制拦截,而是提醒——提醒多了,人自然会养成习惯。第三,每个月留半小时“文档体检”:让 Claude Code 对照代码和文档,列出一份“对不上清单”——哪些接口新增了没写进文档,哪些字段变了文档没跟上,哪些命令已经跑不通了。清单不长,但每次都有新发现。

有一次体检就抓住了真问题:某个接口的分页参数默认值改了,文档还写着旧值,前端按旧值调接口,每次都多翻一页数据。如果没有这道定期检查,这个问题要等到用户投诉才会被发现。

分析:文档保鲜靠的不是责任心,而是机制。三个机制各管一摊:CLAUDE.md 里的规则管“改的时候顺手改”,提交检查管“忘了的时候有人提醒”,定期体检管“长期漂移被发现”。缺了任何一个,文档都会慢慢滑向过期。还有一个原则:文档更新要和代码改动放在同一次提交里。分开提交,文档提交永远会被“下次再说”挤掉;放在一起,改代码的人顺手就把文档改了,成本最低。

结论:文档的新鲜度不是写出来的,是机制保出来的。规则、提醒、体检三道防线齐了,文档才不会在三个月后悄悄过期。


第四节:AI 生成的文档,人要审什么——三条红线不能越

文档交给 AI 生成之后,人的工作不是变少了,而是变精准了。审 AI 生成的文档,有三条红线,一条都不能越。

案例:小林在审第一版 API 文档时,差点放过三处问题。第一处,AI 把一个内部接口写进了公开文档——那个接口只供内部服务调用,暴露出去等于把后门写进了说明书。第二处,示例请求里出现了一个真实的测试密钥——AI 从某个示例配置文件里抄来的,看起来像占位符,其实是能用的凭证。第三处,文档里写了一句“本接口已废弃”,可实际上那个接口还在被三个老客户端调用,废弃的说法是 AI 从一段旧注释里推断错的。

这三处问题,每一处放出去都是事故。团队后来定了一条审稿清单,贴在文档流程里:第一,涉密检查——示例里的密钥、令牌、真实账号,一律换成占位符;第二,公开范围检查——内部接口不进公开文档,公开文档和内部文档分开维护;第三,事实复核——凡是涉及“已废弃”“即将下线”“仅供内部使用”这类判断,必须由人确认,AI 的推断不算数。

分析:为什么这三条是红线?因为 AI 生成文档的错误,和写代码的错误不一样。代码错了,测试会报警;文档错了,报警的是用户,而且往往是几个月之后。涉密信息一旦进了公开文档,撤回也来不及;内部接口一旦公开,等于主动扩大了攻击面;错误的废弃声明会让调用方提前下线还在用的功能。审稿清单的价值,在于把“凭感觉审”变成“按清单审”——清单上的每一项,都是出过事的地方。

结论:AI 负责把文档从无写到有,人负责把关三条红线。生成越快,审稿越不能省;审稿清单越具体,文档才越可信。


总结

文档过期,不是因为团队不重视,而是因为写文档这件事一直靠自觉、靠记忆、靠“下次再说”。Claude Code 改变的不是文档的重要性,而是文档的生产方式:从代码里抽信息生成 README,让新人半小时上手;从路由和类型里生成 API 文档,让接口变化有据可查;用规则、提醒和定期体检三道机制保住新鲜度;再用一条审稿清单守住涉密、公开范围和事实判断三条红线。

记住这个顺序:先抽后写,先生成后校验,生成归 AI,红线归人。顺序对了,文档就不再是项目里永远“明天再写”的那一份。

行动建议:今天就可以动手,不用等项目重构。打开你那个 README 最旧的仓库,给 Claude Code 下一个只读任务——不要改任何代码,只从配置文件和启动脚本里抽出真实的启动命令和环境变量,生成一份新的 README 初稿,再逐条核对一遍。做完这一份,你就知道文档自动化在你的项目里能走多远。


下一期预告:第 24 期《团队协作:共享配置与统一规范》——一个人用得顺手,不等于一个团队用得顺手。下一期讲怎么把 Claude Code 的配置、规则和工作流在团队里统一起来,让新人和老人用同一套标准干活。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料