CLAUDE.md不是写得越详细越好：实证研究支撑的极简写法与最优行数

摘要：很多人把CLAUDE.md当成越塞越好的知识库，结果AI反而更容易跑偏。ETH Zurich在2026年初的一项实测给出了反直觉的结论：人工精简的指令文件能让编程代理的成功率提升约4%，而让大模型自己生成的长文件，在8组评测里有5组成功率不升反降，还多烧20%以上的推理成本。这篇文章用这份研究和Claude官方现行规则，讲清楚CLAUDE.md到底写多少行最优、该写什么不该写什么，以及放不下时三条不靠堆字数的出路。

保哥最近帮一个做户外装备独立站的技术团队看他们的Claude Code配置，打开根目录那份CLAUDE.md，足足240多行：项目历史、设计哲学、团队成员分工、连“我们崇尚简洁优雅的代码”这种话都写进去了。他们的困惑是——明明把所有规矩都交代得清清楚楚，AI却经常无视其中最关键的那几条，比如“改动支付相关代码前必须先走计划模式”。

这不是个例。把CLAUDE.md写成一本越来越厚的说明书，几乎是每个团队都会踩的坑。而真相恰恰相反：对CLAUDE.md来说，长度本身就是一种成本，写得越多，关键约束被稀释得越厉害。这篇文章不讲“CLAUDE.md是什么”那些基础，专攻一个被严重忽视的问题——写多少、写多精简，才是最优解。如果你还在纠结结构怎么搭、措辞怎么写，可以先看这篇CLAUDE.md怎么写才听话的实操篇，那篇管“怎么写”，这篇管“写多少、删什么”，正好互补。

为什么你那份越写越长的CLAUDE.md，反而让AI更笨了？

先理解一件事：CLAUDE.md不是配置文件，是上下文。它在每次会话开始时被原样塞进模型的上下文窗口，和你的对话挤在一起。官方说得很直白——它是上下文而非强制配置，模型读到它会尽量遵守，但没有任何强制力。一个更隐蔽的细节是：CLAUDE.md的内容并不是作为系统提示词注入的，而是以一条用户消息的身份排在系统提示之后——这进一步说明它对模型只有“建议权”，没有“命令权”，越长就越像一段絮叨的开场白，越容易被后面的真实任务盖过。

这就带来一个被多数人忽略的连锁反应。你每多写一行，就多一行常驻token，每次会话都要重新加载、重新消耗；更要命的是，模型的注意力是有限的，当240行里有200行是无关紧要的背景介绍，那10行真正重要的安全约束就被淹没在噪音里。模型每次接到任务，都要先花一轮推理去“过滤”掉那些不相关的规则，才能找到该执行的那条。

所以那个户外团队的问题根本不是“规矩没写全”，而是“写太全了”。把项目崇尚什么、历史怎么演进这类对执行毫无帮助的内容删掉，把那条支付约束单独拎出来用强调标记顶在前面，AI的遵循度立刻就上来了。这正是极简主义的核心逻辑：CLAUDE.md的价值不在于覆盖多全，而在于信噪比多高。

实证研究怎么说：写不写、谁来写，差别有多大？

这不是凭空的个人体感。2026年初，苏黎世联邦理工学院（ETH Zurich）的研究团队做了一项系统评测，论文叫《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》，专门量化了这类仓库级指令文件到底有没有用。结论值得每个写CLAUDE.md的人贴在显示器上。

他们的实验设计很扎实，用了两套互补的基准。一套是大家熟悉的SWE-bench Lite，300个任务来自11个热门Python仓库；另一套叫AGENTbench，138个任务来自12个相对小众、但本身就带有开发者手写指令文件的仓库。测试对象是4个真实的编程代理：跑Sonnet 4.5的Claude Code、分别跑GPT-5.2和GPT-5.1 mini的Codex、以及跑Qwen3-30B的Qwen Code。每个代理都在三种条件下各跑一遍——不给任何指令文件、给一份大模型自动生成的、给开发者手写的那份。

第一个发现是好消息：代理是真的会读、会照做。当指令文件里提到某个工具，比如用uv来管依赖，代理使用这个工具的频率会涨到原来的1.6倍。这说明你写的话不是石沉大海。

但第二个发现就扎心了。开发者手写的精简指令文件，在AGENTbench上带来约4%的成功率提升；而让大模型自己生成的那份长文件，在8组评测设置里有5组成功率不升反降，平均往下掉0.5到2个百分点。更别提，带上这类文件后，推理成本普遍上涨超过20%——因为模型被鼓励去做更宽泛的探索，绕的弯路更多。

