2026 年 5 月 25 日花了一天调研要不要做一个工具，最后没写代码。把过程记下来。
最近用 Claude Code、Codex、Cursor 这些工具的时候发现，仓库根目录的 AGENTS.md、CLAUDE.md、.cursor/rules 这类指令文件常常和仓库实际状态对不上。比如 AGENTS.md 写 npm test，但 package.json 里实际是 pnpm vitest run；或者文件里引用了一个已经被删掉的目录。我想做一个 CLI，叫 driftdoc，跑一下就能列出这些"漂移"。
完整的实施方案在 IMPLEMENTATION.md 里。包括规则集、四周路线、仓库结构。
写完方案之后没立刻动手。先想了一个 go/no-go 标准：
如果在 5 个真实仓库里凑不出中位 2 条以上的漂移，那这个工具的需求假设可能站不住。先停下来。
然后用 gh search code 'path:AGENTS.md' 拉了一批候选，按以下条件筛了 6 个：
- stars > 50
- AGENTS.md 最后修改 > 30 天
- 仓库近 30 天有 commit
- 排除模板、收藏夹
挨个手工对照 AGENTS.md 和 package.json / Cargo.toml / pyproject.toml / 目录结构。结果：
| 仓库 | 语言 | Stars | AGENTS.md 滞后 | 漂移条数 |
|---|---|---|---|---|
| DataDog/lading | Rust | 97 | 117 天 | 0 |
| Brendonovich/MacroGraph | TypeScript | 307 | 158 天 | 1 |
| econ-ark/HARK | Python | 385 | 87 天 | 0 |
| xoofx/Tomlyn | C# | 563 | 107 天 | 1 |
| maxcountryman/underway | Rust | 164 | 100 天 | 0 |
| Pirate-Weather/pirate-weather-code | Python | 62 | 332 天 | 0 |
6 个仓库一共 2 条漂移，中位数 0。详细标注见 fixtures/ground-truth.json。
数据没达标，按预设标准应该停。但停下来之后再想，发现真正的问题不是"没需求"，是我的验证方式只能看到一类很窄的漂移。
问题一：样本选偏了。 stars > 50 的项目维护者本来就更勤快，也更可能顺手维护 AGENTS.md。再叠加一层：当前在公开仓库写 AGENTS.md 的人本身就是早期采用者，他们对这类文件的态度比平均开发者高一截。我相当于挑成绩好的学生的作业看错别字。
问题二：漏掉了最痛的那种漂移。 我设计的规则全在抓命令、路径、glob、字面冲突这种能机器验证的事实。但 AGENTS.md 真正容易过期、过期了又最坑人的是另一类——
- "项目暂时不用数据库" → 现在用了
- "MVP 阶段" → 已经 v2 了
- "不要改 API 层" → 架构早改了
- "我们的开发习惯是 X" → 但某个 PR 已经推翻了
- "暂不支持多用户" → 上周加进去了
这些是叙事漂移，不是事实漂移。我的所有规则一条都抓不到这种。即使 AGENTS.md 整段都已经过期，只要里面没引用具体路径或命令，我的工具就什么都不会说。
所以 6 个仓库 median = 0 这个数据其实只说明一件事：用我那套方法验证不到需求。不能说明需求不存在。
把这两个问题想清楚之后，我的判断也变了：
- 需求大概率是真的，但需要重做样本（中小型项目、AGENTS.md 半年没动的、有大量 commit 累积的）+ 重做标注（人工读 AGENTS.md 散文段落，找声明，再去对照代码）。
- 真要做能抓叙事漂移的工具，它就不再是一个 CLI lint，更像是一个本地跑的小 agent：读 AGENTS.md 散文 → 抽出每条声明 → 去 repo 里找证据 → 判断声明是否仍然成立。形态更重，对 LLM 依赖更大。
- 这种形态和 Claude Code 自己的
/init距离很近。/init已经会读仓库生成 CLAUDE.md，反向（用仓库验证 CLAUDE.md）官方迟早会做。
综合下来，这个项目暂时搁置。不是数据驳回了它，是我意识到自己的初版理解太浅，验证方法和工具设计都跟着错。这种情况下继续写代码反而是浪费。
为了不让一天白跑，记一下读官方文档时确认的几件事：
- Claude Code 项目根
CLAUDE.md在/compact之后会自动重读，只有子目录里的 CLAUDE.md 不会。我之前看到的社区抱怨大概率是后一种情况。 - Claude Code 原生支持
@AGENTS.md一行 import 语法，可以让 CLAUDE.md 直接引用 AGENTS.md 内容，不用复制。 .claude/rules/*.md支持 frontmatter 里的paths:glob，按需加载。这是 v2.1.59 才有的，多数文档还没更新到这一步。- agents.md 官方站点确认 60k+ 项目采用了这个格式，由 Agentic AI Foundation (Linux Foundation) 维护。
调研之后整理的：
| 工具 | Stars | 大致做什么 |
|---|---|---|
| intellectronica/ruler | 2712 | 单源分发规则到各 agent 配置 |
| BayramAnnakov/claude-reflect | 1042 | 从 session 学习写回 CLAUDE.md |
| prompt-security/clawsec | 1006 | OpenClaw 生态的 drift detection |
| sno-ai/mda | 563 | 自定义 DSL 编译到多目标 |
| nedcodes-ok/rule-porter | 8 | 多格式双向转换 |
| nedcodes-ok/cursor-doctor | 8 | Cursor rules linter |
| ItsHege/agents-md-doctor | 0 | AGENTS.md drift checker（和我想做的最像） |
IMPLEMENTATION.md：当时写的实施方案，结构和措辞比较正式，留作记录。fixtures/ground-truth.json：6 个 fixture 仓库的人工标注结果。POST.md：把这次过程写成了一篇短文。
MIT