CLAUDE.md怎么写才能让AI每次都听话？结构、模板与避坑实操

摘要：CLAUDE.md写了AI还是不照做，九成是写法的问题，不是它不听话。它本质是每次会话开头注入的一段上下文，是软约束不是强制配置，所以写得模糊、太长、自相矛盾，遵循度就垮。写好它的关键就几条：只放事实和硬规则、长流程抽去做Skill；用祈使句、写具体到能验证的指令；单文件压在200行以内、太长用@import和路径作用域拆开；用/init起草再精简、写完让它跑一遍验证遵循度；真正不能松动的红线别指望它自觉，交给hook硬卡。本文把这套写法、三个能直接抄的模板，和最常见的几个反模式一次讲透。

几乎每个认真用Claude Code的人，都经历过这么一刻：明明在CLAUDE.md里白纸黑字写了“用pnpm不用npm”，它转头还是敲了一句npm install。于是开始怀疑——这文件到底有没有用？是不是写了也白写？

这种挫败感很普遍，但结论下错了。CLAUDE.md当然有用，问题出在它“怎么用”上：它不是一份你设好就铁定生效的配置文件，而是每次会话开头被塞进模型上下文的一段提示。官方记忆机制文档说得很直白——它是“上下文，不是强制配置”，模型读了会尽量遵守，但不保证字字照做。这意味着，你写得越具体、越精炼、越没有自相矛盾，它照做的概率就越高；反过来，写成一篇又长又糊的项目说明书，它大概率挑着看、看着看着就忘了。

所以这篇不讲“CLAUDE.md是什么”这种入门概念，那部分站内已有专文。这篇只解决一个问题：到底怎么写，AI才真的照做。保哥这两年给团队和客户配过几十份CLAUDE.md，从一开始写得又臭又长没人理它，到后来精简成几十行却句句生效，踩过的坑和总结的规律，都在下面了。

CLAUDE.md为什么写了AI还是不听？

先把根因弄明白，后面的写法才有的放矢。

第一个原因是它的身份被误解了。很多人潜意识里把CLAUDE.md当成.eslintrc那种配置——设好规则，工具就强制执行。但它不是。它更像你入职第一天，老员工塞给你的一张便签，上面写着“我们这儿都这么干”。便签写得清楚，你照做；写得啰嗦含糊，你可能扫一眼就扔抽屉了。模型对待CLAUDE.md就是这个态度：它是参考，不是法律。理解这一点，你才会明白为什么“写法”比“写没写”更重要。

第二个原因是它每次都全量加载，占着上下文。CLAUDE.md里的每一行，每开一次新会话都会被读进去，和你的对话抢同一块注意力。一份200行的精炼文件，模型能稳稳记住；一份500行混着技术栈、历史决策、团队文化、踩坑故事的长文，关键的那几条硬规则就被淹没在噪音里，遵循度断崖式下跌。官方的建议很明确：单个文件控制在200行以内，越长越费上下文、遵循度越差。

第三个原因是自相矛盾。项目大了之后，根目录一份CLAUDE.md、子目录又一份、还有个人的本地配置，几份文件如果对同一件事给了不同指令——比如一处说“缩进用2空格”、另一处说“用4空格”——模型只能随机挑一个照做，你看到的就是“它时而听话时而不听”。这种情况下，问题根本不在某一条规则，而在你从没通读过这几份文件、清掉互相打架的地方。

这里还有个容易被忽略的细节：CLAUDE.md的内容是在系统提示之后、以一条用户消息的形式喂给模型的，不是写死在系统提示里。这就解释了为什么它对“强约束”天然无力——它在模型眼里和你对话里说的话是同一个层级的东西，份量摆在那。明白了这点，你就不会再期待它有配置文件那种铁律般的效力，而会把真正硬的需求交给该交的地方（官方Hooks文档里的钩子），把CLAUDE.md用在它擅长的“持续提供项目常识”上。

把这几点连起来看，一个朴素的结论就出来了：CLAUDE.md不是写得越多越好，而是写得越准越好。下面每一条写法，本质上都在对治这几个根因。

到底什么该写进CLAUDE.md，什么不该？

这是最该先想清楚的事。装进去的内容选对了，后面的措辞优化才有意义；装错了，写得再漂亮也是负担。

官方给的判断信号很实用：当它第二次犯同一个错、当code review挑出一个它本该知道的项目惯例、当你又一次把上次说过的纠正打进对话框——这些时刻，就是该往CLAUDE.md里加一条的信号。换句话说，CLAUDE.md装的是“那些你不想再解释第二遍的事”。