把这两个数字放一起看，信息量极大：指令文件本身是把双刃剑，写对了加4%，写错了反而扣分还多花钱。而“写错”的最典型形态，就是图省事让AI自己生成一大篇。顺带说一句，源头上有些二手文章把AI生成版的影响一刀切写成“掉3%”，那其实是某篇转载的标题党概括，论文原文给的是“5/8设置下降0.5到2个百分点”这个更克制也更准确的区间——这种地方查到原始论文核对一遍，正是判断一份SEO内容靠不靠谱的分水岭。

还有一个容易被读漏的结论：研究发现，不管是人工版还是AI生成版，指令文件都会“鼓励代理做更宽泛的探索”。听上去探索更多是好事，但对一个目标明确的编程任务，宽泛探索往往意味着多翻无关文件、多调用工具、多绕弯路，这正是推理成本涨20%的来源。换句话说，一份糟糕的CLAUDE.md不只是没帮上忙，它还在主动把代理的注意力往岔路上引。这和做SEO内容时的体会一模一样——给读者塞一堆“可能相关”的信息，不会让他更快找到答案，只会让他更快关掉页面。约束的价值在于收敛，不在于发散。

三个最贵的误区，你大概率正踩着

顺着这份研究往下推，有三个误区几乎人人有份。每一个都在悄悄让你的CLAUDE.md从资产变成负债。

误区一：CLAUDE.md越详细越好

这是最普遍的错觉。详细听起来总是对的，但对一份每次会话都要全量注入的上下文来说，详细等于昂贵加干扰。那个240行的文件里，真正能改变AI行为的指令可能就十几条，剩下的全是背景、解释、客套。删掉它们不会损失任何执行力，只会让剩下的关键规则更突出。记住石蕊测试这句话：删掉这一行，AI会因此犯一个具体的、能说得出名字的错误吗？说不出来，这行就该删。

误区二：让大模型自动生成CLAUDE.md省事

这是被研究直接打脸的那个。让Claude自己分析代码库生成一份CLAUDE.md，听起来高效，但它生成的往往是“写干净的代码”“遵循最佳实践”这类通用废话——模型本来就会这些，写进去纯属重复，还把真正项目特有的约束给稀释了。这正是为什么AI生成版在评测里反而拖后腿。正确做法不是不用/init，而是把/init当起点，生成后逐行删改，只保留模型自己发现不了的项目特有规则。

误区三：一个仓库一个大文件就够了

对单体仓库或者monorepo，把所有领域的规则全堆进根目录那一份CLAUDE.md，是另一个慢性毒药。前端团队写的样式约定，在你改后端API时纯属噪音；内容团队的发布规范，在调试构建脚本时只会添乱。这些不该挤在一起常驻，而该按路径拆开、按需加载——后面会讲具体怎么做。

官方到底建议写多少行？

研究给了方向，Claude官方文档给了硬线。官方的内存机制文档白纸黑字写着：每份CLAUDE.md目标控制在200行以内，更长的文件会消耗更多上下文并降低遵循度。注意措辞——不是“200行是上限”，而是“目标在200行以内”，言下之意是越短越好，200行是你该开始警觉的红线，不是舒适区。

这里还要纠正一个流传很广的旧说法：很多老教程说CLAUDE.md是“后面的覆盖前面的”。这是错的。官方现行机制是全部拼接（concatenate），不是覆盖。Claude Code会从你的工作目录一路向上遍历目录树，把沿途每一层的CLAUDE.md和CLAUDE.local.md全部收集起来，按从文件系统根目录到工作目录的顺序拼进上下文。也就是说，上层目录的规则不会被下层替换掉，而是叠加——这意味着如果你在monorepo里层层都写大文件，它们是会累加进同一个上下文窗口的，撑爆得更快。

结合起来理解就清楚了：200行是单份文件的目标，而拼接机制决定了你要对整条目录链上的总量负责。这正是极简主义在工程上的硬约束来源。关于四级作用域（管理策略级、用户级、项目级、本地级）各自放什么、加载先后顺序怎么排，CLAUDE.md记忆术那篇里有完整的对照，配合这里的“总量预算”视角一起看会更立体。

该写什么、不该写什么：一条石蕊测试走天下

