agents-md-lint

agents-md-lint

通过启动一个盲审子 Agent，仅依靠代码搜索尝试重新发现每条已记录事实，以审查 AI Agent 指令文件。测试描述性事实的实际发现成本。即使代码中能看到遵循规范的示例，也要保留规范性指令。

此工具适用于任何旨在向 AI Agent 提供代码库上下文的文件：AGENTS.md、CLAUDE.md、CONVENTIONS.md、.cursorrules 或类似文件。工作流统称这些文件为“指令文件”。

模式

默认（改写）： 生成报告，并改写指令文件，仅保留仍有价值的事实。

试运行： 生成报告，但不修改任何文件。当用户想在提交前查看更改内容，或提出“只展示结果”“仅生成报告”或“哪些内容是多余的？”等要求时，使用此模式。如果模式不明确，请在询问第 1 步中是否有其他文件或要排除的文件时，一并询问用户希望使用哪种模式。

工作流

1. 查找并规范化指令文件

扫描代码库，查找指令文件。常见文件名包括：AGENTS.md、CLAUDE.md、CONVENTIONS.md、.cursorrules、.github/copilot-instructions.md。询问用户是否还有其他文件，或是否需要排除某些文件；如果模式不明确，也要一并询问，让用户只需回答一次。

仅在用户另行要求时，才重命名或创建指令文件的符号链接；精简内容不会改变这些文件的发现路径。

2. 提取事实

将强制规范、禁止事项和验收约定与描述性事实区分开来。除非明确被取代，否则保留前者；代码示例不能证明某条规则没有必要。按文件分组，将每条描述性事实列为编号条目。“事实”指任何单独的主张、规范、指令或背景信息，例如“测试使用 vitest”“分支名称遵循 feature/JIRA-123 格式”“集成测试中绝不模拟数据库”。

3. 将事实分批测试

一次提出太多问题会降低子 Agent 的可靠性。如果某个文件包含 25 条以上事实，请将其拆分为每批 20–25 条，并为每批启动一个独立子 Agent。每批内容都应自成一体；在提示词中提供足够上下文，让子 Agent 无需查看其他批次也能理解相关领域。所有指令文件的批次都应在一次并行调度中启动，而不是逐个文件处理。

4. 启动盲审审查者

针对每批描述性事实，启动一个不继承对话或指令上下文的隔离子 Agent，并使用以下任务模板。关键是子 Agent 不得访问指令文件——它只能依靠搜索代码找到的信息。不要重命名或移动文件，以免出错时造成数据丢失；而应明确告知子 Agent 要忽略哪些文件：

You are reviewing the codebase at <REPO_PATH> to test what facts are easily
discoverable from code alone — without any documentation.

IMPORTANT: Do NOT read or search inside these files, as they are the
documentation being audited:
<list of instruction file paths to exclude>

For EACH question below, try to answer using code searches (grep, glob,
reading config/source files). Use up to 3-4 searches per question — check
multiple locations if the first search doesn't find it (e.g., config files,
source code, test files, CI configs). Answer briefly and rate your confidence:

- HIGH: Found clear, unambiguous evidence
- MEDIUM: Found partial or indirect evidence (e.g., an example exists but
  the convention isn't stated, or the fact is buried in a non-obvious place)
- LOW: Could not find evidence, or only found it after extensive digging

For MEDIUM answers, note WHERE you found the evidence and how many searches
it took. This helps distinguish "technically findable but practically buried"
from "right there in the config."

QUESTIONS:
<numbered list of questions, one per extracted fact>

使用所选运行时模型或明确的审查者配置。记录搜索过程和查找耗时；如果指令自动加载功能妨碍了盲审，请说明这一点。

5. 评估结果

将每个子 Agent 的回答与原始事实进行比较。评分同时考虑正确性和实际可发现性——某条事实即使确实存在于代码中，如果需要内部知识才能找到，也仍值得记录。

Agent 置信度	Agent 回答正确？	结论
高	是	可考虑移除——仅当未来查找成本低于保留一条简短提示时
高	部分正确	保留仅缺失的细节
中	是	保留——虽能找到但埋藏较深；没有文档的 Agent 可能会漏掉它，或浪费时间搜索
中	部分正确	保留——未能可靠找到
低	—	保留——无法发现

6. 展示结果

显示汇总表：

| # | Fact | Confidence | Correct? | Verdict |
|---|------|-----------|----------|---------|
| 1 | Uses vitest for testing | HIGH | Yes | Remove |
| 2 | Branch naming: feature/JIRA-### | LOW | No | Keep |
| 3 | Auth middleware in src/middleware/auth.ts | MEDIUM | Yes | Keep (buried) |

报告证据、保留的约定、建议移除的内容、行数减少情况和查找成本。仅凭上下文节省量无法证明整体效率。

如果处于试运行模式： 到此为止。不要修改任何文件。

7. 重写文件（仅默认模式）

仅使用保留下来的事实重写每个指令文件。原则：

• 每一行都必须物有所值
• 不要保留只有一个项目符号的标题或章节（将其合并）
• 不要重复 CONTRIBUTING.md、README.md 或配置文件中的内容
• 自然地归类相关事实
• 尽可能保留原文件的语气和结构——这是精简，而不是从头改写

提示

• 对于包含多个指令文件的单体仓库，分别测试每个文件——某个事实可能在一个子项目的上下文中容易查到，在另一个子项目中却不容易
• 关于约定（命名规则、分支模式）的事实通常无法查到，即使 Git 历史中有示例也一样——请保留
• 关于身份验证机制的事实通常隐藏在中间件中——通常值得保留
• 关于已知陷阱的事实（例如，“使用 --forceExit”“不要模拟数据库”）几乎无法查到——请保留
• 关于文件位置的事实（“测试位于 tests/ 中”）通常可以轻松从目录结构中查到——适合考虑移除
• 如有疑问，请保留该事实。缺少指令（导致 Agent 操作错误）的代价高于多占用一些上下文令牌的代价