你的 CLAUDE.md 写得越认真，Claude 可能干得越差

Anthropic 官方博客说，他们把 Claude Code 的系统提示词删掉了 80% 以上，跑编码评测，没有可测量的性能损失。

删掉 80%。不是重写，不是优化，是删。

我第一反应是不信。那份提示词里每一句话都是一个团队打磨出来的，删八成还没事，那之前那八成算什么？

然后我打开自己仓库的 CLAUDE.md，6.6 KB，写得工工整整，又打开我最长的那个 Skill，9.1 KB，规则条条分明。看了一会儿我开始怀疑，这里面有一部分东西根本不是在帮 Claude。它们在拦着它。

---

unhobbling

原文用了个词，unhobbling。hobble 是给马腿绑绳，让它跑不快也跑不远。

Anthropic 自己的复盘是：他们把 Claude Code 约束得太狠了，而这个过度约束同时来自三个地方——系统提示词、CLAUDE.md、Skills。

他们翻内部的使用记录，发现一次请求里同时飘着这样两条指令：

"leave documentation as appropriate"（该写文档就写）

"DO NOT add comments"（绝对不要加注释）

一条说该写就写，一条说绝对别写，用户的原始需求里可能还有第三种倾向。Claude 当然还是能猜出你到底想要啥，但它得先花一轮思考去调解这三方，才能开始干活。

我之前那篇《最强的模型，可能正在悄悄用坏你的工具》里说过类似的事：你上下文里塞的每一条规则，都不是免费的。

更要命的是第二层原因。

那些约束当初是对的。早期的 Claude 如果没人拦着，注释会写得又长又错，文件会删得毫无顾忌。所以团队宁可写死"永远不许写多行注释"，接受它在某些场景下判断错误的代价，也要先堵住最坏情况。

护栏是按当年的车速修的。车换代了，护栏没动。

---

六条过期的"最佳实践"

原文列了一张 Then / Now 对照表。我按自己的理解翻成人话，这张表建议你对着自己的 CLAUDE.md 逐条打勾：

过去	现在	我的理解
给 Claude 定规则	让 Claude 用判断力	硬规则换成风格锚点
给 Claude 举例子	设计好接口	例子会变成笼子
全部前置塞满	渐进式披露	该用的时候再加载
重要的事说三遍	工具描述里说一次	别在系统提示词里复读
用 CLAUDE.md 当记忆	用自动记忆	记忆不该跟规则挤一个文件
简洁的 spec	高保真的引用	spec 可以是测试、是代码、是 HTML

其中三条，对我们这种一个人干活的人杀伤力最大。

规则换成锚点

老的系统提示词是这么写的：

代码里：默认不写注释。永远不要写多段式 docstring 或多行注释块——最多一行短的。

新的系统提示词，同一件事，一句话：

写出读起来像周围代码的代码：匹配它的注释密度、命名和惯用法。

前一条是外部命令，它假设自己知道所有场景下的正确答案。它不知道。遇上那段确实需要大段说明的复杂逻辑，它就是错的。后一条不告诉模型写几行，它告诉模型去看手边那份代码怎么写的，就那么写。

整篇文章我觉得最值钱的是这个转向：别在 CLAUDE.md 里描述答案，指一个能算出答案的地方给它。你的项目风格本来就写在代码里了，你何必再手抄一遍，还抄得半对半错。

给例子等于给笼子

这条最反直觉。过去教工具调用，第一铁律就是"多给几个 few-shot 例子"。现在的结论反过来了：给例子会把模型框死在某个探索空间里。

替代方案是去设计你的接口。原文举的是 Todo 工具：你不用写"下面是一个正确调用的示范"，只要把 status 定义成 pending | in_progress | completed 这么一个枚举，模型立刻就懂该怎么用了；再加一句"同时只保留一项 in_progress"，行为就定死了。

换成我们自己的活儿：花在写示范上的时间，挪去把参数名、枚举值、文件名起得更准。一个叫 verify-log-hygiene 的 Skill，比一个叫 check3 然后配三段示范的 Skill，好用得多。

渐进式披露不只是给 Skill 用的

Claude Code 把 code review、verification 这些"不总需要但需要时至关重要"的大段内容，从系统提示词里拆出去，做成了按需调用的 Skill。工具也一样——有些工具是 deferred loading，得先用 ToolSearch 搜出完整定义才能用，没被用到时它一个 token 都不占。

原文点破的那个误区，我上周还在犯：

一个常见的误区是：你想把每一条可能用得上的实践都塞进这些文件，因为你觉得 Claude 否则就找不到它。

你要的是一棵能在正确时机被加载的文件树，不是一个什么都装的仓库。