知道了要短，下一步是判断哪些该留哪些该砍。官方给的判断标准其实很简单：CLAUDE.md只放那些“你希望AI每次会话都记在脑子里的事实”——构建命令、代码约定、项目布局、“永远要做X”这类硬规则。一旦某条内容变成了多步骤流程，或者只在代码库的某一小块才用得上，它就不该待在CLAUDE.md里。至于哪些内容本质上是写给人看的说明、该归到README而非CLAUDE.md，CLAUDE.md和README的分工那篇里按受众、语气、内容、格式四条线拆得很细，这里不再展开。

下面这张对照表，是保哥给客户做CLAUDE.md减法时的标准清单：

那条石蕊测试值得再说一遍，因为它能解决90%的纠结：把光标停在任意一行上，问自己——如果删掉这行，AI接下来会犯一个我能具体描述的错误吗？能，留下，最好还用IMPORTANT、NEVER、MUST这类标记把它顶起来；说不出会犯什么错，删。这一招比任何字数公式都好用。

放不下了怎么办？三条不靠堆字数的出路

很多人不是不想精简，是真有一堆规则不知道往哪放。好消息是，Claude Code现在提供了三条机制，让你既能保留信息、又不让它们常驻上下文。关键是搞清楚它们在“省不省token”上的本质区别——这点连不少老用户都搞混。

先说最被低估的那个：.claude/rules/目录加路径作用域。你可以把规则拆成一个个聚焦的小文件放进.claude/rules/，每个文件顶部用YAML前缀声明它管哪些文件：

---
paths:
  - "src/api/**/*.ts"
---

# API开发规则
- 所有接口必须做输入校验
- 统一用标准错误响应格式
- 补全OpenAPI文档注释

这样一来，这条API规则只在Claude真正去读src/api/下的TypeScript文件时才加载进上下文；你改前端样式时它根本不出现。这才是monorepo拆分的正解——不是把大文件留在根目录硬扛，而是让每块规则只在相关时才现身。没写paths的规则文件则会在启动时无条件加载，优先级等同于.claude/CLAUDE.md，所以真正想省上下文，paths那行别漏。

第二条@import是最容易被误解的。它确实能让你把命令清单抽到docs/commands.md当唯一事实源，再让CLAUDE.md用@docs/commands.md引用它，改一处两边同步。但要清醒一点：@import解决的是“维护重复”，不是“节省上下文”——被导入的文件在启动时照样会被展开、全量塞进上下文窗口。所以拿@import当减肥手段是自欺欺人，它只是让组织更清爽，token一分没少。真要省，靠的是路径作用域和Skill。

第三条是把流程抽成Skill。CLAUDE.md适合放“构建命令是npm run build”这种一行事实；而“完整的灰度发布七步流程”这种长东西塞进去，每次会话都加载就是浪费。把它做成Skill，平时安安静静待在一边，只有当你真的要发布、Claude判断需要时才加载进来。事实留在CLAUDE.md，流程抽进Skill——这是官方反复强调的分工。

一份50行级的极简CLAUDE.md长什么样？

讲了这么多原则，给个能直接抄的骨架。下面这份是保哥给一个跑Next.js的独立站项目精简后的版本，删到了50行出头，但每一行都经得起石蕊测试：

# 项目约定

## 命令
- 开发：`pnpm dev`
- 测试：`pnpm test`（提交前必跑）
- 构建：`pnpm build`

## 技术栈
- Next.js 15 + TypeScript 5.7
- 数据获取统一用 React Query，不要手写 fetch

## 硬约束
- IMPORTANT：改动 src/billing/ 下的代码前，先进入计划模式
- NEVER：把密钥写进代码或提交到仓库，一律走环境变量
- 接口处理逻辑放 src/api/handlers/，组件放 src/components/

## 经验教训
- 这个项目的 SSR 页面别用 useEffect 取数据，会闪屏，用 server component

注意它没有的东西：没有项目介绍，没有“我们追求高质量”，没有把ESLint规则抄一遍，没有完整的部署流程（那个抽成了Skill）。它只回答一个问题——“一个新来的AI协作者，需要知道哪些这个项目独有、又说不出口的潜规则？”那段“经验教训”尤其值钱，它记录的是Claude在这个项目里真实犯过的错，是别处抄不来的项目专属知识。

90秒自检：怎么给现有的CLAUDE.md做减法？

如果你手上已经有一份臃肿的CLAUDE.md，不用推倒重来，按下面这套90秒流程过一遍就能瘦身大半：

