agentsfile

agentsfile

Agent 指令文件会悄悄过时。本工具会根据它们所描述的代码库进行检查。

AGENTS.md 和 CLAUDE.md 会告诉编码 Agent 如何处理代码库：哪些文件很重要、要运行哪些命令，以及项目的布局。代码库的变化速度比指令文件快。目录被重命名、脚本被删除、指南从头到尾都只是个空壳，而 Agent 仍照着文件行事，于是白白浪费一次运行，或凭空编造文件中错误的内容。不会有任何明显的失败，因为从来没有人检查过文件与代码库是否一致。

agentsfile 会执行这项检查。它会读取代码库根目录下的 AGENTS.md 和 CLAUDE.md，提取反引号中的路径以及 npm、yarn 和 pnpm 脚本引用，并根据实际文件树和实际的 package.json 验证每一项。每条发现都附有文件、行号及其来源的确切文本。输出具有确定性：发现按顺序排列，不含时间戳，同一代码库始终会生成相同的报告。

检查内容

规则	严重级别	含义
NO-FILE	高	代码库根目录下既没有 AGENTS.md，也没有 CLAUDE.md。
PATH-MISSING	中	看起来像相对路径的反引号文本在代码库中不存在，无论是文件还是目录。
SCRIPT-MISSING	中	被引用的脚本（npm run <name>、npm test、yarn <name>、pnpm <name> 等）未在 package.json 的 scripts 中定义。
STUB	低	Agent 文件存在，但内容为空或少于 5 行。
NO-PACKAGE-JSON	信息	代码库根目录下没有 package.json（或文件无法解析），因此未检查脚本引用。

判定规则：

• VALID：没有中级或高级发现。可以有低级和信息级发现。退出码为 0。
• DRIFT：至少有一条中级或高级发现。Agent 文件与代码库不一致。退出码为 1。
• MISSING：代码库根目录下既没有 AGENTS.md，也没有 CLAUDE.md。退出码为 1。
• 用法错误的退出码为 2。如果读取方提前关闭输出管道，进程会以 141 退出，绝不会以 0 退出。

脚本引用详情：npm run <name> 会直接检查 <name>。常见简写 npm test 和 npm start（以及 stop 和 restart）会映射到同名脚本。对于 yarn 和 pnpm，<manager> <name> 和 <manager> run <name> 会检查 <name>；包管理器自带的子命令（install、add、publish 等）绝不会被视为脚本。

用法

CLI

# Check the current repo
npx @reneturcios/agentsfile check

# Check another repo, machine readable
npx @reneturcios/agentsfile check ~/src/my-repo --json

# Print the version
npx @reneturcios/agentsfile --version

输出示例：

agentsfile check .: DRIFT
  files: 2, findings: 2 (high: 0, medium: 2, low: 0, info: 0)
  summary: 2 agent file(s) checked; 2 finding(s): 0 high, 2 medium, 0 low, 0 info. Verdict: DRIFT.

AGENTS.md:
  [MEDIUM] line 4 PATH-MISSING `src/gone.ts` Referenced path does not exist in the repo: src/gone.ts
  [MEDIUM] line 5 SCRIPT-MISSING `npm run deploy` Script referenced but not defined in package.json scripts: deploy

DRIFT: at least one medium or high finding; the agent files disagree with the repo.

使用 --json 时，会以 JSON 格式打印完整报告：工具、版本、目标、判定、计数（文件数、发现数和各严重级别的总数）、发现数组以及单行摘要。检查无需凭据或网络，也不会执行目标代码库中的任何内容。

目标也可以是单个 Agent 指令文件，而不是目录；此时会将该文件所在目录视为代码库根目录，并且只检查该文件。

MCP 服务

npx @reneturcios/agentsfile mcp

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "agentsfile": {
      "command": "npx",
      "args": ["-y", "@reneturcios/agentsfile", "mcp"]
    }
  }
}

工具：check_agents_file(path) 会以 JSON 格式返回对 path 所指代码库（或单个文件）的完整检查报告。

明确说明限制

• 只会读取仓库根目录中的 AGENTS.md 和 CLAUDE.md。此版本不会检查子目录中的嵌套 Agent 文件。
• 只会检查两种引用：反引号括起的内容，以及 npm、yarn 和 pnpm 脚本模式。脚本模式可以找到围栏代码块中展示的命令，但不会检查围栏代码块中未用反引号括起的路径，也不会检查链接、正文中的提及，或来自其他工具链（make、cargo、go 等）的命令。
• 路径检测采用启发式规则，并如实说明：如果反引号括起的内容不含空格、不以 http 开头，且包含斜杠，或以已知列表中的文件扩展名形式结尾（另加一小组已知点文件，如 .env），就会被视为路径。包含 @、:、*、= 或引号等字符的标记永远不会被视为路径，因此带作用域的包名和操作引用不会被标记。反过来说：确实可能漏掉不常见的文件名，也可能误报碰巧看起来像路径的标记。结果中始终会引用确切内容，方便人工一眼判断。
• 该检查只确认是否存在。路径存在，并不代表它就是正确的文件；脚本存在，也不代表它会执行指南所述的操作。
• 占位文件规则依据行数（少于 5 行），而非质量判断。简短但确实完整的文件仍会以低严重性报告，但这本身绝不会改变最终判定。