具体该写的，是事实和硬规则：构建和测试命令（pnpm dev、pnpm test）、目录约定（“接口处理函数都放在src/api/handlers/”）、命名规矩（文件名kebab-case、组件PascalCase）、以及“永远要做X”“绝不能做Y”这类不变的底线。这些有个共同点——它们是事实陈述，短、明确、每次会话都该让它知道。

不该写的有三类。一是长篇背景和理由，比如“我们当初为什么从REST迁到GraphQL”这种历史叙事。这些对人理解项目有用，但对模型执行任务毫无帮助，纯属占上下文，该放README。二是多步骤的长流程，比如一整套发布步骤、一个复杂功能的实现规范。官方的Skills文档专门提醒：如果一条内容是多步骤流程、或者只对某一小块代码有用，就别塞CLAUDE.md，抽成Skill或路径作用域规则。三是linter已经强制的规则，ESLint、Prettier已经卡死的格式，再写进CLAUDE.md就是重复，纯浪费。

这里有条贯穿始终的分界线值得记牢：事实留下，流程抽走。一条短事实——构建命令是什么——留在CLAUDE.md，每次都该知道；一套很长的流程——完整的发布步骤——抽成Skill，只在真要发布时才加载。很多人CLAUDE.md越写越臃肿，根因就是把本该是Skill的东西全堆进了这份每次会话都加载的常驻文件。怎么判断该不该抽出去？一个很灵的土办法：如果某段内容在CLAUDE.md里越长、越像一份操作手册，那它多半该搬去做Skill。关于Skill怎么设计才好用，站内的Skill设计模式那篇讲得很细，配着看能把“事实和流程怎么分家”彻底想通。

怎么写AI才真的照做？

内容选对了，接下来是措辞。同样一条规则，写法不同，遵循度能差出一截。这部分是CLAUDE.md的“手艺活”，几条原则都来自官方文档加实战验证。

用祈使句，别用陈述句。写“使用TypeScript严格模式”，而不是“本项目使用了TypeScript严格模式”。前者是命令，模型知道要执行；后者是描述，模型可能只当背景信息读过去。CLAUDE.md是写给一个要干活的智能体的，每一条都该是它能直接照办的指令，不是项目介绍。

写具体到能验证，别写正确的废话。“写干净的代码”“注意性能”这种话等于没说，因为它无法转化成具体动作。换成“用2空格缩进”“接口处理函数放在src/api/handlers/”“提交前先跑pnpm test”——每一条都具体到能直接检查它做没做到。官方给的对照很经典：写“Use 2-space indentation”而不是“Format code properly”。一个简单的自检标准：如果一条规则你没法判断它到底有没有遵守，那它就太虚了，要么改具体，要么删掉。

举个真实的对照体会这种差别。早先有条规则写的是“注意接口的错误处理”，听着挺对，但模型该漏还是漏——因为“注意”到底要它干嘛它不知道。后来改成三条具体的：“每个接口处理函数必须用try-catch包住”“错误响应统一用src/utils/apiError里的格式”“校验失败返回422、未授权返回401”。换完之后，它写新接口时的错误处理立马规范了，因为每一条都是它能直接照办的明确动作，不再需要它去揣摩“注意”是什么意思。这个改动没增加多少字，但把一条虚规则变成了三条实指令，遵循度的差别是肉眼可见的。模糊的规则不是“不够好”，是“基本无效”，这点要认清。

用markdown结构分组，别堆成一段。模型扫描结构的方式和人一样，分好标题和要点的内容，比挤成一坨的长段落好读得多、也好遵守得多。把命令、约定、规则各自归到清楚的小节下，别让它在一大段里捞关键信息。实操上有个好用的结构：用几个固定的二级标题把内容分门别类——技术栈、命令、约定、规则，每类下面用短句列点。这样模型要找“测试命令是什么”，直接去“命令”那节就行，不用在一大段里大海捞针。结构本身就是一种压缩，它帮模型更快定位到该执行的那条，等于变相提升了遵循度。前面那三个模板用的就是这个骨架，照着套不会错。

关键规则用强调标记顶起来。对那些绝对不能破的底线，用IMPORTANT、MUST、NEVER、ALWAYS这类词标出来，相当于在一堆指令里给最要紧的几条加了重音。模型对这种显式强调是有反应的，能把它们的优先级抬上去。但别滥用，全篇都是IMPORTANT等于没有重点。

