1. 从写文档半小时到生成文档三秒钟这个技能到底解决了什么接手别人留下的老项目时最让人头疼的往往不是改代码而是搞不清接口到底有哪些、参数是什么、返回什么结构。很多团队都有这样的场景代码写了一堆接口文档却散落在各处有的在旧Wiki里有的在聊天记录的某个文件里还有的干脆只有代码注释里零星几句。我前阵子参与的一个模拟项目X后端代码有几十个接口但文档停留在半年前新增的接口一个都没补。每次前后端联调都是靠你翻翻代码看看返回啥这种方式。这效率低得让人抓狂。于是我专门弄了一个基于大模型的项目——本质是一个可复用的技能skills输入是项目代码仓库输出是一份结构完整的接口文档。花了几小时配置好之后几十个接口的文档基本能在一分钟内生成初稿而且是按统一模板输出前后端都能直接看。这篇文章就把这个技能从原理、配置到实操完整聊一遍。如果你是后端开发、技术负责人或者经常需要维护项目文档的人这套思路能帮你省下大量重复劳动。它不是什么黑科技核心就是读代码 → 提炼接口信息 → 按模板生成结构化文档但要做好细节还挺多。2. 这个技能的工作原理大模型怎么读懂你的项目代码很多人的第一反应是这不就是把代码喂给大模型让它总结吗其实没那么简单。直接扔一大堆代码进去模型容易抓不住重点输出往往也是泛泛而谈。真正好用的技能需要有一套清晰的处理流程。2.1 不是读全部代码而是精准挑出接口相关代码道理很简单一个项目里真正需要接口文档的是暴露给外部调用的那部分——Controller层、路由定义、请求和响应模型。核心逻辑、工具类、数据库操作这些和接口文档没关系硬塞进去只会浪费上下文窗口、干扰模型判断。所以这个技能的第一步是让大模型先扫描项目结构识别出哪些是接口入口。以Java后端为例最常见的就是Spring框架的Controller类特征非常明显类上有RestController或Controller注解方法上有RequestMapping、GetMapping、PostMapping这些路由注解。Python后端则是Flask的app.route、FastAPI的app.get等装饰器。我配置的技能里第一步就是让模型执行一次目录树扫描按文件名和路径特征筛选候选文件。这一步看着简单但实际上决定了后面所有环节的效率。2.2 关键设计逐文件分析而不是一股脑全塞把几十个Controller一次性塞给模型让它生成一份大而全的文档效果通常不会太好。原因有二一是上下文有限文件太多必然截断或压缩细节就丢了二是模型容易看花眼搞混不同模块的接口。我采用的策略是逐文件分析、分块生成。先让模型读取第一个Controller文件提取其中的接口信息请求路径、HTTP方法、参数列表名称、类型、是否必填、注释说明、请求体结构、响应结构。然后生成这个文件对应的接口文档片段。再处理下一个文件最后把所有片段按模块合并。这样做还有个额外好处如果某个文件的解析结果有问题定位起来非常容易直接重看那个文件就行不用让模型从头再来。2.3 上下文管理的实操技巧用好目标文件而非整个仓库动手配置这个技能时最需要注意的就是怎么把目标文件内容喂给大模型。我试过两种方案。第一种是让模型自己去打开文件读内容这需要技能具备文件读取能力类似给代码库装了个只读访问接口。优点是灵活模型可以根据需要多次读取缺点是多轮交互会消耗较多token速度稍慢。第二种是在调用时直接把目标文件内容作为上下文传入。这种执行效率更高但要求调用方先知道哪些文件是接口相关——绕了一圈又回到了谁来挑文件的问题。我的最终做法是两者结合调用方先传入一个项目文件清单和目录结构技能按规则筛选出候选接口文件然后逐个读取内容分析并生成文档片段最后汇总输出。整个过程对使用者来说是黑盒但其实内部做了好几轮文件读取和分析。2.4 参数补全与推测文档里写可能但代码里要有依据实际写文档的时候最烦的就是接口参数含义不清晰。很多代码注释写得极其潦草甚至完全没有注释。这种情况下技能需要做的是合理推测并标注不确定性。举个例子一个创建用户的接口参数列表里有userName、password、mobile注释全空。模型可以根据参数名和常见接口规范推测userName是用户名、password是登录密码、mobile是手机号并在文档中标注含义依据参数名推测请确认。这个设计很关键。它既保证文档能快速产出初稿又不会给人这文档是瞎编的的印象。所有推测内容都有明确标注人工复核时可以快速定位需要确认的地方。3. 配置一个读代码生成接口文档技能环境准备与核心配置说完了原理来点实际的。这里我用的是一个通用的大模型技能配置框架类似Claude Skills的格式核心是三个文件SKILL.md描述技能逻辑、参考代码、以及可选的脚本文件。这套结构其实不复杂花半小时看一遍官方示例就能明白。3.1 确认你的执行环境具备哪些能力在动手配置前先确认三件事你的大模型工具支持自定义技能加载它具备文件读取能力或者你集成的代码库工具能提供文件内容给模型后端项目能被目录扫描工具识别框架类型。我用的这套环境是同时满足这三点的如果你的工具链缺某一块需要先补上对应的能力。这里有个容易踩的坑很多人以为技能可以自动看到整个项目其实不然。技能本质上是一套指令模板加执行逻辑具体能看到什么取决于调用时传入的信息范围。所以我在技能描述里专门写了基于提供的项目路径执行分析避免误以为它具备全局视野。3.2 SKILL.md的核心写法指令越具体输出越可靠技能的核心文件是一份Markdown格式的指令说明。它告诉模型你的角色是什么、执行步骤是什么、输出格式是什么。我把自己调试了几轮后觉得最稳定的版本结构列一下你可以直接参考。首先声明技能的目标从项目代码中提取接口定义生成结构化接口文档。然后明确执行步骤扫描项目结构识别框架类型和接口入口文件逐个读取文件内容找出所有接口定义提取接口的完整信息生成统一格式的文档片段汇总输出完整文档。接下来要定义接口需要提取哪些字段这是决定文档质量的关键接口名称从方法名推断如createUser请求路径如 /api/users请求方法GET/POST/PUT/DELETE功能描述结合方法名、注释、业务逻辑推断请求参数参数名、类型、是否必填、位置query/path/body、说明请求体示例如果是POST/PUT请求响应结构示例主要返回字段及类型错误码说明如果代码中有显式错误码定义最后是输出格式约定每个接口以固定模板输出包含上述字段。多个接口按模块分组模块名可以从Controller类的注释或名称推断。3.3 写一段逻辑判断代码帮助模型定位入口文件这些文件都标记为“辅助逻辑”。通过增强某些后端的解析能力我让技能变得更敏捷。比如处理Java Spring项目时我会在技能目录中加入一个解析文件专门识别哪些类标注了请求注解并扫描方法上的路由注解以及参数注解。具体的脚本可以按实际需求换成其他工具链。这样做的好处是模型不需要每次都在海量文件中“猜”哪个是接口文件。逻辑直接告诉它候选列表分析时直接从这些文件开始。3.4 让技能看懂多语言项目框架识别的重要性实际项目中使用多种语言时技能也需要能适应这种环境。比如Java项目用Spring、Python项目用Flask或FastAPI、Node.js项目用Express。我这里在技能里加了一个框架识别步骤先看项目配置文件比如Java的pom.xml或build.gradle、Python的requirements.txt、Node.js的package.json再结合代码注解风格判断框架类型。这个步骤非常重要。因为不同框架的接口定义写法差异很大统一用Spring的注解规则去套FastAPI的代码完全是鸡同鸭讲。框架识别准确后面的提取才能准确。4. 实战测试用一个模拟Spring项目跑通全流程配置完成后我拿一个模拟的Spring Boot项目做了全流程测试。项目不大不小正好10个Controller类约60个接口定义代码量大概一万行。这个规模挺有代表性既不会小到没有挑战性也不会大到一次性塞满上下文。4.1 第一步目录扫描与框架识别测试时我先把项目的目录树结构传给了技能。它识别出这是标准的Maven结构pom.xml中存在spring-boot-starter-web依赖于是判断为Spring Boot项目。随后目录扫描定位到所有带Controller命名的类文件一共10个全部进入候选列表。这里顺带说一句文件命名规则很重要。如果你们的项目里Controller不叫Controller比如叫XxxResource那技能就识别不出来。比较好的做法是在技能描述里加上同时匹配RestController注解和文件名中含Controller/Resource/Endpoint等关键词扩大识别范围。4.2 逐文件分析的实际输出拿一个用户模块接口举例我挑一个典型的用户管理Controller看它提取出来的效果。这个Controller里有3个接口创建用户、查询用户列表、删除用户。技能的提取结果如下。创建用户接口识别到POST方法、路径/api/users请求体结构是UserCreateRequest对象里面包含userNameString必填、passwordString必填且代码中有Size(min6)注解可推断长度限制、emailString选填。响应结构是UserVO包含userId、userName、email、createdAt等字段。功能描述则结合方法名createUser和注释新增用户推断为创建新用户。值得说明的是技能不仅提取了字段名和类型还把校验注解转换成了文档里的参数约束。这一层转换很有用因为前端联调的时候最关心的就是这个参数到底能不能为空、有没有长度限制。以前这些信息都要人工翻代码去找现在直接生成在文档里了。三级标题下生成的内容如下查询用户列表接口识别了GET方法、路径/api/users查询参数包含pageNum、pageSize和keyword其中pageNum和pageSize有默认值keyword是选填的模糊搜索条件。响应是分页结构PageResult 包含records、total、pageNum、pageSize这几个字段。删除用户接口识别了DELETE方法、路径/api/users/{id}路径参数是idLong类型必填响应为Boolean表示是否删除成功。4.3 合并成完整文档模块分类与目录生成的合理细节所有Controller分析完之后技能会按模块合并生成一份完整文档。由于项目里Controller的命名比较规整——UserController、OrderController、ProductController这种——所以合并时按名字前缀进行了模块划分每个模块下挂对应的接口列表。这一步还有个细节技能会给每个模块生成一段简介内容是从类注释和第一个接口的功能描述推断出来的。虽然有时推断得不够精准但作为初稿已经有了足够参考价值。我把生成结果和早期的人工接口文档做了对比新接口的识别率基本是全覆盖的老接口的信息也能正确提取。最大的惊喜是它连接口里的deprecated注解都识别出来并标在了文档里——这个细节连很多人工维护的文档都没有。4.4 关于响应结构的处理逻辑请求体好搞响应体要更仔细响应结构的提取比请求体要复杂一些。技能在分析响应对象时需要顺着方法返回值类型去找到对应的类定义再解析这个类的所有字段。在Spring项目里响应往往是统一封装类比如Result 或ApiResponse 里面包了一个泛型data字段。技能需要能识别这个统一封装并在文档里标注接口返回统一格式data字段类型为XxxVO。如果处理不好这一层生成的文档会让人看不明白——所有接口响应结构都长成一个样里面具体包了什么东西反而没人知道。我的做法是在技能里加了一条规则当识别到统一响应包装类时解析其泛型参数类型进一步提取对应的VO类字段并在文档中响应结构一栏展开描述data字段的具体内容。这样文档读起来就很有料了。5. 实际使用中的参数要求与平台适配别忽略执行上限配置这个技能的时候我走了不少弯路。其中影响最大的一个限制是模型的上下文窗口和单次输出长度。接口文档这种结构化内容一多就很容易顶到输出上限。比如一个项目有60个接口按一个接口平均300字算完整文档就接近2万字。如果不能分段输出后半段往往会被截断生成到一半就停了。5.1 输出长度瓶颈拆成单文件单文档是最稳的我第一次测试时全体生成一个接口解析后输出了不到三个模块就中断了。排查才发现是单次输出内容过长触发了截断。后来改成按文件生成文档片段再把片段拼接问题就解决了。这种方式单次输出控制在几百到一千字左右非常稳妥。所以我建议实际使用中如果你的技能框架支持子任务拆分一定要用逐文件模式。如果不支持那就在技能描述里明确要求每个文件单独输出在所有文件处理完成后给出汇总文档。5.2 Token消耗评估跑一次完整项目要多少量有朋友问我生成一次文档消耗多少token这里我以模拟项目X的数据做一个大致估算。每读取一个Controller文件平均200行代码约5000到8000 token10个文件就是约7万到8万 token。加上目录扫描、框架识别和文档汇总整体一次完整运行的token消耗在10万左右。这个数值给一个直观概念如果你使用的是按token计费的服务生成一次完整文档大概相当于一本中短篇小说的处理量。对个人项目来说完全可接受对大型项目建议按模块分批生成不要一次全跑完。5.3 关于平台差异大部分Agent类工具都能挂上这套技能这套技能的结构并不绑定某一个特定平台。核心逻辑是指令模板 文件读取工具只要你的工具支持自定义指令并能读取项目文件基本都能迁移。比如有些平台的技能只是多了个UI配置入口本质一样。如果你对某个平台的技能格式不熟先找个最简单的示例跑通再逐步加复杂逻辑。这里有个实践小建议在配置技能时尽量把环境信息比如框架识别逻辑写在独立的小文件里方便跨平台复用。别把它们硬编码在一个主文件不然换平台时不好调整。6. 从能用到好用让文档真正服务于团队协作技能能跑通是一回事能不能真正替代人工文档又是另一回事。我在测试中总结了几条让文档更好用的经验。6.1 一定要安排的人工复核环节你要有个清醒的预期大模型生成的接口文档初稿准确率在正常代码和注释下主要字段的提取基本可靠真正需要注意的是推断性描述和参数语义。比如createUser这个接口模型可能推断为创建用户但如果这个方法实际是批量导入用户推断就会偏。所以我的流程是技能生成初稿后我花一点时间逐段过一遍修正推断错误补充注释里缺失的信息。这个环节很提效——比起从零写文档速度不可同日而语。更重要的是人工复核完的文档准确性很高能直接作为团队接口文档的基线版本。6.2 一点改进迭代细节把团队的接口规范融入技能不同的团队对接口文档的格式要求不同有的喜欢在文档里写请求示例和响应示例有的偏好通过表格列参数。这些需求都可以写进技能定义里。我在让这套技能符合团队风格时直接在技能指令里追加了一个要求每个接口必须包含一个可用示例请求体和响应体从代码结构生成值为模拟数据。这样生成的文档就有了参考价值前端Mock联调也可以直接用。如果你们团队用的是OpenAPI格式甚至可以要求技能按OpenAPI规范输出JSON那就更是直接对接工具链了。6.3 注意敏感信息与鉴权机制说明提取接口信息时技能能读取整个Controller层自然也能看到一些你不想暴露的内部细节。比如数据库字段名直接出现在VO里某些接口带有内部的调试信息。所以在技能可用的范围内建议增加一条规则默认不输出包含敏感关键词的字段描述如果包含token、secret、password等字段只能用鉴权用字段这样的形式模糊表述。这个细节让我在多团队协作时也放心不少文档作为交付物给到前端后不至于把后端内部实现全暴露出来。7. 踩过的坑与调试建议如果你配置出来效果不对配置这个技能的过程中我遇到了几个典型问题这里直接给结论省得你重走弯路。7.1 识别不出接口文件的排查思路如果你发现技能生成文档时发现能找到的接口很少八成是候选文件识别阶段出了问题。排查顺序是先看目录扫描是否覆盖了Controller目录再看框架识别是否准确比如把Flask项目识别成了Spring最后看文件名匹配规则是否过窄。我用一个笨办法快速验证直接问技能你目前认为哪些文件是接口入口为什么它的分析过程会暴露是哪个环节出了偏差。这个过程可以快速定位到是扫描的问题还是识别规则遗漏了。7.2 参数类型错误或缺失要么是读取不全要么是类解析失败有次测试时一个接口的参数类型被标成了String实际是Integer。查了之后发现问题是请求对象类里那个字段的类型是泛型技能只看到了泛型定义处没看到实际调用处的类型。解决办法是在技能描述里加了一句参数类型需参考具体Setter方法的参数类型而非泛型声明。这类细节在调试中比较隐蔽也没法一次性配置完美建议多跑几个样例做验证。7.3 文档模板前后不一致需要强输出规则刚开始测试时生成的文档格式经常漂移——同一个字段前一个接口叫参数说明后一个变成了参数描述。这是因为大模型在长输出中会略微偏离指令。解决办法是在技能核心指令里放一个示例段落标明以下是一个完整接口的文档模板之后的输出必须严格遵循此格式。这个少样本示例能让输出稳定得多。7.4 不忽略注释质量对输出效果的影响最后一条经验就是代码注释质量直接决定文档质量。如果你项目里的Controller代码本身就没有注释大模型能提取出来的信息就会受限只能靠参数名和上下文推断。最好的使用方式是将这套技能作为一个文档基线生成器帮助快速打通初稿而不是等待代码注释质量提升了再用。反过来用了这个技能之后你会发现以前代码写得不规范所以文档没法写的借口真的站不住脚了。8. 在快速原型与长期维护中的定位它是起点这套技能我用了近一个月后它已经替代了我手头好几个项目的接口文档初始编写工作。我的流程变成了迁移代码仓库时直接跑一次生成初稿花一点时间核对文档入库并通知前端团队后续接口变更时同步更新代码后重新跑一次对应模块的生成再人工快速确认。整体维护成本降了不少。它真正帮到我的是把编写接口文档这件事从一个从零开始的苦力活变成一个从草稿到成稿的快速编辑工作。前后端同事拿到手的文档格式统一、信息完整没有人工文档里常见的缺漏。如果你也受困于代码和文档不同步可以按这个思路配一个自己的技能也许以后你会感谢花掉的这几个小时。最后分享一个实用技巧如果项目是在持续迭代中可以把技能跑出来的文档片段直接接入到你的仓库文档页面中而不是把过程放在聊天记录里。这样可以保留每一次生成的版本记录接口变更时能一眼看出哪些字段在哪个版本发生了变化。这样文档跟着代码走才不是一句空话而是真正变成落地流程。