过度约束,而非太长:CLAUDE.md 应该怎么写

你写过 CLAUDE.md,大概也遇到过这种事:明明白纸黑字写了,它该不照做还是不照做。多数人把这归给模型不太行,或者干脆归给文件太长了。

2026 年 7 月 24 日,Anthropic 在官方博客上给了另一个答案。他们把 Claude Code 的系统提示词删掉了 80% 以上,编码评测上没有可测量的损失:

"We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations."

删改prompt似乎还是他们工程化的做法，但是后面紧接着有：

"Overall, we found that we were overconstraining Claude Code, both through our system prompt and in our CLAUDE.md files and skills."

他们说自己过度约束了 Claude Code。而过度约束的载体,除了系统提示词,还包括 CLAUDE.md。

借着Claude 5 代模型都发布完的契机，我也来分享一下如何构建一个合理的CLAUDE.md，这个思想也许在其他模型下agent work 也能有借鉴意义。

官方删的是他们自己的提示词,跟我的 CLAUDE.md 有什么关系

第一层关系上面已经说了:官方原话点了 CLAUDE.md 的名。

第二层关系更根本——CLAUDE.md 从来就不是强制配置。

官方文档《How Claude remembers your project》写得很直白:

"CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance."

翻成人话:你的 CLAUDE.md 是以一条用户消息的身份,跟在系统提示词后面注入的。它不是配置文件,不是中间件,也不是 hook。同一份文档还有一句:

"Claude treats them as context, not enforced configuration."

当成上下文,不是强制配置。

为什么这样说？因为在agent视角，这段内容注入的时候,旁边会附一段提醒:

<system-reminder>
      IMPORTANT: this context may or may not be relevant to your tasks.
      You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

你辛辛苦苦写的规则被送进去的同时,还配了一句:这东西可能跟你的任务无关,别理它。

这就说明context工程里面——这套机制本来就没承诺强制执行。真正该问的问题也变了:既然不强制,什么样的内容它才愿意听?

不就是太长了吗?——这个解释能走多远

最顺手的答案是:太长了呗。文件越长,单条规则的分量越薄,靠后的越容易被吞掉。删短点不就完了。

这个直觉不是拍脑袋来的,它有实证撑腰,而且撑得还挺硬。

第一篇是 IFScale(《How Many Instructions Can LLMs Follow at Once?》)。它做的事很简单:往一个任务里堆指令,从几条堆到几百条,看依从性怎么掉。结论是,推理模型在 100–250 条这个区间之前基本还能全部照做,再往上开始掉。

论文里对实践最有用的,其实是它给出的三种衰减形态:

• 阈值型:阈值以内几乎不掉,过了阈值断崖式下滑。gemini-2.5-pro 和 o3 属于这一类。
• 线性型:一路稳步下滑,没有明显拐点。gpt-4.1、claude-3.7-sonnet 属于这一类。
• 指数型:几十条就崩,最后趴在 7%–15% 的地板上。claude-3.5-haiku、llama-4-scout 属于这一类。

阈值型最值得记住,因为它意味着多加一条规则的代价不是线性的。你可能连加二十条都相安无事,第二十一条突然就把整份文件的依从性拽了下去。

第二篇是 Chroma 的 Context Rot。

它里面有个实验对 CLAUDE.md 几乎是量身定做的,叫 LongMemEval。同一个问题、同一份相关信息,做两组输入:一组只给相关的那部分,另一组把这部分裹进十一万多 token 的无关内容里。模型在第一组上表现很好,在第二组上稳定地退步。

信息没少,问题没变,只是多裹了一层无关内容。

这正是把只对一个模块成立的规则塞进 CLAUDE.md 在干的事。

到这儿,旧框架能解释的部分已经解释完了,而且解释得不错——它甚至能说通删掉 80% 性能不掉这件事:删的是冗余,冗余本来就在拖后腿。

但它解释不了官方接下来做的事。

官方不是把句子改短。他们把规则改写成了让模型自己判断,还把示例删了。如果问题只是塞不下,示例是最不该删的那一部分——示例向来被认为是每个 token 都花得值的。

真正的机制:过度约束

官方给这个病起的名字叫 overconstraining,过度约束。

要害不是塞不下,是你给的规则挡了它的判断。

拆开看有三种形态：

形态一:用规则替代判断

官方给了自家改写前后的原句,对照着看最清楚。

改之前:

"In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max…"

改之后:

"Write code that reads like the surrounding code: match its comment density, naming, and idiom."

新句子确实更短,但短不是重点。重点是:旧句子替模型把答案定死了——不写注释、最多一行。而这个答案在多数仓库里都是错的,因为多数仓库里该写多少注释本来就没有统一答案。新句子把这个判断还给了模型,同时给了它判断的依据:看周围的代码怎么写。

你 CLAUDE.md 里的规则,十条里有几条是这种替它把答案定死的?