1. 从头到尾扫一遍，每碰到一行就做石蕊测试：删了它AI会犯具体错误吗？说不出来的，标记删除。
2. 把所有“介绍性”“解释性”内容整段拎出来——项目背景、设计理念、团队介绍，这些挪进README，CLAUDE.md一行不留。
3. 找出所有超过三步的流程，抽成Skill；CLAUDE.md里只留一句“发布流程见发布Skill”。
4. 看有没有抄了Linter的规则（缩进、分号、引号风格），ESLint和Prettier已经强制的，全删。
5. 检查矛盾：有没有两处规则打架，比如一处说用Redux一处说用Zustand？留一个权威来源，删另一个，否则模型会随机挑一个执行。
6. 把剩下的安全相关硬约束，用IMPORTANT/NEVER/MUST顶到显眼位置。
7. 开一个新会话，给Claude一个典型任务，看它是否遵循了你保留的关键规则。不遵循，说明那条写得还不够具体，改成可验证的措辞再试。

做完这一轮，绝大多数240行的文件会瘦到80行以内，而AI的遵循度不降反升。这就是减法的威力。

精简之后，还有哪些进阶模式能让规则更聪明？

把CLAUDE.md做减法不等于把它做傻。精简的目标是去掉噪音，不是去掉智能。下面三个进阶模式，能在不增加常驻长度的前提下，让你的规则体系更聪明。

第一个是“经验教训”这一小节，前面模板里那段就是。它的妙处在于，它不是你坐在那儿凭空想出来的规则，而是从Claude的真实失误里长出来的。每当AI在这个项目里犯了一个具体的、第二次还可能再犯的错，你就把它浓缩成一行写进去。比如“这个项目的SSR页面别用useEffect取数据会闪屏”——这种知识没有任何通用教程会告诉你，它是项目独有的疤痕记忆，价值密度极高，完全配得上常驻上下文那点token。

第二个是条件化思维。与其在一份大文件里写“做API开发时要这样、做前端时要那样”，不如把它们物理隔开——API规则用paths作用域绑到接口目录，前端规则绑到组件目录。模型在哪个领域干活，就只看到哪个领域的规则，天然就实现了“条件触发”，还不占无关场景的上下文。这比在一份文件里写一堆if-else式的自然语言条件判断可靠得多，因为模型不擅长在长文里精确匹配条件分支。

第三个是和钩子联动。CLAUDE.md里可以写“提交前要跑测试”，但这条规则靠模型自觉，它可能忘。真正想让它每次必跑，是配一个Claude Code钩子（Hooks）在对应生命周期事件上自动执行。这样CLAUDE.md里那行就可以从“记得跑测试”降级成一句轻描淡写的说明，甚至直接删掉——因为有钩子兜底，不需要再用宝贵的上下文反复叮嘱一件本可以自动化的事。把“能自动化的”交给钩子，CLAUDE.md自然就瘦了。

本土化：独立站和SEO批量活里，精简CLAUDE.md怎么省钱省心？

对做跨境独立站、SEO批量内容的同行，CLAUDE.md的精简不是洁癖，是真金白银。保哥团队常年用Claude Code跑两类活：一类是给Shopify、WordPress主题做二次开发，一类是批量生成和改写内容、处理结构化数据。这两类活有个共同点——会话开得极其频繁，一天几十上百次。

这意味着CLAUDE.md的每一行token，都要乘以会话次数来算总账。一份臃肿到5000token的CLAUDE.md，跑100次会话就是50万token的纯浪费，还不算它拖低遵循度导致的返工。把它砍到800token，一天省下的就是实打实的额度——这一点在用订阅档、有5小时窗口限额的场景下尤其敏感，省下的token直接转化成你能多跑的活。

算笔更具体的账。假设一个10人的独立站开发团队，人手一份相同的项目CLAUDE.md，原本是4200行的庞然大物（别笑，monorepo根目录把所有子项目规则堆一起很容易到这个量级）。按平均每行15token估，单份就是6万多token；团队一天合计开300次会话，光是反复加载这份文件就要烧掉接近1800万token。把它按路径作用域拆开，让每次会话平均只加载相关的那600行，瞬间降到不足十分之一。这还只是显性成本，隐性的是：那4200行里夹杂的矛盾规则、过时约定，每次都在悄悄拉低产出质量，返工的工时才是真正的大头。精简CLAUDE.md，本质上是在给整个团队的AI协作降本。