盯死200行这条线。前面说过，越长遵循度越差。把200行当成一个警戒线：一旦超了还在涨，基本可以断定混进了不该放的东西——长篇解释、多步骤流程、和README重复的内容。该清理了，而不是继续加。这条线不是死规定，但它是个特别好用的体检指标。值得提醒的是，@import引进来的内容也算进总量——它在启动时照样全量加载，所以靠把内容拆进几个被import的文件来“显得短”是自欺欺人，上下文该占还是占。真要给上下文减负，只有两条路：要么把内容彻底删掉或挪去README、Skill，要么用前面说的路径作用域让它按需加载。单纯搬家不解决问题。

文件太长了怎么拆？

项目一复杂，CLAUDE.md确实容易撑大。硬塞进一个文件会触发遵循度下降，正确的做法是拆，官方给了两套机制。

用@import把内容引出去。CLAUDE.md支持@路径语法，能把别的文件引进来，相对路径和绝对路径都行。比如把命令清单单独放进docs/commands.md，在CLAUDE.md里写一行@docs/commands.md引用它。这样做的好处一是组织清晰，二是能和README共用同一个事实源——两边都@导入那个文件，改一处两边同步，不用维护两遍。要注意一点：@import只是帮你把文件组织得整齐，被导入的内容启动时照样全量加载进上下文，所以它解决的是“可维护性”，不解决“省上下文”。真要省上下文，得靠下面这套。

用.claude/rules/做路径作用域。这是更狠的一招。把规则拆成多个文件放进.claude/rules/目录，每个文件管一个主题（testing.md、api-design.md），还能在文件头用YAML的paths字段绑定生效范围。比如一条规则只对src/api/**/*.ts生效，那它就只在模型碰这些文件时才加载进上下文，平时根本不占地方。这等于把“所有规则一股脑常驻”变成了“按需加载”，对大项目是质的提升。没绑paths的规则文件则和主CLAUDE.md一样常驻。