形态二:指令互相打架

这是官方自曝的例子:

"we see several conflicting messages in a single request like 'leave documentation as appropriate,' or 'DO NOT add comments' as our system prompt, skills, and user requests clash with each other."

一个请求里同时出现两条:该写文档就写,和不许加注释。这不是修辞上的矛盾,是真的从不同地方来的—— 一句来自系统提示词,一句来自某个 skill,还可能有一句来自你刚敲下的那行话。

你的 CLAUDE.md 越长,它跟 harness 自带的提示词、你装的 skill、你当下这句话撞车的概率就越高。每撞一次,模型都得先花力气仲裁,再开始干活。

说白了:你以为你在下命令,其实你在给它派仲裁工作。

形态三:示例把探索空间限死

这条最反直觉。多给示例几乎是 prompt 工程的公理,而官方现在把它放进了那张过去 → 现在的对照表,归到了过去那一栏。

理由是:示例会把模型约束在一个探索空间里。你给了 foo(a, b) 这个写法,它就倾向于沿着这个写法走,哪怕手边有更合适的接口。

替代做法是设计接口:把接口和参数设计得能自解释,让代码本身当那份示例——它比你贴在 Markdown 里的那段可靠,而且不会过期。

但这个替代方案有前提:它成立是因为有代码可依托。 官方这条是对着编码场景说的。写文档、定口吻、出报表这类活没有周围的代码可看,示例往往就是唯一能说清什么样算对的东西——你写十条要简洁、别太正式,不如给一封真实的邮件。

所以准确的说法是:示例用来传怎么做,是过度约束;用来传什么样算对,常常无可替代。 后一种别删,但也别让它常驻 CLAUDE.md——挪进 skill 或 path-scoped rule,用到的时候才加载。怎么挪,见后面讲去处的那一节。

官方那六条:过去 → 现在

官方这次不是把句子改短,而是把六类做法整体换了一遍,拆开看更容易对照自己的 CLAUDE.md。

一把尺子:留它猜不到的,砍它自己能看出来的

诊断有了,接下来得能落到每一行上:这条到底该留还是该删?

这把尺子不是我发明的,是官方写进 /doctor 这个命令的行为里的。官方文档这样描述它给 CLAUDE.md 瘦身时干的事:

"cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews, and keeps pitfalls, rationale, and conventions that differ from tool defaults"

砍掉它能从代码库自己推出来的:目录结构、依赖清单、架构概述。留下它猜不到的:坑、理由、以及跟工具默认值不一样的约定。

正面该怎么写,官方也给了:

"Keep your CLAUDE.md lightweight and briefly describe what your repo is for, but spend most of the tokens on gotchas inside of the codebase… Avoid stating 'the obvious' things Claude should know by looking at your file system or your repo."

轻量地说清这个仓是干什么的,大部分 token 花在坑上。

反过来,下面这五种是最常见的添乱内容。挨个对照一下你那份文件:

官方文档给的是硬指标:

"Size: target under 200 lines per CLAUDE.md file."

而实际上，Shrivu Shankar 一篇写团队实践的文章里,他们生产 monorepo 的 CLAUDE.md 是 13KB,他还说完全能想象它长到 25KB。13KB 粗估三百到六百行,跟 200 行不是一个量级。

两个数字都是真的,只是站位不同:官方给的是通用建议,他给的是一个有专职治理的团队在特定仓库里的现状。行数是体检指标,不是及格线。 一份三百行全是坑的文件,好过一百行全是目录结构的。真正的判据还是上面那把尺子;行数只用来提醒你该体检了。

顺手清一个过时说法:你可能见过 Anthropic 没有官方长度建议、社区共识 300 行以内这种话。它在 2025 年底是对的,现在不对了——官方给了 200 行。

还有两条来自实践的判据,我觉得比长度有用得多:

• 按 guardrail 写,不按手册写。 CLAUDE.md 的作用是拦住它掉进坑里,不是教它怎么编程——从它犯过的错反推着写。
• 只有禁令、没有替代,会让它卡死。 他的原话是:模型认定自己必须用那个东西的时候就会卡住,所以 "Always provide an alternative."。与其写不要用 X,不如写:用 Y;别用 X,因为 X 在我们这儿会 ⋯⋯

最后给你一个三问自检,每条规则过一遍:

1. 它自己看一眼代码,能不能推出来?
2. 它是不是只对某一个目录成立?
3. 它是不是本该交给 linter?

有了这把尺子,回头看每一条规则该留还是该删,可以走一遍固定的三问自检,不用凭感觉。

三个里但凡有一个成立,这条就该删,或者该挪。第三条尤其常见——HumanLayer 有句话值得提出来:"Never send an LLM to do a linter's job."