---

量一下我自己的仓库

讲道理容易。我直接量了一下自己的 AssistantBrain：

• CLAUDE.md：6.6 KB
• 最长的 Skill（translate）：9.1 KB
• 第二长（briefing）：4.1 KB

按上面的标准审了一遍，三处硬伤。

最大的一处是将近一半篇幅在描述文件系统。我的 CLAUDE.md 里画了一棵完整的目录树，从 raw/articles/ 到 output/exports/，每个目录后面还贴心地写了注释。可 Claude 一条 ls 就知道这些。原文那句说得很直接：避免陈述那些 Claude 看一眼文件系统或仓库就知道的显而易见的事。这棵树该删，省下的篇幅应该全部花在坑上——比如"所有类型定义只准放在这一个文件里，别处不许有"，这种你不说它就一定踩。

第二处，9.1 KB 的 Skill 显然没做渐进式披露。translate 该拆成一个薄薄的入口加几个按需加载的子文件，而不是一次性糊进上下文。

第三处，规则和记忆混住了。我的 CLAUDE.md 里有几条其实是记忆性质的偏好，现在 Claude 有自动记忆了，这些东西不该继续占着规则文件的位置。

三处都是我"写得很认真"的产物。我越认真，树画得越全，规则列得越细，笼子就编得越密。这不是懒出来的毛病。

---

四层上下文

原文最后给了一张分层图，我按自己的话重排一下，这套分工建议直接抄：

层	归谁管	该放什么
System Prompt	产品	Claude Code 用户基本不用改。但你要是在造自己的 Agent harness，这层该花掉你大部分时间
CLAUDE.md	仓库	轻量。一句话说清这仓库干什么，剩下的 token 全砸在"坑"上
Skills	你 / 团队	你独有的观点、知识、私房最佳实践。当轻量指南写，别写成军规（极重要的领域除外）
References	当前任务	@ 提及的具体文件：spec、mockup、测试、甚至整个代码库

References 这层有个细节值得单独拎出来：优先给代码形式的引用。原文说得很实在，一份 HTML 的设计稿，通常比一段设计描述、甚至比一张截图，都更能出好结果。代码是它最熟的语言。

你的 spec 可以就是一套详细的测试套件。你想要的实现，可以就是另一个代码库里的某个函数，"照它写"。

---

有一样东西别删

到这儿我得踩一脚刹车，因为这篇文章很容易被读成"删就完事了"。

上一篇《如何给 Loop 造个验证器》里我钉死了一条原则：验证器的价值，全在于它不听 Agent 的话，它必须是外部的、AI 改不动的东西。这两篇放一起才是完整的。

• "永远不许写多行注释"——这是规则，模型判断力够了就该删。
• "写得像周围的代码"——这是锚点，它指向代码本身，删了模型就没参照了。
• "任何删列的迁移必须配回填步骤"——这看起来像规则，其实是锚点，是通用 linter 抓不到的项目铁律。这条不但不能删，还该被做成一个真能跑的检查。

一个粗暴但好用的判据：这条内容，是在替模型做判断，还是在给模型提供它拿不到的事实？ 替它做判断的删，给它事实的留，而且最好从文字升级成能跑的东西。

Anthropic 敢删掉 80%，前提是他们手上有一整套评测在兜着。你敢删多少，取决于你有多少验证器兜着。没有验证器就大删特删，那是撒手。

---

今天就能动手的四步

1. 先跑 /doctor。Anthropic 把这套实践做进了这个命令，用来给你的 Skills 和 CLAUDE.md 做瘦身体检。别自己凭感觉猜哪块该删，先让它给你指一遍。

2. 删掉你的目录树。打开 CLAUDE.md，把所有"Claude 用 ls、cat、看一眼 package.json 就能知道"的内容全部划掉。省下来的篇幅，写三条它绝对猜不到的坑。

3. 抓冲突指令。全文搜自己的 CLAUDE.md 和 Skills，找有没有像"该写文档就写"配"绝对别加注释"这样的对打条款。每一对都在偷走模型的第一轮思考。找到就当场裁掉一边。

4. 超过 4 KB 的 Skill 基本都在违反渐进式披露。留一个薄入口，其余拆成子文件，让它需要时自己去取。

---

我们这两年练出来的很多"最佳实践"，是给一个能力较弱的模型写的补丁。补丁写得越熟练，越容易忘记它当初是在补什么洞。

所以每次模型换代，都值得回头问一句：我这些规矩，现在是在帮它，还是在替它做那些它已经比我做得更好的决定？

上周我还在琢磨怎么给 Claude 写更多规则。今天我打开 CLAUDE.md，第一件事是删那棵目录树。