CLAUDE.md 是什么？------AI 协作的"项目手册"
你有没有遇到过这种情况------ 当用 Claude Code 接手一个新项目，你说"帮我启动这个项目"，它可能会回答："你可以运行 npm start 或者 yarn dev，具体要看项目的配置。"
它说的没错，但等于没说。因为它不知道这个项目用什么包管理器、项目有没有特殊的启动方式、测试用什么框架。它只能给一个"通用答案"。
那问题出在哪？
Claude 不知道你的项目是什么样的。
它很聪明，但它不了解你的项目背景。它不知道你的技术栈、不知道你的目录结构、不知道你的编码规范。它就像一个第一天入职的工程师------有能力，但什么都不知道。
CLAUDE.md 就是用来解决这个问题的。
1.1 CLAUDE.md 到底是什么？
一句话说清楚：
CLAUDE.md 是放在项目根目录的"给 AI 看的 README"。
它告诉 Claude 你的项目是什么、怎么跑、有什么约定。
文件名固定为 CLAUDE.md（大写），放在项目根目录。Claude Code 启动时会自动读取这个文件，把里面的内容作为"项目背景"加载到上下文中。
一个最简单的 CLAUDE.md 长这样：
markdown
# My Project
## 技术栈
- 前端：React 18 + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL
## 开发命令
- 安装依赖：npm install
- 启动开发服务器：npm run dev
- 运行测试：npm test
- 构建：npm run build
## 编码规范
- 使用 TypeScript 严格模式
- 组件文件使用 PascalCase
- 样式使用 CSS Modules有了这个文件之后，你再问 Claude "帮我启动这个项目"，它会直接说"运行 npm run dev"，而不是给你一堆猜测。
1.2 CLAUDE.md 可以放在哪些地方？
CLAUDE.md 不是只能放在项目根目录。实际上，它可以在三个层级存在，每个层级管不同的范围。
用户级：~/.claude/CLAUDE.md
放在你的 home 目录下，对你所有项目生效。适合写个人偏好：
markdown
# 我的个人偏好
- 代码使用双引号而不是单引号
- 注释用中文写
- 优先推荐 React 方案
- 回答问题时用中文这里的配置对所有项目都生效。你不必在每个项目的 CLAUDE.md 里都重复写这些。
项目级：<项目根目录>/CLAUDE.md
放在项目根目录，对当前项目生效。适合写项目特有信息（技术栈、命令、规范）。
这是最常用的层级，也是前两篇重点讲的。
另外，项目级也可以放到： <项目根目录>/.claude/CLAUDE.md 下。
子目录级：<项目>/<子目录>/CLAUDE.md
放在项目内的子目录中，对特定目录生效。适合 monorepo 中的子包或大型项目中的模块。
my-monorepo/
├── CLAUDE.md # 全局规范（根目录）
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # 前端应用特有规范
│ └── admin/
│ └── CLAUDE.md # 后台应用特有规范
└── packages/
└── shared/
└── CLAUDE.md # 共享库规范优先级规则
当多个层级的 CLAUDE.md 同时存在时，优先级是：
子目录级 > 项目级 > 用户级越具体的优先级越高。
具体规则：
- Claude Code 启动时会读取所有层级的 CLAUDE.md
- 如果同一个信息在不同层级出现，就近原则------离当前工作目录最近的优先
- 不会互相覆盖，而是合并------不同层级的内容都会加载到上下文中
举个例子：
用户级（~/.claude/CLAUDE.md）：
"代码使用双引号"
项目级（/project/CLAUDE.md）：
"技术栈：React + TypeScript"
"代码使用单引号" ← 覆盖用户级的双引号
子目录级（/project/apps/admin/CLAUDE.md）：
"启动命令：pnpm admin dev" ← 子目录特有的命令
"代码使用单引号" ← 跟项目级一致，不冲突最终加载到 AI 上下文中的是：
代码使用单引号 （来自项目级，覆盖用户级）
技术栈：React + TypeScript （来自项目级）
启动命令：pnpm admin dev （来自子目录级）这个优先级设计的意义在于：个人偏好不干扰项目规范，项目规范不被个人偏好覆盖。
1.3 为什么需要 CLAUDE.md？
你可能觉得：这些信息不是我能自己告诉 AI 的吗？
你当然可以每次手动告诉它。但CLAUDE.md 的价值在于三点：
第一，自动化。
你不说，AI 也知道。CLAUDE.md 在 Claude Code 启动时自动加载，不需要你每次手动交代"我们项目用 React 啊"。
第二，精确化。
手动交代往往丢三落四。你会说"我们项目用 React"，但可能忘了说"我们用 pnpm 而不是 npm""我们不用 class component""我们的测试必须覆盖 80%"。
CLAUDE.md 写清楚之后，AI 不会忘记。
第三，标准化。
团队里每个人跟 AI 协作的方式可能不一样。张三告诉 AI"用 double quotes"，李四告诉 AI"用 single quotes"。有了 CLAUDE.md，所有人都用同一份规范。
1.4 CLAUDE.md vs README.md
很多人第一次接触 CLAUDE.md 会问：这不就是 README.md 吗？
不是。虽然都是 Markdown 文件，但服务对象完全不同。
| 对比项 | README.md | CLAUDE.md |
|---|---|---|
| 服务对象 | 人类开发者 | AI 助手 |
| 阅读方式 | 跳读、扫读 | 全部读取 |
| 内容风格 | 吸引人、展示项目价值 | 精确、结构化、可执行 |
| 关注点 | 项目是什么、为什么用 | 项目怎么跑、有什么约定 |
| 更新频率 | 低频（大版本更新才改） | 高频（项目变化随时更新） |
一个典型的 README 会花大量篇幅介绍"这个项目是干什么的""解决了什么问题""有什么特色功能"。这些对人类很重要，但对 AI 来说------它不在乎。
AI 在乎的是：
- 这个项目用什么技术栈？
- 怎么安装和启动？
- 代码有什么规范？
- 目录结构是怎么组织的？
- 有哪些不能碰的东西？
CLAUDE.md 就是把这些信息用 AI 最容易理解的方式写下来。
另一个关键区别：README 写了不一定会有人读，但 CLAUDE.md 写了 AI 一定会读。
因为 Claude Code 的机制就是每次启动时自动加载 CLAUDE.md。你写了，它就看到了。不写，它就不知道。
1.5 CLAUDE.md 能写什么？
CLAUDE.md 的内容没有严格限制，你的项目需要什么就写什么。但根据经验，这几个方向是最有价值的：
项目概览
告诉 AI 这个项目是什么，有什么特殊背景：
markdown
# 电商后台管理系统
这是一个面向公司内部运营团队的后台系统，不是对外产品。
主要功能包括订单管理、商品管理、用户管理和数据报表。技术栈
明确告诉 AI 用什么技术，避免它给出不相关的建议：
markdown
## 技术栈
- 框架：React 18 + Next.js 14 (App Router)
- 语言：TypeScript (strict mode)
- 样式：Tailwind CSS
- 状态管理：Zustand
- 测试：Vitest + Testing Library
- 包管理：pnpm开发命令
把常用命令写清楚，AI 就不需要猜了：
markdown
## 开发命令
- pnpm install --- 安装依赖
- pnpm dev --- 启动开发环境（端口 3000）
- pnpm build --- 生产构建
- pnpm test --- 运行所有测试
- pnpm lint --- 代码检查
- pnpm type-check --- TypeScript 类型检查编码规范
这是最有价值的部分------让 AI 生成的代码符合你的标准：
markdown
## 编码规范
- 组件使用函数组件 + Hooks，不使用 class 组件
- 文件名使用 kebab-case（如 user-profile.tsx）
- CSS 类名使用 kebab-case
- Git commit 使用 conventional commits 格式
- 不允许使用 any 类型
- 所有 API 请求必须放在 services/ 目录下
- React Query 的 query key 统一管理在 src/lib/query-keys.ts目录结构
让 AI 知道代码放在哪，生成的代码不会放错位置：
markdown
## 目录结构
src/
├── app/ # Next.js App Router 页面
├── components/ # 共享组件
│ ├── ui/ # 基础 UI 组件
│ └── shared/ # 业务共享组件
├── services/ # API 请求
├── stores/ # Zustand stores
└── utils/ # 工具函数边界与约束
告诉 AI 什么不能做，这比告诉它什么能做更重要：
markdown
## 约束
- 不要修改 src/lib/ 下的文件，除非有明确要求
- 数据库 migration 必须经过 review
- 不要引入新的依赖，除非讨论过
- API 接口的修改需要同步更新类型定义1.6 CLAUDE.md 会占用上下文吗？
会，但你不用担心。
CLAUDE.md 的内容会被加载到 system prompt 中，但它通常很短（几百字到一两千字），对一个 100K+ 的上下文窗口来说，占比很小。
而且它的价值远大于它占用的那点空间------没有这些背景信息，AI 需要多轮对话才能搞清楚你的项目，那消耗的 token 反而更多。
好的 CLAUDE.md 不是浪费上下文，而是节省上下文。
1.7 小结
- CLAUDE.md 是给 AI 看的项目说明书，Claude Code 启动时自动加载。
- 它的价值：自动化 （不需要每次手动交代）、精确化 （不会漏信息）、标准化（团队统一）。
- CLAUDE.md 支持三个层级：用户级 （~/.claude/CLAUDE.md，所有项目生效）、项目级 （项目根目录，当前项目生效）、子目录级（子目录，特定模块生效）。
- 优先级规则：子目录级 > 项目级 > 用户级，越具体优先级越高。
- CLAUDE.md 不是 README.md------README 给人看，CLAUDE.md 给 AI 看。
- 值得写的内容：项目概览、技术栈、开发命令、编码规范、目录结构、边界约束。
看完你可能会觉得：这不就是一个配置文件吗，有什么好写的？
但下一篇我会让你看到，一个好的 CLAUDE.md 可以让 AI 从"通用助手"变成"你的项目的专属助手"------效果天差地别。
下一篇：手写一个 CLAUDE.md------从空白到最佳实践]()