跳到正文
DEV Community· PromptMaster·· 5 小時前AI 評分60

如何找出 AGENTS.md 中已失效的命令

Your AGENTS.md Lists Commands That No Longer Exist. Find Them

AI 導讀

這篇教學提供一個唯讀 Python 腳本,檢查 AGENTS.md 中以反引號標示的命令是否仍指向存在的腳本、Makefile 目標或檔案。腳本支援 pnpm、npm、yarn scripts、make 目標,以及 bash、sh、python、python3、node 的檔案參數,不會執行命令,並可在 CI 或 pre-commit hook 中以錯誤碼 1 令步驟失敗。

正文

Say you renamed typecheck to check a few weeks ago. Your AGENTS.md still says pnpm typecheck. Nobody noticed, because nobody on the team reads that line anymore. The agent does.

The agents.md FAQ is direct about what happens to commands you list: "The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task." A command that no longer exists fails every time, and there is nothing sensible for the agent to fix. That last part is my reasoning, not something the docs promise, but it is easy to see how a dead line costs you a confusing session.

The same FAQ answers "Can I update it later?" with "Absolutely. Treat AGENTS.md as living documentation." Living documentation drifts unless something checks it. This article builds that check: a read-only script that tells you which commands in your file point at things that are gone.

Earlier articles covered six mistakes that make agents ignore the file and what a stray file can load. This one is about a file you wrote yourself that went out of date.

How the file goes stale

Three kinds of drift cover most cases:

  • A renamed script. pnpm typecheck becomes pnpm check, and the old name stays in the file.
  • A removed task. A make seed target gets deleted when the seed logic moves, and the file still tells the agent to run it.
  • A moved file. scripts/gen-types.sh moves to tools/, and the path in the file is now wrong.

None of these breaks a build, so no CI job complains. The only reader that follows the line literally is the agent.

Claude Code has a built-in check for part of this. Its memory docs say that /doctor prompt-audit makes Claude look for "references to files or commands that don't exist", among other problems. That is useful if you work in Claude Code. A small deterministic script is a good complement: it runs the same way in any tool, in CI, and without a model in the loop.

The check

The script reads AGENTS.md, pulls out every command written in backticks, and checks that its target exists. It never runs the commands. It handles pnpm, npm and yarn scripts (against package.json), make targets (against the Makefile), and bash, sh, python, python3 and node file arguments. Everything else is skipped. It uses only the Python standard library.

#!/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)

Save it as agents_cmd_check.py. It exits with code 1 when it finds a problem, so a CI step or a pre-commit hook can fail on it.

A real run

I built a small demo repo with a package.json (scripts dev, build, test, lint, check), a Makefile with a migrate target and an AGENTS.md that has the three kinds of drift above. This is the output of the script, run on my machine on 22 Nov 2026 with Python 3.13.5:

$ 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

Three of eight commands point at nothing. The fix is to edit the file, not the repo:

@@ -5,10 +5,9 @@
 - Dev server: `pnpm dev`
 - Test: `pnpm test`
 - Lint: `pnpm lint`
-- Typecheck: `pnpm typecheck`
+- Typecheck: `pnpm check`
 - Apply migrations: `make migrate`
-- Seed the database: `make seed`
-- Regenerate API types: `bash scripts/gen-types.sh`
+- Regenerate API types: `bash tools/gen-types.sh`

 ## Boundaries
 - Never edit `src/generated/`

And the same check afterwards:

$ python3 agents_cmd_check.py demo-app-fixed
ok       line 4: `pnpm install`
ok       line 5: `pnpm dev`
ok       line 6: `pnpm test`
ok       line 7: `pnpm lint`
ok       line 8: `pnpm check`
ok       line 9: `make migrate`
ok       line 10: `bash tools/gen-types.sh`
7 command(s) checked, 0 problem(s)
exit code: 0

Everything above is a real run on the demo repo, not a mock-up. Your repo will print different lines, and the script only tells you whether a name exists. A command can exist and still fail, so keep running your real test command before you merge.

Where to run it

  • In CI or a pre-commit hook. Run python3 agents_cmd_check.py from the repo root. Exit code 1 fails the step.
  • In a monorepo. The agents.md site says agents read the nearest AGENTS.md, so the closest file takes precedence. The script takes a directory as an argument, so check each package against its own package.json: python3 agents_cmd_check.py packages/api.
  • When you rename something. Ask the agent to update AGENTS.md in the same change, then run the check.

What it does not catch

  • Binaries called directly. A line such as pnpm vitest run is reported as a missing script, because vitest is not in scripts. Either add a script for it or edit the checker to accept it.
  • Wrong but existing commands. If pnpm test now runs a different suite, the name still exists. Only a human, or a real run, catches that.
  • Prose instructions. "Never edit generated files" can't be checked by a script. Paths mentioned outside commands are not checked either.
  • Other runners. Cargo, Gradle, just and others are skipped. Adding one is a few lines.

Checklist

  1. Every command in AGENTS.md is an exact command, not "run the tests".
  2. A script checks those commands against package.json, the Makefile and file paths.
  3. The check runs in CI or a pre-commit hook and fails on exit code 1.
  4. In a monorepo, each package's file is checked against that package.
  5. Renames and moves update AGENTS.md in the same pull request.
  6. You still run the real test suite before you merge.
  7. If you use Claude Code, /doctor prompt-audit is a second opinion, not a replacement.

Where to go next

If you don't have a lean, concrete AGENTS.md yet, the free AGENTS.md Quick-Start Cheat Sheet covers what belongs in the file, what to leave out and how to use one file across tools, in 6 pages.

For the full picture, AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard goes deeper on how agents find and load the file, the monorepo hierarchy, the commands section, common mistakes and a 30-day adoption plan, in 42 pages.

This article was written with the assistance of AI and reviewed by the author.

來源:DEV Community · dev.to