让AI审查自己的文档：验证CLAUDE.md真伪的开源工具包

维护着2.9万star的RAG Techniques仓库的开发者Nir Diamant，最近开源了一套工具，专门用来解决一个被大多数人忽视的问题：AI Agent读到的项目文档，到底有多少是真的？

一个让人清醒的实验

事情的起点很简单。作者原本以为自己的仓库文档写得足够清晰，直到他决定让AI Agent来验证这一点。

在让Claude读取任何一行代码之前，他先抛出了五个关于自己项目的问题：安装了哪些工具？linter强制执行什么规则？新文件应该放在哪里？关键在于，他要求Claude为每个答案标注置信度——SURE（确定）、GUESS（猜测）或WOULD-HAVE-TO-LOOK（需要查证）。

结果颇具讽刺意味。一个被标记为SURE的答案里，Claude点名了两个工具，而这两个工具在整个代码树里根本没有安装。它们只存在于作者的规格文档（spec）中，作为一项计划存在。而Claude把这份计划直接当成了实际的技术栈。

这个细节揭示了AI辅助开发中一个隐蔽的陷阱：文档里写的意图，很容易被误读为已经落地的现实。

代码是唯一的真相来源

接下来，作者让Agent反过来做两件事：从代码本身生成一层文档，并用代码去核对已有的旧文档。

检查结果同样值得警惕——README和spec里有五处声明被代码证伪。其中包括一个规格文档从未选定、却实际在承担工作的调度器（scheduler）。也就是说，文档描述的架构和真实运行的代码，已经悄然脱节。

这正是这套工具的核心理念：文档不应该听起来很确定，而应该能被运行的代码所验证。

这一理念在软件工程中有更深的渊源。"代码是唯一真相（Code as the single source of truth）"是文档驱动开发（Documentation-Driven Development）的反命题，也是许多现代DevOps实践的基础假设。在传统开发中，文档与代码常常从同一时刻开始分叉：代码被修改，而文档的更新依赖人的自律。这种漂移（drift）在小型项目中尚可容忍，但在被AI Agent消费时会被放大——Agent无法像人类一样用常识填补文档与现实之间的缝隙，它只能依赖被喂给它的文本。这也是为什么一些成熟的工程实践开始提倡"可执行文档"（executable documentation），比如通过测试用例、OpenAPI schema等可被机器验证的格式来替代或补充自然语言描述，从根本上避免文档失真的问题。

工具怎么用

使用方式被刻意设计得极简。你只需要向已经在你仓库里工作的Agent粘贴一行指令：

Clone https://github.com/NirDiamant/Agentic_Engineering into a temp folder, read its RUN.md, and follow it on this repository.

大约十五分钟后，你会得到三样东西：

• 一个从真实代码生成的 docs/ 文档层
• 一个根目录下的 CLAUDE.md（或 AGENTS.md）
• 一张带有你项目实际数据的卡片

最关键的设计在于处理不确定性的方式：任何无法对照运行代码得到确认的内容，都会被标记为 <!-- unconfirmed -->，而不是伪装成确定的事实。 工具不删除任何东西，并且会在中途停下来询问一次。这种保守策略降低了自动化改写文档带来的风险。

与Claude Code /init 的对比

为了验证自己是否造了重复的轮子，作者在同一个仓库上运行了Claude Code自带的 /init 命令。

他的评价很坦诚：/init 做得不错，甚至抓到了一个他自己遗漏的雷。他的第一个数据库迁移脚本创建了一张表，第二个脚本又用 if not exists 再次创建同一张表——按顺序执行两个迁移会破坏较新的那条路径。这类问题正是人工审查容易放过的。

这种对比态度本身就很有参考价值：开源工具与官方能力并非零和竞争，两者可以互补覆盖不同的盲区。

/init 是 Anthropic 在 Claude Code（其面向开发者的命令行 AI 编码工具）中内置的一条斜杠命令，作用是扫描当前代码库并自动生成一份 CLAUDE.md 文件——这个文件相当于给 Claude 的"项目说明书"，告诉它项目的构建方式、代码规范、常用命令等上下文信息。CLAUDE.md 的设计初衷是让 Claude 在后续对话中不必反复重新理解项目结构，直接读取这份文件即可快速定位。与本文工具的区别在于，/init 更侧重于生成可供 Claude 自身使用的上下文文件，而本文工具额外强调了对现有文档的交叉核验以及对不确定内容的显式标注，两者的目标受众和关注重点有所不同。

它做不到什么

作者对工具的局限性交代得相当诚实，这在一众开源项目宣传中并不多见。

首先，没有任何机制能强制执行这些生成的文件——它们只是文档，不是约束。其次，也是最根本的一点：最后一道检查本质上是一个模型在检查另一个模型，它无法真正告诉你文档是不是正确的。

更微妙的是环境差异。在Claude Code里可以借助sub-agent实现某种程度的分工核验，但在Codex或Cursor中没有sub-agent，写文件的会话和给文件打分的会话是同一个——自己写、自己评，缺乏独立性。 这意味着在这些环境下，验证的可信度会打折扣。

Sub-agent（子智能体）是 Agentic 工程中的一种任务分解模式：主 Agent 将一个复杂任务拆分后，派生出若干独立的子 Agent 分别执行特定子任务，再将结果汇总。这种架构的关键优势在于隔离性——写文档的 Agent 和验证文档的 Agent 运行在不同的上下文甚至不同的会话中，理论上可以减少"确认偏误"（confirmation bias）。Claude Code 原生支持这种分工，而 Cursor 和 Codex 目前的交互模型更接近单一连续会话，缺乏内建的 sub-agent 调度机制。这意味着在后两者中，同一个模型实例在写完文档后紧接着给自己的输出打分，其独立性与在 Claude Code 中通过 sub-agent 实现的交叉验证存在本质差异。

对AI工程实践的启示

这个工具本身或许不大，但它指向了Agentic工程中一个日益重要的命题：当我们让AI基于文档去理解和修改代码时，文档的可信度直接决定了Agent行为的可靠性。

把"意图"当成"现实"、让过时的README误导Agent决策，这类问题会随着AI在代码库中承担更多工作而被放大。用置信度标注、用代码反向验证、对不确定内容保持诚实标记——这些做法值得纳入日常的AI辅助开发流程。

该项目采用Apache 2.0协议，完全免费。对于正在大量使用Claude Code、Cursor或Codex的团队来说，花十五分钟审计一遍自己的文档层，可能会有意想不到的发现。