改完代码还要更新文档，好痛苦！这个skill一招解决

上周晨会刚开完，下游组长把我堵在会议室门口。

“老X，你们上周改的那个接口，返回值多了一个字段，文档没更新，我们这边两天的活全废了。”

我回头一查，是小张改的。代码没问题，自测也过了，就是文档这步压根没走。

说实话，这事我不怪小张。

“改完代码再补文档”这事它就是反人性

带过团队的都知道，你刚在几百行代码里把逻辑理顺，脑子里全是实现细节，这时候让你去 docs/02-api/03-components/ 底下翻对应的mdx文件——谁干谁知道，翻着翻着就想放弃；或者说这个代码逻辑就是我写的，蜜汁自信，下次我肯定记得。

而且小张这人不懒，代码质量在组里排前三，review意见反馈也快。但文档这坎，他就是过不去，组里其他人也好不到哪去。好像做技术的人员，就本能的不愿意写文档、做分享，老难了。

我琢磨了一下，问题的本质不是大家不重视文档，而是文档更新的触发时机和编码是脱节的。编码是有明确结束信号的——“跑通了、合了”，但文档没有。你得额外启动一个任务，记忆成本极高。

后来我无意间看到TRAE官方文档中一篇《研发场景十大热门 Skill 推荐》的文章，里面推荐Next.js维护团队搞的那套update-docs规范，研究了一下核心思路：建立源码改动到文档位置的映射，把“找文档”这件事自动化。
你改了 packages/ui/src/button.tsx，它能告诉你对应的文档在 docs/components/button.mdx。你新增了一个prop，它能识别出API表格需要加一行。你不用记任何路径。

有了方向之后，我在 Trae 里给全组配了这个Skill。步骤比想象中简单：

Github地址：https://github.com/vercel/next.js/tree/canary/.agents/skills/update-docs

安装姿势一：一行命令搞定（推荐）

最简单粗暴的方式，在项目根目录跑这条命令：

npx skills add https://github.com/vercel/next.js --skill update-docs

跑完之后，CLI会弹出一个交互式选择框，问你要把Skill装到哪个编辑器。用键盘方向键选Trae，空格确认就行。

装完了看一眼.trae/skills/update-docs/这个目录有没有生成，有就说明成了。

但有个坑要注意：装完得重启Trae才能生效。我刚用的时候不知道，折腾了半天发现AI根本不鸟我，后来重启了一下就好了。

安装姿势二：手动创建（不想装命令行就用这个）

如果你不想全局装npx skills，可以直接在项目里手动建目录：

.trae/skills/update-docs/
└── SKILL.md

然后在SKILL.md里写最基础的元数据：

---
name: update-docs
description: 根据代码改动自动更新项目文档。当代码和文档不一致、需要同步文档时使用。
---
# update-docs 技能
（这里写具体的执行指令）

这个方式的优点是不需要装额外工具，缺点是要自己写SKILL.md的内容。不过你可以直接去GitHub仓库把现成的SKILL.md拷过来改改。

安装姿势三：Trae界面里直接操作（适合不碰命令行的人）

Trae右上角点⚙️设置 → 规则和技能 → 技能 → 点「创建」。

然后填三个东西：

• 技能名称：update-docs
• 描述：写上触发关键词，比如“更新文档”、“同步文档”、“docs需要更新”
• 指令：粘贴Skill的具体行为描述

填完确认就完事了，不需要重启，直接生效。

配好之后我让小张试了一下，对话框里输入“帮我定位这次改动对应的文档”，几秒钟返回结果，告诉他该改哪一章、哪一段。

落地过程中踩了一个坑

第一次全组推行的时候，好几个人反馈说“这玩意儿给的建议太多了”。仔细一看，原来默认会扫描所有改动文件，一次性给出全部文档建议。有个同事改了一个公共组件和一个内部工具函数，结果Skill把两个都扫出来了，工具函数那个根本不对外暴露，完全不需要文档更新。

后来我定了个规矩：用的时候指定范围。不要笼统地说“帮我更新文档”，要说“针对 src/components/Table 这次改动的文档”。或者我自己封装了一个快捷指令，让组员直接说“/doc Table”就能触发指定范围的文档检查。

另外还有一个让团队能真正用起来的关键点：它不会直接改你的文档。每次改动前生成diff预览，让你逐条确认——哪里改、哪里不动，勾选了才动手。组里几个老员工说，这功能让他们第一次觉得“工具是帮忙的，不是添乱的”。

不能指望靠“自觉”来维持规范

你天天在周会上强调“记得补文档”，没用。你在PR模板里加一行“请确认文档已更新”，有用但有限。真正起作用的，是把这件事的成本降到最低——低到大家顺手就做了，不需要额外启动意志力。

这套Skill配好之后，小张那种情况再也没发生过。不是因为大家记性变好了，而是文档同步从“想起来才做”变成了“顺手就做了”。三步变成一步，认知负担完全不在一个级别。

GitHub上有人统计说这套流程能让文档更新效率提升95%以上——一个15个组件变更的PR，手动更新文档要15-30分钟，用工具几秒钟定位。我没精确算过，但组里文档滞后的投诉从每个月三四次降到了零，这数据已经够有说服力了。

当Leader最舒服的状态不是盯着每个人干活，而是把规矩嵌进工具里，让工具替你盯着。

这个Skill不挑项目，前端项目能用，后端开发也能用。Trae里建个目录配好描述，扔进Git仓库，全组共享，以后就是跟AI说句话的事。

所以，你们团队中有没有类似不喜欢更新文档的童鞋，有的话，明天就去让他（她）装吧！