CLAUDE.md 中 5 个偷烧 token 的坏习惯

CLAUDE.md 会被加载进每一个 Claude Code session，从第一个 prompt 一直到最后一个。里面写了什么，团队里的每位工程师、每一次使用都会为它付费。一份 1200 个词、塞了三个“示例”的文件，单看并不显贵 —— 直到你把它乘以每天的 session 数、团队人数和每月周数。

下面是我们几乎在每次 CLAUDE.md 审计中都会看到的 5 个习惯。每一个都很机械、容易修，而且一旦找出来，就能省下实实在在的钱。

1. 一句话能讲清的行为，写成了多段示例

这是最常见的成本来源。工程师想让 Claude 遵守某个命名约定，为了保险，贴了一大段“比如，如果文件是……”的说明。模型从此会一直把这段内容带在上下文里，并在需要时复述出来。但它真正需要的指令，其实只有一行。

改前：

For naming React components, please use PascalCase. For example,
if you have a component that displays a user profile, you would
name the file UserProfile.tsx (not user-profile.tsx, userProfile.tsx,
or user_profile.tsx). Similarly, a component for a payment form
would be PaymentForm.tsx, and for an order summary it would be
OrderSummary.tsx. Make sure the file extension is .tsx and not .jsx.

改后：

- React components: PascalCase, `.tsx` extension (e.g. `UserProfile.tsx`).

你省下的是约 80 个 token × 每个 session。一个 6 人团队，如果每人每天跑 5 个 session，一周就是大约 12,000 个本可避免的加载 token。

通用规则是：如果你发现自己在 CLAUDE.md 里写“比如”，这就是一个坏味道。把示例压缩成更紧凑的规格，或者把示例移到代码库里真正相关的代码注释中 —— 那才是它应该待的地方。

2. 旧规则和新规则矛盾，却没有删掉旧规则

文件通常是靠不断添加长大的。六个月后，“永远用 tab” 这条规则躺在“用空格，绝不用 tab”上面 40 行，没人知道哪条是后加的。模型会挑一条执行 —— 通常是第一条 —— 团队则在反复纠正和逐渐放弃之间来回摇摆。

每一处矛盾都比没有规则更糟。模型会花 token 尝试调和两条相反的指令，然后在低置信度下选一条，结果是一半时候错，另一半也不够果断。

修法是编辑层面的，不是技术层面的。 每月一次，从头到尾把 CLAUDE.md 读出来。每遇到一条和前文冲突的规则，就删掉输掉的那条。大多数团队第一次 review 后，文件会缩短 30–40%。Claude 的输出通常在同一个 session 里就能明显改善。

3. 把个人偏好写进共享文件

工程师 A 喜欢简洁回复。工程师 B 觉得过于简洁的回复没有帮助。A 在项目 CLAUDE.md 里加了一句：“永远保持简洁，少写解释，优先给代码。”于是 B 在和 A 共享的项目上，也被迫收到自己并不想要的简洁回复。

个人风格偏好应该放在 ~/.claude/CLAUDE.md（每个用户自己的文件）里，而不是放进提交到 git 的项目文件。项目文件应该描述对 代码库 为真的事情：它的约定、约束、不明显的坑，而不是某个工程师喜欢别人怎么和他说话。

一个快速判断是：这条规则适用于昨天刚入职的新人吗？如果适用，放项目文件；如果只是“只有 Alice 喜欢这样”，放个人文件。大多数团队从没对共享文件做过这类审计，结果就是一份提交进仓库、由所有人一起付费、却装满某个工程师个人偏好的文件。

4. 老生常谈的套话

“写干净的代码。”“遵循最佳实践。”“加上合适的错误处理。”“保持函数简短。”这些句子看起来有帮助，也显得负责。但对模型来说，它们是零比特指令 —— 模型默认就会这么做 —— 只会给每个 session 增加 token，却不会改变行为。

经验法则： CLAUDE.md 里的每一行，都必须相对于一个训练良好的通用模型来说是 反常识的。如果模型本来就会这么做，这一行就是死重量。真正值得留下的指令，是新模型不会自己猜到的东西：你们具体使用的测试框架、某个具体的部署怪癖、那个任何人碰之前都必须叫醒 on-call 的函数。

一个有用的练习是：对每条规则问一句，“如果我删掉它，Claude 在我们的代码库里会做出什么不同？”如果诚实答案是“没什么不同”，就删掉。

5. 复述框架文档里已经写明的东西

这一条和第 4 条关系很近，但更具体：把语言和框架基础知识重新写一遍。“使用 async/await，不要用 callback。”“优先函数组件，不要用类组件。”“TypeScript 开了 strict mode，要遵守。”模型早就知道这些。你是在花 token 提醒它训练数据里已经包含的内容。

值得保留的是你的代码库偏离框架默认方式的地方，或者你们做过的非显而易见选择。比如：

有用（你代码库特有）：

- We use Zustand for global state, not Redux. There's a single `store/index.ts`;
  do not add another store file.
- HTTP errors from our API are handled by `lib/api/errors.ts`; do not
  swallow or rethrow them ad-hoc.

浪费 token（模型早就知道）：

- Use React hooks for state.
- Avoid global mutable variables.
- Use TypeScript's type system; do not use `any`.

第一版值得留下，因为没有哪个全新模型能猜到你们这些具体选择。第二版是在花钱教模型它已经会的东西。

合起来看：100 行目标

只要过一遍，大多数团队的 CLAUDE.md 都能缩短 30–60%，而且指导并不会减少 —— 通常还会更多，因为信噪比提高了。对一个典型代码库来说，合理目标是：100 行以内，分成 4–6 个小节，每一行都值得它占用的位置。

如果你想要第二双眼睛，这就是我们在本站做的 CLAUDE.md 审计：90 分钟、书面诊断、一份重写后的根文件，以及五个可复用模板。$299 个人版，$799 适用于 2–10 人团队。上面这五个习惯，占了我们目前所有审计中大约一半到四分之三的问题。

我们还没讲、但接下来应该讲的

还有几个模式值得单独成文：深度嵌套的 CLAUDE.md 文件（根目录 + 子目录 + 每个 package）以及它们如何合并、CLAUDE.md 和今年早些时候上线的新 memory 工具之间的关系，以及 AGENTS.md 在实践中和 CLAUDE.md 到底有什么不同 —— 最后这个我们已经写了：CLAUDE.md vs AGENTS.md —— Claude Code 到底读哪个。如果另外几个问题正好在困扰你，欢迎告诉我。