精简智能体规则文件的实用原则

每个认真使用 coding agent 的用户，都会让自己的 CLAUDE.md 走上同一条路。起初，它空空如也。每发生一次事故，就加上一行。某天你抬头一看，发现它已经有 500 行了。

接着，奇怪的事情发生了：你添加的规则越多，Agent 遵守的规则反而越少。你明明写得清清楚楚，它却置若罔闻。于是，你把同一条规则再写一遍，语气更强烈：加粗、加感叹号，再在前面加上「ALWAYS」。结果它还是不理。

这篇指南讨论的不是应该往 CLAUDE.md 里放什么，而是应该从中拿掉什么。简单来说：好的 CLAUDE.md 应该是一部简短的宪法，而不是一本冗长的规则手册。如果你的工具读取的是 AGENTS.md，同样的原则也适用。

为什么这个文件会越来越臃肿

过程总是一样的。Agent 犯了一个错误，你就加上一条规则。它又犯了另一个错误，你再加一条。

在当下，添加规则总显得合情合理：事故刚刚发生，而这句话可以防止它再次发生。问题在于，反方向的时机永远不会到来——你很难直观判断删除一条规则是否带来了改善，而保留所有规则造成的损害，却在缓慢累积。

因此，一份臃肿的 CLAUDE.md 并不意味着懒惰。只是所有激励都只指向了一个方向。

为什么越臃肿，效果越差

有三种效应会叠加在一起。

上下文是一项固定成本。每个 session、每一轮对话，你的 CLAUDE.md 都会随请求一起发送。文件有 500 行，就意味着每次请求都要为这 500 行付出成本。这不只是 token 费用的问题：它会预先占用原本应该用于处理实际任务的注意力。我在《Token Economics》中介绍过缓存和上下文成本背后的机制。

强调会随着使用范围扩大而被稀释。只有 5 条规则时，每条规则都有分量；有 50 条规则时，每条规则只剩下五十分之一的分量。什么都强调，就等于什么都没强调。在一份已经出现十次「ALWAYS」的文档里，第十一次只是装饰。

冲突会被悄无声息地解决。一本持续扩充数月的规则手册，必然会积累彼此冲突的条款。如果「始终先写测试」和「只做用户要求的最小改动」同时存在于一个文件中，模型不会报告冲突，而是默默舍弃其中一条——至于舍弃哪条，每天都可能不同。相当一部分「Agent 忽略了我的规则」的情况，其实正是由此造成的。

哪些该留，哪些该删

有三类内容值得保留。

• 无法从代码或文档中了解到的信息：为什么选择这种架构、没有记录在其他地方的团队习惯
• 无条件适用于每个 session 的要求：语气、语言、commit 约定
• 安全边界：任何难以撤销的操作，例如向 main 分支推送代码或接触生产环境

有四类内容应该移除。

• 任何可以从代码中读到的内容，例如目录导览、函数列表
• 任务早已结束的一次性指令
• 只在特定情况下才需要的流程（下一节会说明它们应该移到哪里）
• 模型本来就擅长的事情，例如「编写整洁的代码」

检验标准只有一句话：「如果删掉这一条，下一个 session 具体会在哪方面变差？」如果给不出明确答案，它就不该在这个文件里占位置。

被移除的内容应该放到哪里

一听到要删除规则，人们往往会觉得不放心。这些规则都是事故记录，真的能承受丢失它们的风险吗？

你并没有丢掉它们，只是给它们换了住处。如果 CLAUDE.md 是宪法，那么其他所有内容就是具体法规。把身份和原则留在宪法中，把具体条款移到只有需要时才会加载的地方。

情境化流程 → skills（命令）。「按照这个顺序部署」根本没有必要在每一轮对话中都随身携带。有人调用 /deploy 时再加载就足够了。

机械化重复工作 → hooks。「commit 前运行 lint」不是规则，而是自动化。无论模型是否记得，hook 都会触发。判断哪些事情可以交给记忆、哪些事情应该交给机器，是这里最关键的一步。

积累的知识 → memory。「上次这个 bug 是这样修复的」不是规则，而是一段记忆。无论使用文件还是专门的工具，都应该设置一个独立的层，用于搜索和检索这些内容。

项目事实 → 与代码放在一起的文档。架构说明应该放进 README 和 docs。Agent 会在需要时自行读取。

一旦建立起这种结构，每次有人想添加新规则时，都要先问一句：这是宪法，还是具体法规？答案几乎总是后者。

# CLAUDE.md (excerpt, before the diet, ~500 lines total)
- Always respond in Korean
- Helper functions live in src/utils. UI components in src/components,
  API clients in src/api, hooks in src/hooks... (40 lines of structure tour)
- ALWAYS run npm run lint before committing
- Deployment MUST follow: 1) test 2) build 3) staging check 4) ...
- Do not edit config.ts directly (see incident, 2026-05-12)
- Write good commit messages
- ...

精简之后则是这样（这是完整文件，不是节选）：

# CLAUDE.md (after the diet, complete)

## Identity
Speak Korean, like a colleague. Conclusions first.

## Boundaries
- Never push directly to main. Ask before committing.
- Production config files are read-only.

## Delegation
- Deployment: /deploy skill
- Pre-commit lint: handled by a hook (not entrusted to model memory)
- Project history and past incidents: search memory

缺少的那 490 行去了哪里，正是这篇指南想要说明的核心。目录导览移到了文档，部署步骤移到了 skill，lint 交给了 hook，事故记录则进入了 memory。没有任何内容丢失，每样东西都回到了它该在的位置。

日常维护方法

发生事故时，把处理顺序倒过来。不要先想「加一条规则吧」，而要先问「这应该放在哪里」——skill、hook，还是 memory？CLAUDE.md 应该是最后的选择。

定期精简。回顾最近十个 session，找出一次都没有触发过的规则。任何无法通过检验标准的内容，都应该删除。

设置上限。我的标准是一屏。文件一旦长到需要滚动，就说明有些内容应该移出去了。

打开你的 CLAUDE.md，检查以下五件事。

• 是否每一行在被删除后，都会让下一个 session 明确变差？
• 是否存在代码本身就能回答的内容？
• 「ALWAYS」是否出现了三次或更多？
• 是否有互相冲突的条款？
• 它能否在一屏内完整显示？

如需采取进一步行动，你可以考虑屏蔽此人和／或举报滥用行为。