prumo

检查编码 Agent 读取的上下文文件，并与其旁边的代码进行核对。

问题

三个月前，有人在 CLAUDE.md 中写下了这段内容：

The sidebar logo lives in `layouts/AppLayout.vue`.

此后，这个文件夹被重命名为 Layouts，首字母改成了大写。Windows 和 macOS 仍能打开该路径，因此从未有人发现问题。Linux 和 CI 则不行，每个读取该文件的 Agent 都会被引向一个不存在的位置。

同样的文件经过六次手动审查，这一行依然被漏掉了。prumo 用了四秒就找到了它。

快速开始

如果你已经安装了 Node.js 18+ 和 git，就可以开始了。无需安装、无需配置，也无需创建账户。在任意 git 仓库内打开终端：

npx @tomd4vs/prumo

prumo 会自行查找上下文文件：CLAUDE.md、AGENTS.md、.cursor/rules、.github/copilot-instructions.md、.claude/skills/ 中已安装的技能，以及其他文件。它会查找的所有文件和文件夹都列在参考文档中。

如果经常使用，可以安装一次：

npm install -g @tomd4vs/prumo             # available everywhere on your machine
npm install --save-dev @tomd4vs/prumo     # or as a dev dependency of one project

无论哪种方式，命令都是 prumo，且零依赖。如果这一步出错，例如 Node 版本过旧或当前文件夹不是 git 仓库，请参阅故障排除。

查看结果

检查通过：

prumo — 1 context file, 401 files tracked by git

nothing to review.

发现问题的运行结果及注释：

prumo — 3 context files, 412 files tracked by git             ← what it read
        1 historical entry exempt from path checks            ← what it skipped on purpose

CASE MISMATCH  (1)   wrong letter case: works on Windows and macOS, fails on Linux and CI
  CLAUDE.md:18  layouts/AppLayout.vue   ->  resources/js/Layouts/AppLayout.vue
                ↑ what the note says        ↑ what the repository has

BROKEN LINK  (2)   points at a page or heading that is not there; 1 with a likely destination
  CLAUDE.md:21  [[deploy-checklist]]   ->  deploy_checklist   ← the file it probably meant
  CLAUDE.md:30  [[old-architecture]]                          ← no candidate: renamed or deleted

MISSING PATH  (1)   the note cites it, but git tracks no such file or folder
  docs/setup.md:44  config/database.php                       ← file, line, dead path
      Copy the template into `config/database.php`…           ← the sentence, so you can judge

4 to review, --fix corrects 1                                 ← 1 + 2 + 1

每条问题都会标明文件、行号和修正建议；如果 git 历史记录了重命名，缺失路径还会指出 git 将其移到了哪里。工具不会猜测，也不会写入任何内容。每条问题的含义和处理方法见参考文档。如果它标记了一行你确认无误的内容，忽略问题介绍了两种说明方式；如果它没有标记你预期会提示的内容，prumo --explain CLAUDE.md:12 会说明它读取了什么，以及哪个过滤器做出了判断（为什么某一行会或不会被报告）。

它不会做什么

三个刻意设定的限制，详见设计：

• 它不会判断陈述是否属实。要判断 “此标志会禁用缓存” 是否仍然准确，需要用到模型，而那是另一种工具。
• 除了更正字母大小写和 git 自身记录的重命名，它不会做其他修改。根据名称建议链接只是有依据的猜测；没有历史记录的缺失路径也可能是有意删除的。
• 它不会进行网络调用。没有遥测、没有账户、没有模型。

发布之前，每项检查都在公开仓库上进行了测试；设计页面公布了测试数据，包括不理想的结果。

从 Agent 中使用

prumo 是一个纯 CLI，因此任何可访问 shell 的 Agent 都能运行它。