路径作用域在monorepo里尤其救命。设想一个仓库里前端、后端、基础设施三套代码并存：前端要React的规矩、后端要Python的规矩、infra要Terraform的规矩。如果全塞进一份CLAUDE.md，模型改前端时还得连带读一堆Python和Terraform的规则，纯属噪音、还占上下文。改成路径作用域后，React规则绑frontend/**、Python规则绑backend/**、Terraform规则绑infra/**，模型碰哪块就只加载哪块的规矩，干干净净。这种“规则跟着文件走”的设计，是大项目把上下文用精细的核心手段。这套作用域机制、加上自动记忆这些更深的层面，站内的CLAUDE.md记忆术那篇专门拆过，想把大项目的上下文管理做到位值得读。

不用手写，/init能生成吗？

能，而且强烈建议从/init起步，别对着空文件硬憋。

在项目里跑/init，Claude Code会分析你的代码库，自动生成一份带构建命令、测试方式、它发现的项目约定的CLAUDE.md草稿。如果已经有CLAUDE.md了，它不会覆盖，而是给改进建议。这一步能帮你省掉从零开始的摩擦，拿到一个有模有样的底子。

还有个不少人不知道的新玩法：设环境变量CLAUDE_CODE_NEW_INIT=1，能开启一套交互式的多阶段流程。这时/init不只生成CLAUDE.md，还会问你要不要顺带配Skill和Hooks，然后派一个子代理去探索你的代码库、通过追问补全细节，最后给你一份可审阅的方案再落盘。对一个想一次性把基础设施搭起来的新项目，这个交互式模式比传统的/init省事不少。

但要切记：/init生成的是草稿，不是终稿。它从代码里能扒出来的是表层约定，那些它猜不到的——你团队特有的偏好、踩过的坑、业务上的硬规则——得你自己加。生成完第一件事是精简：删掉它列的、但linter已经管了的；删掉太泛的废话；把真正重要的几条顶上去。一份好的CLAUDE.md几乎都是“生成一版，再人工砍掉一半”砍出来的。

写完怎么知道它到底有没有用？

很多人写完CLAUDE.md就扔那了，从不验证，结果它早就名存实亡了都不知道。写完该做两件事。

一是测试遵循度。方法很简单：让它干一件本该触发某条规则的任务，看它做没做到。比如你写了“提交前先跑测试”，那就让它改点东西然后提交，看它有没有自觉跑测试。没有，说明这条规则要么写得太虚、要么和别处冲突，得调。这个验证不用每条都做，挑那几条你最在意的关键规则试一遍就行。

二是用/memory看它到底加载了哪些文件。/memory命令会列出当前会话加载的所有CLAUDE.md、本地配置和规则文件，还能直接打开编辑。如果你写的某个文件压根没出现在列表里，那它根本没被加载，规则当然不生效——这种“放错位置”的低级问题，靠/memory一眼就能查出来。它还能帮你审计自动记忆里攒了些什么。

还有最关键的一条认知：如果一条规则反复不被遵守，别再跟它较劲，改用hook。CLAUDE.md终究是软约束，对“必须在某个时刻执行”的事——比如每次提交前必须跑lint、绝对不许读密钥文件——它做不到100%保证。这种真正不能松动的红线，该写成hook，在固定的生命周期节点上以shell命令的形式强制执行，做不到就直接拦下来。判断很简单：希望它“尽量这么做”用CLAUDE.md，要求它“必须做到、做不到就阻断”用hook。怎么配hook兜住流程红线，站内的Hooks指南那篇有完整写法。把软的交给CLAUDE.md、硬的交给hook，是配置这套东西最该有的分工意识。

一份CLAUDE.md从臃肿到精简，到底改了什么？

原则讲再多，不如看一份真东西怎么改出来的。这是保哥经手的一个出海独立站项目，前后对比很说明问题。

最初那份CLAUDE.md快300行，是团队几个人陆陆续续往里堆的。开头四十多行讲“项目背景”——这站当初为什么用某套技术、中间换过几次方案、各自的取舍理由，洋洋洒洒像篇技术博客。中段塞了一整套发布流程，从拉分支到推上线足足二十几步，写得倒是详细。后面又抄了一长串ESLint已经强制的格式规则，还混着两三个开发者各自的工具偏好。结果呢？模型经常忘记最要紧的那几条业务硬规则，比如“价格字段一律用整数存分、不许用浮点”——这条被埋在第两百多行，基本等于没写。

改的时候做了几件事。第一刀砍背景：开头那四十多行项目历史，整段搬去README，CLAUDE.md里一个字不留——模型执行任务根本不需要知道“当初为什么”。第二刀抽流程：那套二十几步的发布流程，整个抽成了一个Skill，CLAUDE.md里只留一句“发布走release这个Skill”。这样平时它不占上下文，真要发布时才加载。第三刀删重复：ESLint管的格式规则全删，工具卡死的事不用文字再提醒。第四刀分家：几个人的个人工具偏好挪进各自的CLAUDE.local.md，团队那份只留共识。

砍完，CLAUDE.md从近300行缩到了55行，全是事实和硬规则：技术栈、命令、目录约定、几条业务底线，每条都用祈使句、都具体到能验证，最要紧的“价格用整数存分”这种规则还加了IMPORTANT顶在显眼处。效果立竿见影——之前反复要纠正的那几个错，基本不再犯了。这个案例最反直觉的地方在于：内容砍掉八成，遵循度反而大涨。因为模型的注意力是有限的，你把噪音清掉，它才看得见真正要紧的信号。这也是这篇从头讲到尾的那句话——CLAUDE.md不是写得越多越好，是写得越准越好。

三个能直接抄的模板长什么样？

讲了一堆原则，给三个能直接改的骨架，对照着填自己的项目就行。注意它们都很短——这正是重点。

模板一·个人全局配置（放~/.claude/CLAUDE.md，对所有项目生效）：

# 个人偏好
- 优先函数式写法，变量名要有描述性
- 单个函数尽量不超过40行
- 回答用中文

# 提交习惯
- 提交前必须跑通lint
- 小步频繁提交，一次只做一件事
- 不留TypeScript类型错误

模板二·前端项目配置（放项目根./CLAUDE.md，提交进Git团队共享）：

# 技术栈
Next.js 15 + TypeScript + Tailwind + Prisma + PostgreSQL

# 命令
- 开发：pnpm dev
- 测试：pnpm test
- 构建：pnpm build
- 数据库迁移：pnpm db:migrate

# 约定
- 文件名kebab-case，组件名PascalCase，常量UPPER_SNAKE_CASE
- 接口处理函数放在 src/api/handlers/

# 规则
- 组件一律函数式，Props必须有TypeScript接口
- 必须处理loading和error状态
- NEVER 使用 any 类型

模板三·Python后端配置：

# 技术栈
Python 3.12 + FastAPI + SQLAlchemy 2.0 + PostgreSQL 16 + Redis

# 命令
- 启动：poetry run uvicorn app.main:app --reload
- 测试：poetry run pytest
- 格式化：poetry run ruff format

# 规则
- 遵循 PEP 8，行宽88字符
- 所有函数加类型注解
- 用Pydantic做数据校验
- IMPORTANT: 数据库改动必须配Alembic迁移脚本

三个模板的共同点：没有一句废话，全是事实和硬规则，结构清楚，每条都具体到能验证。你的真实文件可能比这稍长，但方向应该是这样——短、准、可执行，而不是面面俱到。

哪些是最常见的CLAUDE.md反模式？

最后把踩得最多的几个坑集中列一遍，写完对照着排查一遍，能避开八成问题。

写成长篇说明书。500行起步，混进项目历史、架构演进理由、团队文化。这是头号反模式，直接导致关键规则被淹没、遵循度崩盘。解药是砍：解释挪README，流程抽Skill，只留事实和硬规则。

规则太模糊。“写干净的代码”“注意性能”“保持一致”——这些等于没写，因为无法转成动作。每条规则都该过一遍“这能验证吗”，不能验证就改具体。

混入README的内容。把项目背景故事、安装介绍、功能列表一股脑搬进来。记住分工：README给人看、偏解释，CLAUDE.md给AI看、偏命令。这两个文件的根本区别，站内的CLAUDE.md和README有什么区别那篇专门拆过，分不清的话先看那篇。

重复linter已经管的事。ESLint、Prettier强制的格式还往CLAUDE.md里抄一遍，纯占地方。工具能自动卡死的，就别再用文字提醒它。

写完就忘，从不更新。项目在变，CLAUDE.md却停在三个月前，里面一半规则已经过时甚至和现状冲突。养成习惯：每次它犯了本该避免的错，就回头补或改一条；定期通读清掉过时和打架的内容。CLAUDE.md是活的，不是写一次就完事的。有个低成本的维护节奏值得推荐：把“更新CLAUDE.md”绑进你的日常——每当你在对话里又一次手动纠正它、或者code review又挑出一个它本该知道的惯例，当场就花十秒往CLAUDE.md里补一条。这种随手维护比攒到某天“专门整理一次”靠谱得多，因为后者基本不会发生。一份长期生效的CLAUDE.md，都是这么一条条养出来的，不是一次写成的。

个人偏好塞进共享配置。把“我喜欢用某个调试工具”这种纯个人的东西写进提交了Git的项目CLAUDE.md，污染了全团队的上下文。个人的东西放CLAUDE.local.md并加进gitignore，或者放你自己的全局配置，别混进团队共享的那份。

把这些反模式反过来，其实就是一份好CLAUDE.md的样子：短、具体、只装事实和硬规则、分工清楚、持续更新。它不需要写得多全，需要写得多准。配好了，你会实实在在感觉到——它终于“懂你的项目”了，那些重复的解释和纠正，再也不用说第二遍。

常见问题解答

CLAUDE.md写了AI却不照做，是它的问题还是我的问题？

九成是写法问题。它是每次会话注入的软约束，不是强制配置，写得模糊、太长、自相矛盾，遵循度就会垮。先检查这条规则够不够具体、文件是不是太长淹没了重点、几份CLAUDE.md之间有没有打架。真正必须执行的事，别指望它自觉，改用hook。

CLAUDE.md到底写多长合适？

越短越好，官方建议单文件压在200行以内。没有死字数，但一旦超200行还在涨，基本是混进了不该放的东西——长解释、多步骤流程、和README重复的内容。该清理而不是继续加。每一行都是每次会话反复消耗的上下文。

文件太大了，是该用@import还是.claude/rules/？

看你要解决什么。@import是把内容引出去让文件组织更整齐，但被导入的内容启动时照样全量加载，不省上下文。.claude/rules/能给规则绑定paths路径作用域，只在碰到匹配文件时才加载，真正省上下文。要省上下文用后者，只为整理结构用前者。

该自己手写还是用/init生成？

从/init起步，再人工精简。它能自动扒出构建命令、测试方式和项目约定，给你一个底子，省掉从零硬憋的摩擦。但它只能发现表层约定，团队特有的偏好、踩过的坑得你自己加。生成完第一件事是砍——删掉linter已管的、太泛的，把关键规则顶上去。

怎么验证CLAUDE.md到底有没有生效？

两招。一是让它干一件本该触发某条规则的任务，看它做没做到，没做到就说明规则太虚或有冲突。二是用/memory命令查当前会话加载了哪些文件，如果你写的文件没出现在列表里，说明放错了位置根本没被加载。挑你最在意的几条关键规则验证就够，不用每条都测。