用只读脚本排查 AGENTS.md 里的失效命令
项目脚本改名或任务被删除后,AGENTS.md 里的旧命令仍可能被编码助手执行。文章介绍如何编写只读脚本,找出这些已经无法执行的命令。
AI 深度解读
把 package.json 里的 typecheck 改成 check,构建照常通过,AGENTS.md 却还写着 pnpm typecheck。团队成员早就记住了新命令,AI 编程代理(agent)仍会按文档执行旧命令。等它在收尾时跑检查,这条过期指令就变成了一次失败。
作者写了一个只读的 Python 脚本,专门检查 AGENTS.md 里的命令还能不能找到对应的脚本、Make 目标或文件。演示仓库里,8 条命令查出 3 处过期引用。这个做法适合已经把验证步骤写进 AGENTS.md、又经常调整脚本入口的团队。
为什么构建通过了,代理还是会卡住
AGENTS.md 可以告诉代理改完代码要跑哪些检查。按 agents.md FAQ 的说明,代理会尝试执行相关检查,并在结束任务前修复失败。旧命令失败后可能让代理花时间排查,是作者对执行过程的推断,原文没有测量这类失败会耗时多久。
演示里的三种变更都很常见。类型检查脚本从 pnpm typecheck 改成 pnpm check,数据库播种逻辑迁走后删掉了 make seed,生成 API 类型的脚本从 scripts/gen-types.sh 移到了 tools/gen-types.sh。如果 CI 已经在用新入口,这三处改动可以一路通过,旧引用继续留在文档里,直到有代理照着它运行。
以类型检查为例,CI 调用 pnpm check,通过时验证的是新入口所执行的检查。代理根据文档调用 pnpm typecheck,第一步就得在项目脚本里找到这个名字。只要构建流程没有核对文档里的命令,改名时漏掉的那一处引用就可能一直留到下一次代理收尾才暴露。
Claude Code 的 /doctor prompt-audit 也会找不存在的文件或命令引用。作者给出的脚本用固定规则做同一类检查,用的是 Python 标准库,能直接在 CI 里跑,结果也可以交给不同工具使用。
一个只读脚本能查到什么
脚本从指定目录读取 AGENTS.md,逐行提取反引号里的内容,再用 shlex.split 拆分命令。对 pnpm、npm 和 yarn,它去 package.json 的 scripts 查名字,并放行 install、ci 等预先列出的内置命令。遇到 make,它去 Makefile 查目标。遇到 bash、sh、python、python3 或 node,它把第一个参数当成文件路径检查。
这段代码解决的是「文档指向的入口还在不在」,全程只读文件。读输出时要先看一条命令是按哪条规则通过的。pnpm install 命中的是内置命令名单,pnpm check 核对的是项目脚本名,bash tools/gen-types.sh 核对的是指定目录下的路径。这几类 ok 都来自同一次静态扫描,各自对应一次不同的查找。
#!/usr/bin/env python3
"""Check that commands written in an AGENTS.md still point at things that exist.
Reads only. Runs nothing. Usage: python3 agents_cmd_check.py [repo_dir]"""
import json, re, shlex, sys
from pathlib import Path
repo = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
agents = repo / "AGENTS.md"
pkg = repo / "package.json"
scripts = json.loads(pkg.read_text()).get("scripts", {}) if pkg.exists() else {}
makefile = (repo / "Makefile").read_text() if (repo / "Makefile").exists() else ""
targets = set(re.findall(r"^([A-Za-z0-9_.-]+):(?!=)", makefile, re.M))
BUILTIN = {"install", "i", "ci", "add", "remove", "update", "audit", "exec", "dlx", "outdated"}
NODE = {"pnpm", "npm", "yarn"}
problems = checked = 0
for no, line in enumerate(agents.read_text().splitlines(), 1):
for span in re.findall(r"`([^`]+)`", line):
try:
argv = shlex.split(span)
except ValueError:
continue
if not argv:
continue
tool, args = argv[0], argv[1:]
msg = None
if tool in NODE and args:
name = args[1] if args[0] == "run" and len(args) > 1 else args[0]
if name not in BUILTIN and name not in scripts:
msg = f"no script '{name}' in package.json"
elif tool == "make" and args:
if args[0] not in targets:
msg = f"no Makefile target '{args[0]}'"
elif tool in {"bash", "sh", "python3", "python", "node"} and args:
if not (repo / args[0]).exists():
msg = f"file not found: {args[0]}"
else:
continue
checked += 1
if msg:
problems += 1
print(f"MISSING line {no}: `{span}` -> {msg}")
else:
print(f"ok line {no}: `{span}`")
print(f"{checked} command(s) checked, {problems} problem(s)")
sys.exit(1 if problems else 0)
留意 name = args[1] if ... 这一行。它能取出 pnpm run check 里的 check,但也会把 pnpm vitest run 里的 vitest 当成项目脚本名。项目里即使装了 Vitest,只要没有同名的 scripts 条目,也会报缺失。统计里的「已检查」只包括进入这些规则的命令。拆分失败的反引号内容和规则未识别的命令都会跳过,因此问题数为零时,还要结合检查条数判断文档里的常用命令覆盖了多少。
三处报错是怎么消掉的
作者在 2026 年 11 月 22 日用 Python 3.13.5 跑了一个小仓库。仓库的 package.json 定义了 dev、build、test、lint 和 check,Makefile 里有 migrate。第一次运行定位到了三条旧指令所在的行。
$ python3 agents_cmd_check.py demo-app
ok line 4: `pnpm install`
ok line 5: `pnpm dev`
ok line 6: `pnpm test`
ok line 7: `pnpm lint`
MISSING line 8: `pnpm typecheck` -> no script 'typecheck' in package.json
ok line 9: `make migrate`
MISSING line 10: `make seed` -> no Makefile target 'seed'
MISSING line 11: `bash scripts/gen-types.sh` -> file not found: scripts/gen-types.sh
8 command(s) checked, 3 problem(s)
exit code: 1
其中第 11 行报的是文档里的旧路径,修复时把它更新为 bash tools/gen-types.sh 即可。另两处分别改成 pnpm check 和删掉已取消的 make seed 指令。之后执行 python3 agents_cmd_check.py demo-app-fixed,检查了 7 条命令,问题数为 0,退出码也从 1 变成了 0。
检查条数从 8 条降到 7 条,来自移除 make seed。类型检查和 API 类型生成仍是文档里的操作,只需把它们指向现有入口。脚本给出的行号和缺失项能帮评审找到具体该看的地方。至于一条指令该更新还是删除,要看原来的操作在改动后是否还需要执行。
退出码让它能接到 CI 或 pre-commit hook 上。对于 monorepo,原文援引 agents.md 的说明,距离工作位置最近的 AGENTS.md 优先。因此,包里有自己的指令文件时,就用 python3 agents_cmd_check.py packages/api 这类调用,让它读取对应目录的 AGENTS.md 和 package.json。脚本单次只查一个目录,有多份文件就需要分别运行。传入 packages/api 也会改变相对路径的查找起点,文件路径和 Makefile 都会从这个子包目录查找。
我的判断
这个检查最适合命令格式统一的团队。前端仓库往往已经有稳定的 package.json 脚本入口,把这些入口写进 AGENTS.md,再做一次静态核对,维护成本很低。人工评审更擅长看命令的用途变没变。例如 pnpm test 仍然存在,却改成只跑一小部分用例,脚本会照常打印 ok,评审和实际执行才有机会发现覆盖范围的变化。同样,在更新 pnpm check 的文档引用时,评审还可以核对 package.json 中这个脚本实际执行的内容,确认它仍然完成文档要求的类型检查。
原文只展示了一个小仓库修复前后的实测,没提供跨仓库的误报率,也没对比人工评审或 /doctor prompt-audit 的效果。至于接入后能节省多少代理排查时间,仍是经验判断。落地前可以先看自己仓库里的命令写法。除了直调 vitest 会误报,node --version 也会把 --version 当作路径。目录也能通过 exists(),所以 ok 只说明指定路径存在。Cargo、Gradle、just、正文里的路径和「不要编辑生成文件」这样的约束,都超出了这个脚本的检查范围。
能拿来做什么
- 在改名、删除或移动脚本的同一个 PR 里更新
AGENTS.md。让代理把命令定义和引用一起改,顺手清掉已经停用的指令。 - 对常用的前端检查优先记录团队维护的脚本入口。如果仓库习惯直接调用
pnpm vitest run,就先决定是否封装成package.json脚本,或扩展检查器识别这种写法,再用退出码1阻断 CI。 - 在仓库根目录运行
python3 agents_cmd_check.py。如果 monorepo 的子包有独立的AGENTS.md,就按包传目录检查,并在合并前继续运行实际测试。