1. 文档同步不是“加个注释”就能解决的事大多数人改完代码顺手补一句// TODO: 更新文档，然后就去写下一个 feature。三个月后，这个TODO还在，而接口字段早已删了三个、新增了五个，Swagger UI 显示的却是半年前的字段名和类型。我上个月接手一个内部 SDK 项目，光是核对README.md和src/api/下实际导出的函数签名，就花了整整两天——不是因为代码难读，而是因为文档里写的getUsers(filter: string)在 v2.3 版本里早就被拆成了listUsersByStatus()和searchUsersByName()，但文档里连函数名都没变。更麻烦的是，这种脱节根本没法靠 CI 拦住。传统 linter 不认识@param里的类型是否匹配 TS 接口，Git Hooks 也判断不了 Markdown 表格里的字段描述是否还对应当前zodschema 的.shape定义。直到我们把 Claude Code 的 Sub-agent 模式真正用进文档流，才意识到：文档过期的本质不是人懒，而是文档和代码处在两个完全不同的生命周期里——一个靠手动提交触发，一个靠编译构建触发。本文讲的不是“让 AI 写文档”，而是让文档成为代码变更的必然副产品。它不依赖人工触发，不增加 PR 流程负担，也不要求每个开发者都精通 prompt