文档检查 · 检查放在文档里,等于没有

📦 这份资料包里有什么

👉 滑动

现成的工具里有一个 driftlint。文档里写着 npm run deploy——deploy 不在 scripts 里，它就报错。

可 npm test 这种写法，它一个字都不说：命令名直接跟在 npm 后面，中间没有 run。这恰恰是我们写文档时最顺手的写法。

它只认「npm run + 名字」这一种格式，别的命令写法一概不看——pnpm build、yarn dev 都一样。

补它，逻辑就三句话：

一、把文档里反引号包着的命令全捞出来

二、每条命令的最后一个词，就是脚本名

三、拿去 package.json 的 scripts 里找，没有就报

脚本我写在最后一节了，27 行，不用读——存成 scripts/check-commands.sh 就能用。

我那个小项目的文档里留了一行早就不存在的 npm test，它只报这一行；有问题时退出码是 1，所以能挂在钩子上拦住提交——下一节说怎么挂。

一句说明：它只认 package.json，也只读文档、不写任何文件。你的项目要是用 justfile、Makefile，把取脚本名的那两行换掉，三句话的逻辑不变。npm install 这类内置命令它跳过了；项目里压根没有 package.json，它会一声不响地退出——那不等于“检查过了”。

两段配置——挂 pre-commit，提交时拦；挂 CI，推送时查——都在最后一节，选一个或都上。

⚠️ .git/hooks/ 这个目录不进版本库，换台机器、重新克隆就没了。团队要一起用，把它放在仓库里的 .githooks/ 下，再执行一次 git config core.hooksPath .githooks——这样它跟着代码走。

这是挂了之后的效果。文档里留一行 npm test——就是第一节说的、现成工具漏掉的那种写法。两道检查挨着跑，第一道没看出问题，第二道把它拦下来，那条提交没进历史：

把那行改对，再提交就过了。这一条是关键：拦住的不是提醒，是提交本身。

也正因为这样，两道都得挂：driftlint 那一道只管 npm run 那种格式，补的这道管它看不见的写法。只挂一道，另一道漏的错照样进历史。

挂哪儿，是我自己跑出来的结论：

查“文档点名的东西还在不在”，放提交时 —— 快，不拖你

查“内容有没有过期”（比文件时间），放推送时或者 CI 里 —— 它要翻 git 历史，慢

那份判据卡的审计，每次推送带一次，再每周过一遍

最后一句实话：driftlint 是 8 月 11 号发的第一版，一个多月更了 11 个版本，最近一周下载 66 次。它哪天不在了、改得你不认识了，或者你不想多装一个包，把 npx 那行删掉，剩下的照样跑。

路径和命令，脚本对得了。但有一类机器永远看不出来：约定过期了。

文档写着“我们的组件还在用类组件”，其实早就全换成函数组件了；写着“改表结构必须走评审”，那个流程半年前取消了。

这种没有唯一答案，只能让另一个 agent 读。但它读的时候你得给它三条约束——不给，它会“顺手把文档更新一下”，然后跟你说更完了。

一、只出报告，不改文件（改不改，我点头之后再说）二、每条发现必须能说成“某处写着 X，但 X 不成立”；写不成的，别放进报告三、分不清是文档错了还是代码歪了，两个都列出来，交给人

第二句是整张卡的重心。像“组件应该用函数写”这种话，说不成那个格式——它不是“某处写着 X 但 X 不成立”，它是个没落地的观点。这一句卡住，报告里剩下的就都是能查证的。

能直接粘给它的一段：

还有两件事，比指令本身更要紧：

别让它一边干活一边顺手更文档。 它对自己刚干的活，判断力最差。

agent 自己说“我更新过了”，不算数。 要独立的一步，专门对账。

三份，原样复制。不用读。 前两份今天就能做完；第三份，等你有了 CI 那天再回来拿。

一、补漏的检查 → scripts/check-commands.sh

二、挂在提交上 → .githooks/pre-commit（放仓库里，chmod +x，再跑一次 git config core.hooksPath .githooks）

三、挂 CI → .github/workflows/docs.yml

还有一层在 PART 03 · 三条判据卡：三条约束，加那段可粘给 agent 的指令——留到你要清文档的那天用。

翻一遍你的文档，问一句：

这里面哪句话是错的，也不会有人发现？那一句，就是你要接的那根线。