rules-doctor 0.3：检查你的 CLAUDE.md 是否在"欺骗"AI 代理

AI 编程代理越来越依赖 CLAUDE.md、.cursorrules、AGENTS.md 这类规则文件来约束自己的行为。但一个被忽视的问题是：这些规则文件本身是否可靠？开源工具 rules-doctor 的 0.3 版本给出了一个尖锐的追问——你的规则文件真的值得被加载吗？

从「能加载」到「值得加载」

rules-doctor 的演进路线很清晰。v0.1 解决的是最基础的问题：规则文件能否被正确加载，比如检测失效的 @import 引用、被遮蔽（shadowed）的 AGENTS.md、以及指令臃肿（instruction bloat）；v0.2 强化了导入分析能力。而到了 v0.3.0，工具的关注点从「技术上能否加载」上升到了「内容上是否有价值」这一更难回答的层面。

这个转变背后有真实的社区痛点支撑。开发者社区反复出现的两类抱怨最为突出：一是范围蔓延（scope creep）——代理擅自修改了没人让它碰的文件；二是规则文件不可靠——写在 CLAUDE.md 或 .cursorrules 里的指令，在任务执行到一半时被悄悄忽略。Hacker News 上一篇获得 219 分的热帖《Agents don't need memory, they need documentation》从另一个角度印证了这一点：文档即系统，那么文档就必须值得信赖。

被遮蔽的 AGENTS.md 指的是当多个同名规则文件分布在不同目录层级时，子目录中的文件可能因路径解析顺序而覆盖或屏蔽上层文件，导致开发者预期生效的规则实际上从未被读取。指令臃肿（instruction bloat） 则描述规则文件随时间不断堆积、缺乏清理，最终超出模型上下文窗口的有效处理范围，或因内容过长而导致模型对靠后指令的遵从度显著下降——这是 LLM「注意力稀释」现象在规则层面的直接体现。这两类问题都属于「技术可加载但实际失效」的典型场景，构成了 rules-doctor 早期版本的核心关注点。

v0.3 到底检查什么

rules-doctor 0.3 引入了四项针对规则「质量」而非「语法」的检查：

检查项	严重级别	捕捉的问题
CONTRADICTORY_RULES	error	同一文件中出现「总是运行测试套件」与「永远不要运行测试套件」这类矛盾指令。模型面对冲突时会任选其一，并在任务中途悄悄丢弃另一条。
SCOPE_BOUNDARY_MISSING	warning	文件从未声明代理可以触碰哪些文件/目录。没有明确的作用域，「别越界」就不是代理能遵守的规则——这是范围蔓延风险的静态代理指标。
VAGUE_DIRECTIVE	warning	含糊措辞，如「视需要」「记得」「在适当时候」。读起来像建议而非规则，实际无法执行，往往是任务中途最先被丢弃的内容。
ADR_MISSING	warning	非简单项目却缺少架构决策记录（ADR）。某次会话做出的决策，会被下一次会话重新争论甚至悄悄推翻。

使用方式非常简单，一行 pip 安装、一行命令即可运行：

pip install rules-doctor
rules-doctor ~/my-project

工具的输出也相当直白，会直接指出矛盾所在并给出修复建议：

[ERROR] CONTRADICTORY_RULES -- CLAUDE.md
  Line 3 contradicts line 4 in CLAUDE.md: 'Always run the full test
  suite after changing code.' vs 'Never run the full test suite --
  it is too slow.'...
  Fix: Decide which rule wins, then delete or rewrite the loser.

这种设计思路值得玩味：矛盾规则被定为 error 级，因为它直接导致不确定行为；而缺少作用域、含糊措辞、缺少 ADR 则是 warning 级，属于「迟早会出问题」的隐患。

架构决策记录（ADR，Architecture Decision Record） 是软件工程中记录重要技术决策及其背景、权衡与结论的结构化文档，通常以 Markdown 文件形式存储在代码库中（如 docs/decisions/ 目录）。在 AI 代理工作流中，ADR 的缺失会引发一个特殊问题：每次新会话启动时，代理不具备跨会话的持久记忆，如果规则文件中没有记录「为什么选择方案 A 而非方案 B」，代理可能在后续任务中重新评估并悄然推翻上一次会话已经确定的架构选择。将 ADR 纳入规则文件质量检查，本质上是把「决策的可追溯性」提升为代理可靠性的前置条件。

成本与质量：两个互补的维度

作者特意区分了 rules-doctor 与另一个思路相近的工具 claude-code-guardrails。后者的 /cleanup-docs 技能从成本角度审计文档：测量 → 验证 → 削减，以字节数汇报，告诉你的规则有多「贵」（即消耗多少上下文）。

rules-doctor 关注的则是质量。作者的论点很犀利：一个廉价却自相矛盾、从不声明作用域、满是含糊措辞的规则文件，照样会在任务中途坑你一把——只不过它「失败得很便宜」。两者是互补关系：先用 rules-doctor 让规则变得可信，再用成本审计让规则变得廉价。

这个区分点出了一个常被混淆的问题。很多团队优化 CLAUDE.md 时只盯着 token 消耗，努力把文件压缩得更短，却忽略了压缩本身并不能解决规则相互冲突或指令含糊的根本问题。短而错，比长而对更危险。

claude-code-guardrails 所代表的成本视角，针对的是 LLM 调用中上下文窗口（context window）的实际消耗。每次代理被调用时，规则文件的全部内容都会作为系统提示或上下文注入，直接增加每次请求的 token 用量，进而影响延迟与费用。对于频繁调用的 CI/CD 流水线或长会话任务，臃肿的规则文件会产生可观的累积成本。这正是「成本审计」工具存在的意义——但正如文章指出的，压缩 token 数量与提升指令质量是两个正交的目标，需要分别对待。

诚实的局限性

作者对工具的边界保持了难得的坦诚。这些检查本质上是文本启发式规则，而非模型。矛盾检测通过匹配同一主题下极性相反的指令来工作，因此会漏掉更微妙的冲突，也可能在引用示例时误报；作用域检测只识别显式的作用域描述语言。

当某个检查结果看起来可疑时，作者建议对照真实的 Claude Code 行为来验证——用 --debug 参数可以查看实际加载了哪些内容。这种「别全信我的工具，去验证真相」的态度，反而增强了工具的可信度。

从工程角度看，rules-doctor 还有两个加分项：零依赖、纯标准库实现，以及 MIT 许可证。这意味着它可以几乎无成本地集成进任何 CI 流程，作为规则文件的质量门禁。

对 AI 协作工作流的启示

rules-doctor 的价值不止于一个小工具，它折射出 AI 辅助编程走向成熟过程中的一个关键认知：规则文件正在成为需要被工程化管理的一等公民。当我们把越来越多的行为约束写进 CLAUDE.md，这些文件就从「随手写的笔记」变成了「必须保证正确性的配置」。

传统软件工程早有 linter、静态分析、CI 门禁来保证代码质量，而针对 AI 规则文件的质量保证工具才刚刚起步。rules-doctor 把 linting 的思路迁移到了 prompt/规则层面——矛盾检测、作用域声明、措辞明确性，这些检查项与代码审查中的常见问题一一对应。随着 agentic 工作流普及，这类「规则 linter」很可能会成为标准配置。

正如作者所说：在你自己的 CLAUDE.md 上跑一遍——你可能不会喜欢它发现的东西。