最近总有同事问我：每次新开一个 Claude Code 会话，它怎么知道咱们项目里哪些命令能跑、哪些文件不能乱动？你是不是每次都贴一大段规则进去？
真不是。这些东西我都放在一份叫CLAUDE.md的文件里了。
CLAUDE.md就是 Claude Code 的项目专属上下文入口。把它放在项目根目录，Claude Code 启动时会自动读取，相当于给 AI 发了一本“入职手册”——项目怎么启动、代码风格是什么、哪里藏了坑，一次性讲明白，之后每轮对话它都带着这份记忆工作。这篇我会从加载机制讲起，把全局、项目、子目录三层配置怎么写说透，再聊上下文体积控制、实际配置里常见的坑，以及团队协作时的进阶玩法。刚接触 Claude Code 的新手，和已经用了一段时间但总觉得它“不够懂项目”的老手，都能从中拿到直接能用的东西。
1. CLAUDE.md 的加载机制：为什么它比对话里反复交代更可靠
很多人误以为 CLAUDE.md 就是把项目说明文档换个名字。其实不是。它之所以能成为 AI 编码流程里最值得投入的一份文件，核心在于它的加载机制和生效方式，跟普通文档完全不一样。
1.1 没有 CLAUDE.md 时，Claude Code 是什么状态
我第一次用 Claude Code 的时候，直接在项目里给它派活。它确实能读代码、能改文件，但每次新开会话，它就跟失忆一样：上个月定好的文件命名规则忘了，测试命令也经常搞错，让它改一个模块，结果把不相关的文件也动了一遍。
后来我想明白了，这不是模型能力的问题，是上下文没给够。AI 编码工具的能力上限，很大程度上取决于它启动时能看到什么。你在对话里临时交代的东西，只对当前会话有效；一旦会话关闭，或者对话超过上下文窗口被截断，一切都归零。CLAUDE.md 解决的就是这个“归零”问题。
1.2 加载时机与生效范围
CLAUDE.md 的加载时机很简单：Claude Code 启动会话时，会在工作目录里查找 CLAUDE.md，找到就自动读入，不需要你在提示词里手动指定。
它的定位更接近“系统提示词”而不是“普通对话内容”。这意味着它会全程留在模型视野里，并且对模型行为的约束力比对话里的临时要求更强。这也是为什么有人觉得 Claude Code 有时候“太固执”——你中途跟它说“这次别管 CLAUDE.md 里的规则”，它也可能继续遵守，因为那部分内容在系统层级的权重更高。
另外要注意，修改 CLAUDE.md 之后，通常要新开会话才会重新加载。正在进行的会话不会实时感知文件变化。我自己的习惯是：改完 CLAUDE.md 后，立刻开一个新会话验证效果，而不是在旧会话里接着聊。
1.3 为什么是 Markdown
CLAUDE.md 之所以用.md后缀，是因为 Markdown 天然适合给大模型当上下文：
- 结构化标题帮助模型快速定位信息
- 列表能压缩冗余表达
- 代码块保持命令的可复制性
- 纯文本格式对 git diff 友好，团队评审改动时一眼就能看出变化
相比之下，把上下文塞在 IDE 配置里或者一个 JSON 文件里，维护成本都高得多。这也是 CLAUDE.md 能在 Claude Code 生态里成为标准配置的根本原因。
提示：CLAUDE.md 不是 README.md 的替代品，也不是写给人类同事看的文档。它的唯一读者是 AI，所以内容组织方式要围绕“AI 执行任务时需要知道什么”来设计。
2. 三层配置：全局、项目与子目录的分工
CLAUDE.md 并不是只能放在项目根目录一个地方，它分三层：全局、项目、子目录。这三层解决的是不同粒度的问题，很多人只用了项目级，等于白白损失了另外两层能力。
2.1 全局配置文件：管住“你这个人”的偏好
全局 CLAUDE.md 在用户主目录下的.claude目录里（macOS/Linux 是~/.claude/CLAUDE.md，Windows 在用户目录下的.claude文件夹）。它管的是“你这个人”的通用偏好，与具体项目无关。我会把这三类内容放进去：
- 默认语言习惯：
代码注释用中文，回复用中文，但保留英文关键词不做翻译 - 通用代码风格：
缩进统一两个空格，变量用驼峰，类名用大写开头 - 通用红线：
不要在没有确认的情况下直接删除文件，涉及破坏性操作先给方案再执行
注意，全局文件里不要写任何跟具体项目绑定的事情，比如某个项目的目录结构、某个服务的启动命令。这些放全局只会污染所有项目。我见过有人把公司老项目的端口号写进全局配置，结果在其他项目里 AI 天天试图访问那个端口，排查了很久才发现是全局文件在作怪。
2.2 项目配置文件：AI 的入职手册
项目根目录的 CLAUDE.md 是绝大多数人最需要认真写的。它的读者不是人而是 AI，所以目标很明确：让 AI 在不翻源码的情况下，快速知道这个项目怎么跑、怎么改、哪里不能碰。
项目级配置建议覆盖四个维度：
- 常用命令：安装、启动、测试、构建、代码检查
- 技术栈与入口：框架、语言、数据库、生产环境入口文件
- 编写规范：接口返回结构、日志方式、文件命名、代码风格
- 禁止事项：高风险操作、不该动的目录、不该引入的依赖
2.3 子目录覆盖规则：大仓库的救命稻草
在一个 monorepo 或者大型仓库里，如果所有规范都塞在根目录一份 CLAUDE.md 里，内容会非常长，而且在某个子目录工作时，根目录里那堆全局规范很多都用不上。
子目录 CLAUDE.md 就是为这种情况设计的：Claude Code 在哪个目录工作，就会优先读取那个目录下的 CLAUDE.md，用它来覆盖根目录的规则。我之前用一个多服务仓库，根目录只写仓库层面的约定，每个服务目录里放一份小 CLAUDE.md，只写这个服务自己的启动命令、端口、特殊约束。效果立竿见影，AI 在具体服务里工作的时候，不会再拿根目录那套规则乱套。
2.4 合并优先级与冲突处理
三层配置不是互斥关系，而是叠加关系：子目录覆盖项目，项目覆盖全局。这个优先级决定了，当你发现 AI 行为不对时，排查顺序应该是：先看当前目录有没有子目录级 CLAUDE.md，再看项目根目录，最后才查全局。
我的经验是：写的时候就不制造冲突。全局只写跟项目无关的通用偏好，一旦发现自己想往全局写规则，先问一句“这个规则在别的项目里也成立吗”，不成立就放到具体项目里。
3. 一份可以直接抄的 CLAUDE.md：结构拆解与写法逻辑
空谈概念没有意义，直接给你一份我现在常用的项目 CLAUDE.md 模板。你可以复制过去，改成自己的项目就能用。
# 项目名称 一句话说明：这个服务做什么，面向谁。 ## 常用命令 - 安装依赖: pnpm install - 启动开发: pnpm dev - 运行测试: pnpm test - 构建: pnpm build - 代码检查: pnpm lint ## 技术栈 - 框架: Next.js 14 App Router - 语言: TypeScript - 数据库: PostgreSQL + Prisma - 样式: Tailwind CSS ## 项目结构 - src/app 页面路由，文件即页面 - src/components UI 组件，按布局/业务/通用拆分 - src/server/api 服务端接口层 - src/server/db 数据库查询与迁移 入口说明：生产环境入口在 src/app/page.tsx，定时任务入口在 src/jobs/index.ts，两个入口不要混用公共工具函数时注意副作用。 ## 编写规范（必须遵守） - 接口返回结构统一为 { code: number, message: string, data: T } - 禁止在组件里直接调用数据库 - 新增页面的时候必须同时补上 metadata - 日志使用项目封装的 logger，禁止 console.log - 中文文案统一放在 messages/zh-CN.ts，禁止硬编码在组件里 ## 禁止事项 - 不要修改 src/server/db/schema.prisma 之前，先说明迁移方案 - 不要引入新的 UI 组件库，已经引入的保持统一 - 不要删除 src/app/(auth) 下的中间件文件 ## 已知的坑 - 修改 UserService 前先读 src/server/services/userService.ts，里面有缓存逻辑 - 运行迁移前必须确认本地数据库版本，否则可能锁表 - 这个项目没有 mock 数据，接口联调依赖本地数据库 seed3.1 命令部分：只写能直接执行的东西
命令部分有一个很容易犯的错：写得像教程。“进入项目目录后运行 npm install，安装完成后运行 npm run dev”，这种表述对模型来说信息密度太低，它反而容易漏掉步骤。
正确做法是每行一个命令，前面加一个简单动词短语，比如安装依赖、启动开发、运行测试。这样 AI 遇到相关任务时，可以直接定位到对应命令去执行，不用再理解自然语言里的隐含步骤。
3.2 项目结构：写职责，不写注释
项目结构部分的关键技巧是：不要只列目录树，要写“职责”和“入口”。AI 读目录树只能知道有什么，写清楚“生产环境入口在 src/app/page.tsx”，它才知道从哪看起。
如果是多入口项目，一定要把每个入口都列清楚，并说明各自的用途。我见过一个项目有 Web 服务、定时任务、消息消费三个入口，CLAUDE.md 里没写清楚，AI 每次改定时任务都会去改到 Web 服务的代码，因为那个文件名字更大、位置更显眼，AI 完全被误导了。
3.3 规范部分：做与不做明确分开
规范部分我建议用两类写法配合。“必须”部分约束质量底线，“禁止”部分直接堵住高风险操作。
对模型来说，“禁止做 X” 比“尽量别做 X”有效得多。“尽量别”是模糊表达，模型会根据自己的理解自由发挥；“禁止”是明确边界，能直接对齐预期。我甚至见过有人把“尽量”改成“必须”后，AI 产出的代码风格明显稳定了一个档次。
3.4 已知的坑：让 AI 学会绕开地雷
这个 Section 经常被人忽略，实际上它对任务质量的影响最大。把项目里容易踩的坑、特殊的缓存逻辑、危险操作的前置条件写清楚，AI 就能在动手之前先避开。
比如“修改 UserService 前先读 userService.ts，里面有缓存逻辑”，这句话可能节省你半小时的 debug 时间。否则 AI 大概率会直接改掉那部分代码，然后缓存逻辑崩了，它还不知道为什么。
4. 控制上下文体积：CLAUDE.md 不是越详细越好
写 CLAUDE.md 有一个反直觉的结论：不是越详细越好，而是越精准越好。原因在于它每时每刻都在占用上下文窗口。
4.1 上下文窗口的真实压力
CLAUDE.md 每次启动都会被完整加载，这意味着它永久占用上下文窗口的一部分。如果你的上下文窗口是 200K tokens，一份 3000 tokens 的 CLAUDE.md 本身不算贵；但如果膨胀到 20000 tokens，占用就非常可观了，对话稍微长一点就容易碰到截断边界。
上下文超过限制后的典型表现是：最早的对话内容被截断遗忘，模型丢失之前已经确认过的决策，越到任务后半段越“笨”，你得反复把之前的结论重新贴回去。控制 CLAUDE.md 的体积，是规避这个问题最便宜的手段。
4.2 我建议的体量上限
给自己定一个体量上限，既能保证质量，又能防止失控。我个人的经验值：
- 稳定在 150 行以内
- Token 消耗控制在 2000 左右
- 超过这个量，就开始反思是不是有内容可以移出去按需引用
哪些内容适合写进 CLAUDE.md，哪些不适合，我是按这张表来判断的：
| 内容类型 | 是否适合写入 | 原因 |
|---|---|---|
| 安装命令、测试命令 | 适合 | 每次都需要，更新频率低 |
| 架构简述、模块职责 | 适合 | 帮助 AI 定位代码 |
| 代码风格、接口约定 | 适合 | 直接影响产出质量 |
| 详细实现原理、教程 | 不适合 | 按需读取文档更划算 |
| 团队流程、会议记录 | 不适合 | 与任务质量弱相关 |
| 历史变更记录 | 不适合 | 容易过时且占据体积 |
4.3 按需引用，不要全部内联
CLAUDE.md 里完全可以写“架构细节参见 docs/architecture.md，遇到架构调整时先读那个文件再动手”，让模型在需要时再去读对应文档。这种写法的上下文开销比把整篇文档塞进去小得多，但在实际效果上几乎一样。对话过程中还可以用 @ 符号直接引用文档，把更详细的内容按需拉进上下文，比把一切都内联在 CLAUDE.md 里干净得多。
4.4 用 /context 确认加载情况
每改完一版 CLAUDE.md，我都会跑一下 Claude Code 的/context命令，看当前会话到底加载了哪些上下文、CLAUDE.md 占了多少量。这是验证精简效果最直接的办法。如果你发现上下文占用比自己预估的高很多，基本可以断定 CLAUDE.md 里塞了不该塞的东西，需要重新梳理。
5. 实践中的坑与我的处理惯例
配置 CLAUDE.md 的过程里，我踩过不少坑，有些坑甚至让整个项目停摆了半天。下面这几个是最常见的，也是我在团队里反复强调的。
5.1 不要把 CLAUDE.md 写成第二份 README
CLAUDE.md 和 README.md 的读者不同。README 面向人，需要背景介绍、安装方式、使用示例；CLAUDE.md 面向 AI，只需要能执行的命令、该遵守的规范和要躲开的坑。
我在项目里见过 README 七百行，CLAUDE.md 直接把它复制了一遍。后果很直接：AI 每轮对话都携带大量用不上的介绍性文字，碰到关键任务反而容易忽略里面夹着的那几条真规则。维护上也是双重负担，改一处漏一处，内容很快就开始互相矛盾。
我的做法是：命令部分和 README 保持完全同步，其他部分各写各的。为了让命令同步不出错，我会把命令统一收敛到 Makefile 或 package.json scripts 里，CLAUDE.md 和 README 都引用同一套命令名，自然就不会分叉。
5.2 过期规则比没有规则更危险
这是我现在最警惕的坑。AI 遵守规则的认真程度远超人类，它不会自动判断 CLAUDE.md 里哪条已经过时。
举一个真实例子：项目当时已经全面迁移到 ES Module，CLAUDE.md 里却一直留着“禁止使用 import 语法，统一用 require”。结果 AI 每次生成新文件都在用 CommonJS，给出理由还是“因为项目规范要求”。你气得想砸键盘，但它确实是在严格执行你的规范。
所以我把 CLAUDE.md 当成一等代码文件来维护：重大重构后必须过一遍，技术栈切换时立刻更新对应小节，提交时放进 code review，队友改代码的同时会看 CLAUDE.md 要不要同步。我甚至会在文件头部加一行“最后更新日期”，提醒自己定期翻。
5.3 敏感信息绝不放进去
CLAUDE.md 的内容会和对话一起发送给模型服务端，所以数据库密码、API key、内网地址、未公开的商业逻辑，一律不要出现。
这个坑一旦踩了很难翻案：日志、历史记录、模型服务端都可能留存。我的做法是在评审 CLAUDE.md 时专门检查一遍有没有敏感字符串，把这条也写进团队 review checklist。
5.4 全局偏好与项目需求打架
不同层级规则冲突时，实际生效顺序一般是子目录覆盖项目，项目覆盖全局。但更重要的不是记住优先级，而是写的时候就不制造冲突。
比如全局写了“代码注释全部用中文”，项目规范却要求“提交到开源仓库的代码用英文注释”，AI 就会陷入两难。我的经验是：全局只写和项目无关的通用偏好，一旦发现自己想往全局写规则，先问一句“这个规则在别的项目里也成立吗”，不成立就放到具体项目里。
5.5 写得太空与写得过细都不行
有些人写出来的 CLAUDE.md 就五行：“这是一个用 Vue 写的后台系统，请遵守项目规范。”这种文件等于没写。另一些人则细到把每个函数的作用都描述了一遍，AI 反而忽略了里面的关键规则。
我的判断标准是：如果一段话不能让 AI 更好地执行任务，无论感觉多有用都要删掉。一句话能说清的命令规范，不要用三句话“解释背景”；一个目录只写职责就行，不要描述这个目录里每个文件是干什么的。
6. 进阶玩法：多模块仓库、团队协作与周边工具联动
当 CLAUDE.md 的基本功扎实以后，可以往更复杂的方向走。下面这几个玩法是我在实践中验证过有实际收益的。
6.1 多模块仓库的子目录配置实践
如果你维护的是一个 monorepo，根目录 CLAUDE.md 只需要写仓库层面的约定：包管理器、lint 规则、仓库结构。每个子包内部再放一份小型 CLAUDE.md，只写这个包的启动命令和特殊约束。
这样做的第一个好处是根目录文件不会膨胀；第二个好处是 AI 在特定包目录下工作时，能准确拿到这个包专属的规则。比如你在packages/admin目录下让它加一个接口，子目录里的 CLAUDE.md 可以直接写“所有接口需要打包在src/routes/admin.ts里”，AI 就不会去碰其他包的东西。
6.2 团队模板与评审流程
团队要想统一 AI 协作质量，最有效的方式是制定一份团队级 CLAUDE.md 模板，规定文件至少包含哪几个 Section。我们团队的模板固定包含：命令、技术栈、项目结构、编写规范、已知坑。
有人提交新的 CLAUDE.md 时，code review 会检查这五个 Section 是否完整、是否与代码现实一致。效果非常明显：两个人接手同一个项目时，AI 的行为不会因为使用者不同而漂移，新人也只需要按模板补内容，不用从零思考“该写什么”。
6.3 对接本地模型或代理时的特殊处理
如果你用 litellm proxy 或者 ollama 这类方案把 Claude Code 接到本地模型上，要特别注意：本地模型的上下文窗口通常比云端小不少，CLAUDE.md 的体积控制就要更苛刻。
在这种场景下，我会把 CLAUDE.md 压缩到几十行，只保留最核心的命令和约束，其余内容全靠 @ 引用按需传入。别指望小窗口模型能长期记住一份五千字的规范，它连一次性读都读不完，更谈不上在长对话里保持遵循。
6.4 把 CLAUDE.md 的方法论迁移到其他工具
CLAUDE.md 这套“用文件承载项目上下文”的思路，在很多 AI 编码工具里都有对应实现。Cursor 里有.cursor/rules，GitHub Copilot 有.github/copilot-instructions.md，Codex 也有自己的AGENTS.md。
一旦你理解了 CLAUDE.md 的精髓——把决策、命令、边界写进版本库，让 AI 按需加载——换工具的迁移成本就很低。你沉淀下来的不是某个特定文件，而是一套“上下文工程”的方法论：用什么粒度组织项目信息，哪些内容必须常驻，哪些按需读取，冲突如何分层。
最后分享一下我接新项目的固定流程：前三天不急着把 CLAUDE.md 写完美，先用初始化功能让它根据现有代码起草一版，补上命令和已知坑，然后边用边改。等到第一周结束，文件基本稳定了，再补上更新日期，进入代码评审流程。CLAUDE.md 的终极目标不是写得多漂亮，而是成为团队对 AI 说“这是我们项目的样子”的那本手册——维护它，和维护代码一样，是每天的日常工作。