让 Agent 运行它。 npx @tomd4vs/prumo 可在任何 git 仓库中运行，并会自动检查安装在 .claude/skills/ 下的技能。对于本身就是技能的仓库，请指定文件：npx @tomd4vs/prumo . SKILL.md。文本输出会列出文件、行号和修正内容，足以让 Agent 直接处理，无需解析。--format json 会以结构化数据返回相同的检查结果。

将其作为工具提供。 此软件包还附带 prumo-mcp，这是一个通过 stdio 提供服务、包含五个工具的 MCP 服务：只读的 prumo_check，会改写字母大小写和 git 记录的重命名的 prumo_fix，以及三个同样只读的报告工具 prumo_drift、prumo_budget 和 prumo_coverage。在 Claude Code 中：

claude mcp add prumo -- npx -y -p @tomd4vs/prumo prumo-mcp

其他 MCP 客户端的配置见 Agents。

添加斜杠命令。 在 .claude/commands/prumo.md 中创建文件，即可将检查变为 /prumo：

Run `npx @tomd4vs/prumo` and fix every finding it reports.

每次编辑后运行。 PostToolUse 钩子会在 Agent 写入上下文文件时运行 prumo，让检查结果出现在对话记录中，以便它在同一轮中进行修正。适用于 bash 和 PowerShell 的钩子见 Agents。

持续集成

prumo 在发现问题时会以非零状态码退出，因此可作为单个步骤加入流水线。最简方式是使用此仓库提供的 action：

# .github/workflows/docs.yml
name: docs
on: [push, pull_request]
jobs:
  prumo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: TomD4vs/prumo@v1

它会在拉取请求的确切行上添加注释，并在有内容需要审查时使任务失败。在 actions/setup-node 之后运行 npx @tomd4vs/prumo --quiet，在任何流水线中也能达到相同效果。照常使用 actions/checkout；prumo 会读取 git 索引，因此不包含该索引的检出方式无法使用。以下三个选项涵盖其他需求：

• --baseline 会记录已有积压问题的仓库当前状态，之后的运行只会因新增问题而失败。
• --since origin/main 只检查拉取请求涉及的上下文文件。
• --sarif FILE 会输出用于代码扫描的问题，.pre-commit-hooks.yaml 则通过 pre-commit 框架在每次提交前运行相同的检查。

action 的输入参数、SARIF 上传和 pre-commit 配置见参考文档。

三种报告

除了检查之外，还有三个命令用于测量而非评判，无论发现什么都会以状态码 0 退出：

prumo drift     # which sections describe code that changed since they were written
prumo budget    # what each context file costs the agent, and what is written twice
prumo coverage  # which folders of the code no context file mentions, most active first

drift 会通过 git blame 获取每个章节最后一次编写的时间，统计此后修改过其引用文件的提交次数，并优先列出变动最多的章节：这可作为审查时的阅读顺序，因为某个章节引用的文件即使变更了四十次，内容仍可能正确。budget 会估算每次会话中上下文文件的成本，包括 CLAUDE.md 导入的文件，以及只有在使用技能、文件夹说明或作用域规则时才会增加的成本；它还会计算自某次提交以来的增长量，并列出在多个位置重复编写的段落。coverage 会按软件包列出工作区中未被任何上下文文件提及的代码文件夹，并优先列出过去九十天提交次数最多的文件夹：也就是 Agent 从未获知的内容。三个命令的说明都在参考文档中，且都可作为 MCP 服务的工具使用。

文档

页面	解答的问题
参考文档	每个选项和退出码的含义、每种检查结果的含义、如何忽略某项检查，以及 --fix 会修改哪些内容
Agents	完整介绍每种集成：MCP 服务、适用于 bash 和 PowerShell 的 PostToolUse 钩子、斜杠命令
设计	为什么检查项如此少：移除符号检查器的测量结果，以及让其余检查保持安静的过滤规则
故障排除	错误消息，以及人们在采用前常问的问题
API	如何从代码中调用，以及如何运行测试套件

许可证

MIT