CLAUDE.md 怎么写？给 AI 立项目规则
CLAUDE.md 是一个放在项目根目录、给 AI 编程助手自动读取的”项目说明书”——它告诉 AI 这个项目用什么技术栈、目录怎么放、命令怎么跑、规范要遵守什么，让 AI 一上手就懂规矩。
如果你用 Claude Code 写代码，经常发现它”猜”错你的项目约定——用错包管理器、把文件放错目录、不知道怎么跑测试，那问题多半出在你没给它一份 CLAUDE.md。这篇讲清楚它是什么、怎么自动生成、该写什么、写多长，文末给一份可直接抄的模板。
为什么需要 CLAUDE.md
AI 助手每开一个新会话，对你的项目都是”零记忆”。它能读代码，但读不出那些没写在代码里的约定：你团队偏好哪种命名、为什么这个目录不能动、上线前必须跑哪条检查命令。
没有 CLAUDE.md 时，你只能每次会话都重复交代一遍，或者眼睁睁看它踩坑再纠正。CLAUDE.md 就是把这些”口头规矩”一次性写下来、永久生效：每次启动会话，AI 会自动把它加载进上下文,当成最高优先级的指令来遵守。
一句比喻：CLAUDE.md 就是给 AI 的”新人入职文档”。新人入职你会给一份《这个项目你得知道的事》,CLAUDE.md 就是写给 AI 同事看的那一份。
举个我踩过的真实坑：一个 monorepo 项目,根目录和 packages/web 都有 package.json,但真正跑测试的入口在 packages/web 下,而且这个包用 pnpm,同仓库另一个 Python 服务用 poetry。没写 CLAUDE.md 之前,AI 会习惯性在根目录跑 npm test,报一堆找不到脚本的错;或者改完 Python 服务的代码,顺手在根目录跑了 npm install,把 lockfile 搅乱。这类问题不是 AI”笨”,是它没有任何信息来源能知道”这个仓库有两套依赖体系,分别归两个目录管”。把这条写进 CLAUDE.md 之后,类似错误基本消失——因为规则已经不依赖你”记得提醒”了。
CLAUDE.md 是怎么工作的
机制很简单,分三步：
- 位置约定：文件放在项目根目录(也可以放在子目录,作用域是该目录及其子文件)。AI 助手启动时会自动扫描并读取。
- 注入上下文：读到的内容会被拼进每次对话的系统提示里,优先级高于普通对话。所以写在里面的规则,AI 会”始终记得”。
- 持续生效：只要文件在,无论换多少个会话、换谁来用这个项目,规则都一致。这也是它比”在对话里临时叮嘱”强的地方——约定沉淀进了仓库,而不是某个人的脑子。
正因为它会占用每次对话的上下文,所以篇幅要克制——这点后面专门讲。
用 /init 自动生成第一版
不用从空白文件开始。在项目根目录跑 Claude Code,输入斜杠命令 /init,它会自动扫描你的代码库,分析技术栈、目录结构、常用脚本,然后生成一份初始的 CLAUDE.md。
/init 生成的版本通常已经覆盖了八九成:它能认出你用的框架、包管理器、测试命令。你要做的是在它基础上删改——删掉它猜错的、补上它读不出来的(比如团队偏好、业务约定)。
具体命令名、行为细节可能随版本调整,以官方文档为准;思路是不变的:先自动生成,再人工精修。
CLAUDE.md 该写什么
挑 AI 最容易猜错、且写下来收益最高的东西写。建议覆盖这几类:
| 类别 | 写什么 | 例子 |
|---|---|---|
| 技术栈 | 语言、框架、关键依赖版本 | ”Astro + React islands + Tailwind,包管理器用 pnpm” |
| 目录结构 | 关键目录的作用、哪些不能动 | ”页面在 src/pages/,内容集合在 src/content/“ |
| 常用命令 | 跑测试、构建、本地启动的命令 | ”构建:pnpm build;单测:pnpm test” |
| 代码规范 | 命名、风格、提交信息约定 | ”组件用 PascalCase;提交信息用中文” |
| 禁区与陷阱 | 容易踩的坑、必须遵守的红线 | ”改完路由必须同步更新 sitemap” |
核心判断标准:这条规则,AI 不知道就会做错吗? 是,就写;只是”锦上添花”或代码里一看就懂的,别写。
再补一条很多人漏掉的:“红线”要写成祈使句、带后果,而不是描述句。 对比一下:
- 弱:“路由和 sitemap 有关联。“——AI 读完不知道该干嘛。
- 强:“改完
src/pages/下任何路由,必须同步跑pnpm gen:sitemap,否则线上 sitemap 会漏页。“——AI 读完知道触发条件、要跑的命令、不跑的后果。
同理,“提交信息用中文”不如”提交信息用中文,格式为 类型(范围): 描述,例如 fix(登录): 修复验证码校验失败”——给一个可直接照抄的例子,比抽象规则好用得多。AI 对”举例说明”的服从度,通常比对”抽象规范”高。
CLAUDE.md 不该写什么,以及写多长
最常见的错误是写太长、太啰嗦。 记住:它每次都吃你的上下文预算,越长越稀释 AI 对重点的注意力。
不该写的:
- 代码里能直接读到的信息(把整个目录树抄一遍——没必要,AI 自己会看)。
- 长篇大论的背景故事、设计理念(放 README 或 docs,不放这里)。
- 短时效内容(临时的 TODO、某次重构的进度——这些会过期)。
判断口诀:简洁、直给、只留”AI 不知道就会错”的硬约定。 宁可分多个小节用清单列,也别写成一大段散文。如果内容确实多,可以在 CLAUDE.md 里只放核心约定,用一行指路”详见 docs/xxx”,让 AI 按需去读。
和 Codex 的 AGENTS.md 是一回事吗
是同一思路的不同名字。Codex 用的是 AGENTS.md,作用和 CLAUDE.md 几乎一样——都是放在项目里、给 AI 助手读的项目约定文件,内容结构也大同小异(技术栈、命令、规范)。
所以如果你同时用 Claude Code 和 Codex,两份文件写的东西可以高度复用:把项目约定整理一遍,分别命名落进各自的约定文件即可。想深入了解两个工具的差异,可以看Claude Code 教程。
不同工具对约定文件的具体命名、加载规则可能不同,以各自官方文档为准;但”用一个静态文件给 AI 立规矩”这个范式是相通的。
一份可抄的最小模板
# 项目约定
## 技术栈
- 语言/框架:______
- 包管理器:______(命令统一用它,别混用)
## 目录
- 源码:src/
- 测试:______
- 不要改:______(生成产物 / 第三方)
## 常用命令
- 本地启动:______
- 构建:______
- 测试:______(改完代码必须跑)
## 规范
- 命名:______
- 提交信息:______
- 红线:______(例如:改路由必须同步 sitemap)
填空即可。先用 /init 生成,再对照这个骨架查漏补缺。Cursor 用户的等价物是 .cursorrules / Project Rules,写法思路一致,可参考 Cursor Rules 最佳实践(规划中)。
进阶用法:分层、复用、维护
单文件够用的项目占多数,但项目大到一定规模,光一份根目录的 CLAUDE.md 会撑不住。这里给三个进阶技巧,都是我们自己在多站点仓库里用出来的。
1. 按目录分层。 前面说过 CLAUDE.md 可以放在子目录,作用域限定在该目录及其子文件。实操上很好用:根目录放”全局硬约定”(语言、提交规范、部署方式这种全项目通用的),子目录(比如 apps/admin/、packages/ui/)各放一份只讲该子包特有的东西(它的启动命令、它专属的组件规范)。AI 进入某个目录工作时,会同时吃到根目录的全局规则和当前目录的局部规则,不用把所有细节都堆进一个文件。
2. 用 @ 语法引用其他文件,别复制粘贴。 如果某段规则在多个地方都要用(比如详细的接口设计规范、数据库字段命名表),别在 CLAUDE.md 里复制一份长文——写一行 详见 @docs/api-design.md,把内容维护在专门的文档里,CLAUDE.md 只做”路标”。好处是:那份详细文档改了,CLAUDE.md 不用跟着改;而且没必要时 AI 也不用被迫加载整份长文档进上下文。具体语法以官方文档为准,思路是”CLAUDE.md 管索引,细节文档管内容”。
3. 当成代码一样维护,而不是写一次就扔那儿。 CLAUDE.md 最容易过期的场景是:团队约定变了(比如从 npm 切到 pnpm),但没人记得回去改这份文件,结果 AI 一直按旧约定行事,反而帮倒忙。建议的做法是:把它纳入 code review——谁的 PR 涉及了项目约定的变化(新增命令、改目录结构、换技术栈),顺手改一下 CLAUDE.md,当成和改 README 一样的义务;定期(比如每次大版本迭代后)通读一遍,删掉过期条目。一份长期没更新、内容和现状对不上的 CLAUDE.md,比没有还糟——因为它会主动”教”AI 犯错。
常见问题
CLAUDE.md 必须放在根目录吗?
放根目录作用于整个项目,最常用。也可以放在子目录,这样规则只对该目录及其子文件生效——适合 monorepo 里给某个子包单独立规矩。
CLAUDE.md 越详细越好吗?
不是。它每次都占用 AI 的上下文预算,太长反而稀释重点、拖慢响应。原则是简洁、只写”AI 不知道就会做错”的硬约定,背景故事放 README。
我没用过命令行,能写 CLAUDE.md 吗?
能。它就是一个普通的 Markdown 文本文件,用任何编辑器都能写。更省事的办法是在 Claude Code 里跑 /init 自动生成第一版,你只需在它基础上改几句。
CLAUDE.md 和 README 有什么区别?
README 是给人看的项目介绍;CLAUDE.md 是给 AI 看的操作约定。前者讲”这是什么项目”,后者讲”你(AI)动手时要遵守什么”。两者可以并存,内容尽量别重复。
CLAUDE.md 和 Codex 的 AGENTS.md 能共用吗?
内容能高度复用,但文件名不同——Claude Code 读 CLAUDE.md,Codex 读 AGENTS.md。同时用两个工具时,把约定整理一遍,分别落进两个文件即可。
👉 看看我们的 AI 编程实战体系课,或逛 AI 编程教程大全 把基本功打扎实。