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慢慢从资产变成负担。

CLAUDE.md越详细越好吗？

这是最普遍的错觉。“详细”听起来总没错，但对一份每次会话都要全量注入的上下文来说，详细就意味着成本高、干扰多。那个240行的文件里，真正能改变AI行为的指令可能只有十几条，其余都是背景、解释和客套话。删掉它们不影响执行，剩下的关键规则反而更显眼。判断标准可以用这条石蕊测试：删掉这一行，AI会因此犯一个具体的、能说出名字的错误吗？说不出来，这行就该删。

让大模型自动生成CLAUDE.md能省事吗？

研究数据直接否定了这个做法。让Claude自己分析代码库生成CLAUDE.md看似高效，但生成的内容多半是“写干净的代码”“遵循最佳实践”这类通用废话，模型本来就会，写进去只是重复，还把真正项目特有的约束稀释了。这正是AI生成版在评测里拖后腿的原因。/init可以用，但要把/init当起点，生成后逐行删改，只保留模型自己发现不了的项目特有规则。

一个仓库只放一个大CLAUDE.md够用吗？

对单体仓库或monorepo，把所有领域的规则都堆进根目录那一份CLAUDE.md，问题会慢慢积累。前端团队写的样式约定，在你改后端API时全是噪音；内容团队的发布规范，在调试构建脚本时只会添乱。这些规则不该挤在一起常驻，应该按路径拆开、按需加载，具体做法见后文。

CLAUDE.md官方建议写多少行？

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

这里还要纠正一个流传很广的旧说法：很多老教程说CLAUDE.md是“后面的覆盖前面的”，这是错的。官方现行机制是全部拼接（concatenate），不是覆盖。Claude Code会从你的工作目录一路向上遍历目录树，把沿途每一层的CLAUDE.md和CLAUDE.local.md都收集起来，按从文件系统根目录到工作目录的顺序拼进上下文。

上层目录的规则不会被下层替换，而是叠加。如果你在monorepo里每一层都写大文件，它们会累加进同一个上下文窗口，窗口会更快被撑满。

两条规则合起来看：200行是单份文件的目标，拼接机制则要求你对整条目录链上的总量负责，这就是极简写法在工程上的硬约束。关于四级作用域（管理策略级、用户级、项目级、本地级）各自放什么、加载顺序如何排，CLAUDE.md记忆术那篇有完整对照，可以结合这里的“总量预算”一起看。

CLAUDE.md该写什么、不该写什么？

确定了要写短，下一步是判断哪些该留、哪些该删。官方给的标准很简单：CLAUDE.md只放“你希望AI每次会话都记住的事实”，比如构建命令、代码约定、项目布局、“永远要做X”这类硬规则。某条内容一旦变成多步骤流程，或者只在代码库的某一小块用得上，就不该放在CLAUDE.md里。

至于哪些内容其实是写给人看的说明、应该放进README而不是CLAUDE.md，CLAUDE.md和README的分工那篇从受众、语气、内容、格式四个方面做了细致拆分，这里不再展开。

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

石蕊测试值得再强调一次，它能解决90%的取舍问题。把光标停在任意一行，问自己：如果删掉这行，AI接下来会犯一个我能具体描述的错误吗？能，就留下，最好再用IMPORTANT、NEVER、MUST这类标记突出；说不出会犯什么错，就删。这个方法比任何字数公式都好用。

CLAUDE.md规则放不下时，该往哪里分流？

很多人不是不想精简，而是手上确实有一堆规则不知道放哪里。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.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引导方向，钩子守住底线，两者分工明确才安全。