前两天看到赵纯想发了条推，说 AI coding agent 最大的问题之一是文档跟不上代码变化。

我深有同感。

代码库一大，文档就成了摆设。

于是我写了个 Claude Code skill，叫 auto-doc。

核心理念很简单：每次改代码，文档必须跟着更新。不是靠人记着，是靠 AI 自动执行。

01 三层文档结构

auto-doc 设计了三层文档体系，覆盖从项目全局到单个文件。

第一层：根目录的 ARCHITECTURE.md

放在项目根目录。用 10 行以内说清楚整体架构，然后链接到各子目录的文档。

只有架构层面的变化才需要更新它。

第二层：每个文件夹的 INDEX.md

每个有代码的文件夹都有一个 INDEX.md。

用 3 行说清楚这个文件夹的职责，然后用表格列出每个文件的角色和功能。文件有变动，这里必须同步。

第三层：每个代码文件的头部注释

每个代码文件开头都要有结构化注释。不是那种写了等于没写的注释，是有固定格式的：

/** * @input 这个文件依赖什么 * @output 这个文件输出什么 * @position 在架构中的角色 * @auto-doc 改动时更新 INDEX.md */

三层结构，从宏观到微观，缺一不可。

02 强制更新流程

结构设计只是第一步。

关键是 强制执行。

auto-doc 规定了一套必须遵守的更新顺序：

1. 改完代码，先更新文件头部注释
2. 然后更新所在文件夹的 INDEX.md
3. 如果是架构变动，最后更新 ARCHITECTURE.md

Claude Code 会按这个顺序执行。不是建议，是 skill 的硬性要求。

你可能会问：凭什么 AI 能判断要不要更新？

这就是 skill 的价值。SKILL.md 里定义了清晰的触发规则：

Claude Code 读完这个表，就知道该干什么了。

03 为什么不是事后生成

你可能用过那种"一键生成文档"的工具。

效果往往一般。

原因是它们在代码写完之后才介入，只能根据代码猜测意图。

auto-doc 不一样。它要求边写边记，在你还清楚自己在干什么的时候就把文档写好。

这其实是 AI 时代的新范式。

以前我们怕写文档，因为是额外工作量。现在 AI 替你写，你只需要在代码提交前 review 一下。

而且因为是增量更新，每次改动很小。不像从头生成，动辄几千字，没法看。

04 如何使用

把 SKILL.md 放到你的 .claude/skills/auto-doc 目录下，并在CLAUDE.md注明强制使用这个skill。

然后正常用 Claude Code 写代码就行。

每次涉及文件改动，Claude Code 会自动读取这个 skill，按规定流程更新文档。

第一次用的时候，你可能需要手动补一下已有代码的头注释。之后就是全自动了。

建议配合 git hooks 使用。在 pre-commit 阶段检查 INDEX.md 是否和文件列表一致，强制要求文档和代码同步。

这个 skill 解决的是一个老问题：文档和代码的不一致。

以前靠人的自觉，效果一般。现在靠 AI 的自动化，终于有了可行方案。

点击“阅读原文”获得markdown文件，欢迎star，我会维护这个repo，不断添加新的skills。

欢迎在评论区分享你的使用体验。