文档成了垃圾堆——CLAUDE.md是怎么失控的

你有没有过这种经历？

新项目刚启动，CLAUDE.md 里就写了几行注意事项：项目叫啥、核心逻辑在哪、认证模块有个坑要注意。简单明了，挺好。

然后？然后就刹不住车了。

几个月后再打开，嚯，这哪是文档啊，简直是灾难片现场。互相矛盾的指令、过时的提醒、还有一堆不知道谁加的附录。没人真正看懂里面写了啥，但也没人敢删。

好消息是，这不是你一个人的问题。

坏消息是，这是所有人和AI助手协作的通病。

那个让人头皮发麻的数据

研究人员分析了247,694条指令在1,867个仓库里的生命周期，发现了一个让人笑不出来的规律：

AI指令文件不只是增长——它是无限制地疯长。

平均每个commit，文件就会多出4.9条指令。从不减少，只增不减。运营期间整体增长幅度高达226%。

更绝的是：一条指令存在越久，就越不可能被删掉。

数据显示，每经历一个commit，指令被删除的概率就会下降一点（log-hazard -0.032）。换句话说，时间一长，文档里的内容就自动获得了"免死金牌"。

不是大家不想清理，是真不知道怎么删——万一把重要的东西删了呢？

为什么越攒越多？

研究者给这种现象起了个名字：灾难性记忆（catastrophic remembering）。

听着挺高大上，其实道理很简单。

加一条指令，成本有多高？

几乎为零。发现问题，写下来，搞定。下一秒就能看到效果。

删一条指令呢？

那就复杂了。你得先搞清楚这条指令在哪些场景下可能被用到，得理解它和现有其他指令的互动关系，还得确保删掉之后不会在哪埋个雷。

研究者算了算，这个认知成本大概是 O(2^|D|)——指令越多，成本指数级飙升。

所以结论就是：开发者选择了放弃。

反正加东西又快又安全，删东西又难又危险。那就只加不删呗。

.comments()：被忽视的救命稻草

接下来这段研究，是我最想让大家记住的部分。

解决方案既不是什么高级的prompt技巧，也不是什么更智能的模型。就是一样从编程诞生之初就存在的东西——注释。

研究者干了件挺有意思的事：他们把IFEval这个标准测试给"反过来"用了，创建了一套已知最优答案的场景。然后给不同版本的prompt加上带有推理过程的注释。

结果？

指令的无序增长从 +211.3% 骤降到 +1.4%。

减少了99.3%。

但这不是最让人震惊的。

加了注释之后，实际任务中的指令遵循能力提升了23.1%。

也就是说，注释不只是帮你管好文档——它真的让AI理解得更准确、做得更好。

注释不是乱堆的废话，它是支撑整个结构的承重墙。

为什么现在这事儿特别重要？

我们正在经历一场根本性的转变：什么叫"代码"？

研究者提了个扎心的问题："如果英语成了新的代码，为什么我们不给它写注释呢？"

想一下程序员社区干了多少年的事：代码要加注释。注释解释"为什么这么做"，不只是"做了什么"。注释记录了意图、边界情况、和那些只有老员工才知道的潜规则。

这些东西，光看代码是看不出来的。

但到了AI时代，我们把natural language instruction当成例外来处理了。写出来全是命令句：要做这个、别做那个、记得检查X。理由呢？没有。推理过程呢？不存在的。

结果呢？就是那些越来越膨胀、越来越没人看得懂的CLAUDE.md。

怎么办？

如果你手里有CLAUDE.md或类似的AI指令文件，研究给了三条建议：

1. 给你写的指令加注释，就像给代码加注释一样

每条规则背后的原因是什么？什么情况下这条规则可能会失效？当时为什么这么决定？把这些写下来。

2. 定期重构，别只会追加

写文档不是发朋友圈——不是越多越好。隔一段时间整个重写一遍，是为数不多能真正刹住增长的方法。

3. 把AI助手当新人来对待

你会给刚入职的同事丢一个400行的规则清单让他自己悟吗？AI助手也一样。它值得同样的清晰和尊重。

最后

现在很多项目的轨迹是这样的：开头用心写，后来懒得管，最后完全失控。

但解决方案可能比想象中简单得多。

写注释的时候，想象六个月后有人——或者有AI——会读到这段话。不是现在急着要答案的那个，而是需要理解整个上下文的那一个。

注释不是杂物，是理解的架构。

就这么回事。