还有一个本土化场景的硬道理：真正不能让AI碰的红线，别指望CLAUDE.md兜底。官方说得很清楚，CLAUDE.md是行为引导不是强制层。如果你的规矩是“绝对不能动生产数据库”“绝对不能删客户表”，这种零容忍的约束，正确做法是写成PreToolUse钩子——它是真正在工具执行前拦截的硬闸，不管模型怎么想都拦得住。CLAUDE.md负责“引导AI往对的方向走”，钩子负责“在它走错时一把按住”，两者分工，CLAUDE.md才能保持精简而不用承担它扛不住的责任。

说到底，精简CLAUDE.md和做SEO是一个道理：堆量从来不是答案，把每一份资源用在信噪比最高的地方才是。一份50行、每行都掷地有声的CLAUDE.md，胜过240行的自我感动。

反过来想：什么情况下再精修CLAUDE.md也没用？

极简主义不是万能药。承认它的边界，反而能帮你把力气花在对的地方。有四种情况，再怎么打磨CLAUDE.md都收效甚微，得换工具。

一是一次性的临时需求。某个只做一次、下次不会再碰的特殊处理，没必要写进每次会话都加载的CLAUDE.md，直接在对话里告诉Claude就行——为一次性的事付常驻token的代价不划算。

二是规则本身太软、太主观。像“代码要优雅”“注释要有意义”这种没法验证的指令，模型读了也无从执行，写多少遍都白搭。要么把它具体成可验证的形式（“每个公开函数必须有一行说明它的副作用”），要么干脆别写。模糊指令是CLAUDE.md里最大的token黑洞。

三是需要跨会话自动积累的知识。如果你想让AI自己记住“这个项目的测试要先起一个本地Redis”，这类它在干活中自己摸索出来的经验，更适合交给自动记忆机制去沉淀，而不是你手动一条条往CLAUDE.md里抄。手写CLAUDE.md管“你想让它做什么”，自动记忆管“它自己学到了什么”，两者分工。

四是必须100%执行的硬约束。前面反复强调过，CLAUDE.md对模型只有建议权。任何“绝对不能”级别的红线，写进CLAUDE.md都有被忽略的概率，必须上钩子做硬拦截。把这类约束硬塞进CLAUDE.md，不仅不保险，还白白占着本该留给真正引导性指令的篇幅。认清这四条边界，你就不会再对着一份CLAUDE.md反复纠结那些它压根解决不了的问题。

常见问题解答

CLAUDE.md到底写多少行最合适？

官方目标是单份文件控制在200行以内，越短越好。实测经验是大多数项目砍到80行以内反而遵循度更高。没有死的字数公式，但一旦超过200行还在涨，基本说明混进了不该放的东西——长解释、多步骤流程、和README重复的内容。200行是该警觉的红线，不是舒适区。

让Claude用/init自动生成CLAUDE.md行不行？

可以当起点，但别直接用。ETH Zurich的研究显示，大模型自动生成的指令文件在多数评测设置里反而拉低成功率，因为它爱写“遵循最佳实践”这类通用废话稀释关键约束。正解是把/init生成的当草稿，逐行删改，只留模型自己发现不了的项目特有规则。

把规则用@import拆到别的文件，能省上下文吗？

不能，这是最常见的误解。@import被导入的文件在每次会话启动时照样全量展开进上下文，token一分没省。它解决的是“同一信息维护两遍”的问题，让组织更清爽。真正想省上下文，要用.claude/rules/的路径作用域（只在碰到匹配文件时加载）或者把流程抽成Skill（按需调用）。

monorepo里规则太多，该怎么组织CLAUDE.md？

别把所有领域的规则堆进根目录一份大文件，那样改任何一块都要背上全部噪音。用.claude/rules/把规则按主题拆成小文件，每个文件用paths前缀声明它管哪些路径，这样前端规则只在改前端时加载、后端规则只在改后端时加载。还可以用claudeMdExcludes跳过其他团队不相关的CLAUDE.md。

CLAUDE.md里的多份文件是后面覆盖前面吗？

不是，这是老教程的过时说法。现行机制是全部拼接，不是覆盖。Claude Code从工作目录向上遍历，把每一层的CLAUDE.md和CLAUDE.local.md按从根到工作目录的顺序全部叠加进上下文。上层规则不会被下层替换，而是累加——所以整条目录链上的总量都要算进你的上下文预算。

精简了CLAUDE.md，重要的安全规则会不会失守？

恰恰相反，精简能让安全规则更被重视，因为它不再被噪音淹没。但要清醒：CLAUDE.md是行为引导不是强制层，零容忍的红线（如禁删生产数据）应该写成PreToolUse钩子，它在工具执行前真正拦截，不受模型判断影响。CLAUDE.md引导方向，钩子守住底线，分工明确才安全。