这把尺子还有一个坑,是我自己实测时踩出来的:把只对某个目录成立的规则挪成 path-scoped rule,前提是这条规则的违规现场也在那个目录里。要是判断依据在别处——比如不许从别的模块 import 这个变量这类跨模块约束——按需加载在最需要它的时候反而不会触发。判据是违规会发生在哪个目录,不是这条规则在讲哪个模块;按需加载不是无脑好。

写不下的放哪?@ 一下行不行

删是删了,但有些东西确实有用,只是不该每次都在场。它们该去哪?

先破一个最常见的做法:把内容拆成几个文件,在 CLAUDE.md 里用 @ 引进来。

这不省任何上下文。 这条我自己测了,数字在下一节。

"Splitting into @path imports helps organization but doesn't reduce context, since imported files load at launch."

说人话:@某文件 等于把那份文件整份贴进每一次会话,只是你那份 CLAUDE.md 看起来短了而已。

真正决定省不省的,是各种机制什么时候进上下文。下面这张表是这篇里最该存下来的东西:

官方的分流原则,一句话:

"If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead."

多步流程,或者只对代码库某一块成立的——挪进 skill 或者 path-scoped rule。

但这里有个坑。 很多人挪完之后在 CLAUDE.md 里留一句详见 docs/xxx.md,然后发现它压根不去读。Shrivu Shankar 把这事说得很直:

"if you just mention the path, Claude will often ignore it. You have to pitch the agent on why and when to read the file."

你得推销,不能只列路径。给触发条件——什么时候去读、遇到什么去读:

处理复杂的 XX 用法,或者遇到 FooBarError 时,去读 path/to/docs.md 里的排查步骤。

@ 本身的定位也变了。官方现在把它当成 references——给当前这个具体计划用的深度参考,而不是组织文档的手段。而且更推荐指向代码里的文件:

"Generally you should prefer files that are in code as it provides clear, high-fidelity instructions to Claude in a language it knows very well."

最后送个小彩蛋:块级 HTML 注释在内容注入之前就被剥掉了,不花 token。给下一个接手的人留的说明,用它写。

我改完了,怎么知道有没有效

改完不验证,等于把一种玄学换成另一种。有三个动作可以直接跑。

/context —— 看 Memory files 那一栏。它会告诉你哪些文件真的被加载了、一共占多少 token。这是最快的一次体检,建议在编码会话中途至少跑一次。

/doctor —— 它会主动提议该删什么,依据正是上一节那把尺子:砍能推出来的,留猜不到的。

InstructionsLoaded hook —— 挂上它,把到底加载了哪些指令文件、什么时候加载、为什么加载全部日志化。比挂代理抓包好复现得多。它的日志长什么样,下一节直接贴。

基于上述理论的演示，用货真价实的Claude token换数据

三项验证都跑在同一个一次性测试仓上:CLI 2.1.220、claude-sonnet-5、opus-5、云端容器,反例版 189 行,改造版 24 行。先看 Memory Files 占了多少预算。

拆文件配合 @ 导入,token 占用几乎没降;把规则改写成按需加载,才是真正省预算的动作。

再看规矩守不守得住,十四条规则全部程序判定:sonnet-5 交替跑十二轮,opus-5 交替跑六轮,只挑差异最大的三条。

sonnet-5 上两版总合规率差 0.98pp,十一条规则完全打平;换到 opus-5,H4、H5 差异归零,只有 P4 反而拉大——六轮里反例版有 4 轮栽在这条规则上。

真正决定预算的,不是文件切成几份,是规则什么时候进上下文。

payment 规则只在碰到 app/payment/ 下的文件时才加载,auth、utils 两个文件全程没被碰过。(两轮都跑在云端容器里,这个环境有个怪癖:多次独立调用拿到同一个 session_id,日志一个字没改;发起时刻、计费、token 用量各不相同,原始文件在仓里,可以自己对。)

测法一句话:三项都跑在专门新建的一次性测试仓上,规则依从性用 sonnet-5、opus-5 两档模型分别交替跑十二轮与六轮,十四条规则全部程序判定,不靠人工打分。

写到最后

Claude每次发布，除了新性能的模型，还会带来Agent开发的策略的新的迭代升级，从原来复制Prompt到现在把决策交给AI，也许我们自己也要想想在做Project的时候，是自己定好规矩还是相信AI能构建。

参考

• The new rules of context engineering for Claude 5 generation models — Thariq Shihipar,Anthropic,2026-07-24
• How Claude remembers your project — Claude Code 官方文档
• Writing a good CLAUDE.md — Kyle,HumanLayer,2025-11-25
• How I Use Every Claude Code Feature — Shrivu Shankar,2025-11-02(2026-03-20 修订)
• How Many Instructions Can LLMs Follow at Once? — IFScale
• Context Rot: How Increasing Input Tokens Impacts LLM Performance — Kelly Hong 等,Chroma Research,2025-07-14