文档瘦身之后又长回来：和 Agent 一起整理项目文档

这篇记录一次和 AI 编程 Agent 一起整理项目文档的过程：动手前查了什么、文档怎么拆、加了哪些会一直跑的检查。整理之后 Agent 是否真的更守规矩，没有测过，文末「边界」一节会再说清楚。

这个博客的仓库给 Agent 准备了一份规则文件 AGENTS.md，每次会话全文加载；更细的规则、运维手册和历史记录放在 docs/ 下。10 月 10 日我在交给 Agent 的一组任务里加了一条：精简整合全站文档，同时对齐 README、AGENTS.md 这类说明文件。原话是「现在有的文档太长了，我担心模型可能不能很好地遵循」。

先查上一次为什么没管住

这不是第一次瘦身。9 月 12 日已经做过一次，AGENTS.md 从 36,969 字节削到 25,148 字节，事故叙事移进了审计日志。Agent 动手前先量了它之后的变化：四周后回到 28,855 字节，涨了 15%；同期视觉规范 design-system.md 从 50 KB 涨到 86 KB。

再按章节拆开看增量。AGENTS.md 涨的 3.7 KB 里，将近一半在「Important Paths」，多是新功能附带的路径说明。design-system.md 涨的 35.7 KB 全是带日期的条目，其中 30 KB 在「Documented Decisions」里逐条追加。两份文件都是同一个结构：现行规则和规则的来历写在一起，于是文件长度跟着改动次数增长。

所以这次的目标没有定成「再删一遍」，而是让必须遵守的那部分不再随改动变长。

怎么拆

第一步把冻结的文档单独放。三份月度 roadmap 档案、三份域名迁移稿、旧的 CMS 迁移方案、已完成的内联脚本迁移记录、改版交接稿和实施记录、两份被取代的设计规格，一共 12 份，原文不动移进 docs/archive/。文档检查脚本原来逐个列出不做时效检查的文件，每退役一份就要手改一次名单；现在改成整个目录豁免。

第二步把规则和账本分开。design-system.md 只留现行基线和规则，所有带日期的决策原文移到新的 design-decisions.md，以后改某个组件前在那里搜它的名字。培养机制的说明和它的任务卡日志拆成两份，前者从 26 KB 变成 4 KB。交接文档里那段停在 9 月 24 日的「最近一次发布证据」早已不是最近一次，原文移进审计日志，原位置换成仍然成立的已知限制。

第三步按关注点拆。运维安全文档里的 x402 付费墙政策并入 x402 运行手册，原来两份文档冲突时以谁为准要靠 AGENTS.md 里一条专门的规则，现在只剩一份。第三方分析工具的接入步骤在运维文档和 SEO 文档里各写了一遍，合成一份 analytics.md。写作规范里与 CMS 文档、图片文档重复的部分改成指针，「写作调性」八条原样保留，因为它要整节贴进给模型的任务书。

第四步只留一份索引。原来根目录 README、交接文档和 AGENTS.md 末尾各维护一份文档清单，三份并不一致；现在只有 docs/README.md，按「做之前先读 / 手册 / 账本 / 冻结历史」分组，其余地方都指向它。

AGENTS.md 本身改到 16,830 字节，规则没有删：事故表格压成一句并指向审计日志，路径说明只留路径和规则，两条只与样式有关的规则（目录折叠、表格横向滚动）移到视觉规范。

必读文档	整理前（字节）	整理后（字节）
AGENTS.md	28,855	16,830
content-authoring.md	25,804	19,090
design-system.md	85,851	9,739
seo.md	19,214	14,602
operations-security.md	61,522	30,672
owner-training.md	26,477	4,063
合计	247,723	94,996

文档总量没怎么变。多数内容是搬走而不是删掉，账本和 archive/ 里都还在；变少的是 Agent 动手前必须读完的那部分。

两道一直跑的检查

整理本身是一次性的，上一次的结果说明一次性的整理会被后续改动抵消。所以这次加了两条检查，放在每次构建都会跑的 npm run check:docs 里。

第一条是体积上限。AGENTS.md 18,000 字节，另外五份必读文档各有上限。超了构建失败，报错文字要求把叙事移进账本，而不是调高数字。

第二条是失效引用检查：代码注释、配置和现行文档里写到的 docs/…md 路径必须存在，现行文档里的相对链接必须能解析。这次搬了十几份文件，引用是用 grep 一处处找的，这条检查是为了下次不用再找。它第一次运行报出 18 处，全是这次整理之前就已经失效的。其中 10 处在 roadmap 和审计日志这两本账里，记的是当时的文件名，属于历史，检查改为不查这两本账；另外 8 处在现行文档和配置里，包括一条指向不存在文件的 wrangler.toml 注释，和两处把另一个仓库的文档写成本仓库路径的引用，都已改正。

协作是怎么进行的

同一条消息里还有别的事，Agent 按优先级排：先修图片放大后显示不全的 bug 并上线核验，再修点赞防刷用了未加盐 IP 哈希的问题，然后做文档，最后写这篇。文档分三次提交，每次提交前跑 npm run check。仓库的提交钩子会拦下「改了代码却没动文档」的提交，所以每一步都在 docs/roadmap.md 留了一条记录，写明改了什么、怎么核对、哪里没做。

过程中有一处要更正。第一次提交时，roadmap 和提交说明都写成「18 处失效引用已逐一改正」，实际上只改了 8 处，另外 10 处是让检查不再查。写这篇核对数字时发现，roadmap 已加注更正。

仓库里还有一份培养机制：不高于我当前级别的维护任务，Agent 要出一张任务卡让我自己做。文档整理和两个修复都高于这个级别，由 Agent 直接完成。发布这篇属于我练习的范围，Agent 起初停在草稿并写了任务卡，之后我让它代为发布。

边界

• 「文档短了，模型就更能遵循」是这次整理的前提，不是测出来的结论。整理前后没有用同一组任务对比 Agent 的表现，上面的数字只说明必读的字节少了。
• 搬走的内容没有借机重新核验，例如 x402 的政策资料和供应商额度，它们仍是原来那次核对时的状态。
• 当月的 roadmap 账本已有 91 KB，这次没动。它只追加，查历史时按关键词搜，不在必读之列。
• 体积上限只管字节数，管不了写得清不清楚。

写作说明：Claude Opus 5.5 根据会话记录起草，文中的文档整理也由它完成；作者决定发布。