我从零重写了我的 CLAUDE.md
这是一篇第一人称的 CLAUDE.md 重写记录。我原来有一份 612 行的文件，已经往里加东西十四个月了。过去三个月，agent 的行为一直在悄悄变差：追问更多，忽略规则更多，也更偏离我自己手写时会做的方式。我最后决定，唯一修法就是删掉这个文件，从空白开始。下面是发生了什么。
为什么我没有直接编辑它
这个文件已经变成一层一层的化石。项目第一个月留下的规则，那时我们还在选 stack。迁到 TypeScript 时留下的规则。事故复盘后加的规则，因为有人搞坏过东西，希望 CLAUDE.md 里加一句以后别再发生。一次从未落地的 refactor 留下的规则。还有我在烦躁时加的规则，我自己也知道那更像 rant，不像指令。
我试过编辑两次。两次都让它更糟。我加了“例外” clauses，结果和前面的规则冲突。或者把一条模糊规则改成稍微不那么模糊，但依然没有任何可证伪内容的规则。这个文件已经和自己纠缠太深了，拉一根线，十根线都会松。编辑它明显不如删掉它。
空白文件
rm CLAUDE.md && touch CLAUDE.md 是少数让人很爽的 git-adjacent command。repo 在会话开始时有了一块干净白板。agent，在这个例子里是 Claude Code，会读到一个空文件，然后按 training-data defaults 工作。这意味着接下来一个会话里，agent 做的每个决定都是候选信号：如果它做了我不想要的事，我就有一条真实规则要加；如果它做了我想要的事，那这条规则可能已经是隐含的，不需要写。
我给自己一个约束：我不手写 CLAUDE.md。我只在接下来两周，根据具体 agent 行为来写。重写文件里的每一行，都必须对应一个能证明它必要的 agent 动作。没有愿望规则。没有 “best practice” 规则。只有“agent 做了 X，而我不想要 X”的规则。
两周观察到的行为
我在一个 scratch file 里持续记日志。每次 agent 做了和我不同的事，我就记下来。第一周结束时有三十二条；第二周结束时有五十一条。它们大致分成六类。
流程违规：agent 直接 push 到 main，或跳过 hook，或 amend 已发布的 commit。八条。它们变成第一节：不可谈判项。
stack-specific drift：agent 去拿一个项目已经明确迁走的 library 或 pattern。十条。它们变成语言和风格规则。
对操作环境无感：agent 对 dev environment 做了错误假设（path、command、service availability）。十二条。它们变成 operational notes。
调查深度判断错误：我会希望先多查一点时，agent 直接行动；或者反过来。六条。它们变成 principles。
沟通风格：agent 解释过多或过少，用正式英文而我想要简短，或者我想要直接时它在 hedge。九条。它们大多变成 style section 里的一段话。
对其他 tooling 的错误或过期假设：agent 引用了不存在的 CI 或 hook 功能，或者以为某个 CI step 在跑，其实没有。六条。它们变成 enforcement rules，也暴露出三个真实 harness 缺口，我在写规则前先补掉了。
从日志起草
两周后，我坐下来把日志变成 CLAUDE.md。过程几乎是机械的：每组 notes 变成 3 到 8 条规则，每条规则都必须指向日志里的具体 note，每条规则都必须可证伪。第一稿 89 行。
然后我用 AgentLint 跑了一遍。linter 报了六个问题：三条模糊规则，两个缺少阈值，一个过期 tooling reference（我凭肌肉记忆写了 pnpm，但项目用的是 bun）。二十分钟 edit 后，文件通过。
重写后的 CLAUDE.md 是 102 行。原来是 612 行。新文件承重更多，不是更少，因为每一行都连着我亲眼看见 agent 在没有这行时做错的具体行为。
agent 行为发生了什么变化
commit 新 CLAUDE.md 后的第一个会话里，agent 的感觉变得不一样，这点我没预料到。对于重写覆盖到的决策，它问的澄清问题更少了：新 test file 放哪、命名怎么用、能不能直接 push。对于我刻意没写进规则的决策，它问得更认真了：这个新 feature 到底该做什么，用户期待是什么，哪些 edge cases 重要。agent 不再把预算浪费在已经决定过的问题上，而是把预算用在真的需要我参与的问题上。
接下来两周，“agent 做了 X，而我不想要 X”的 notes，从每天大约四条降到每天不到一条。剩下的 notes 要么是真正的新模式（慢慢变成新规则），要么是一次性怪事，不值得写规则。文件最后稳定在大约 110 行。
下次我会怎么做得不同
回头看，有三件事。
我应该更早开始记日志。 我等到删文件才开始。其实那两周观察可以在臃肿文件还在时就做；我会学到同样的东西，空白文件阶段可以压缩成一个周末。删除很爽，但学习发生在观察里，不发生在删除里。
我应该把 operational notes 再砍狠一点。 我放进了一些只遇到过一次的规则。如果观察更多周，它们会被删掉。经验法则：一条规则至少要在日志里出现两次，才配占一行。
我应该明确给 principles section 打标签。 重写时，我把 principles 当承重规则。它们确实是，但它们的老化方式和 process rules 不一样。过期的 principle 会在很久之后看起来仍然合理，而过期的 path command 会明显坏掉。我现在会给 principles 标 “last reviewed” 日期，并且每季度复查。
重写是容易的部分
删除和重写很爽。难的是阻止同样的十四个月堆积再次发生。我现在的纪律是：每次 edit CLAUDE.md，都必须带一个同等重量的删除，或者一条清楚的日志记录证明为什么要加。CLAUDE.md 不能在日常工作里自然长胖。它可以在观察到新模式时变长，也必须在旧模式不重要时变短。
如果你的 CLAUDE.md 超过 300 行，而且六个月以上没认真重写过，可以考虑做同样练习。两周观察，一个周末起草，AgentLint 做最后清扫。更短、更锋利的文件几乎总比又长又漂的文件更好。agent 会在一周内告诉你这次重写有没有用。如果有，它会是你这个季度做过杠杆最高的改动之一。