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 长这样：

# 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 目录下，对你所有项目生效。适合写个人偏好：

# 我的个人偏好

- 代码使用双引号而不是单引号
- 注释用中文写
- 优先推荐 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 同时存在时，优先级是：

子目录级 > 项目级 > 用户级

越具体的优先级越高。

具体规则：

1. Claude Code 启动时会读取所有层级的 CLAUDE.md
2. 如果同一个信息在不同层级出现，就近原则——离当前工作目录最近的优先
3. 不会互相覆盖，而是合并——不同层级的内容都会加载到上下文中

举个例子：

用户级（~/.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 这个项目是什么，有什么特殊背景：

# 电商后台管理系统

这是一个面向公司内部运营团队的后台系统，不是对外产品。
主要功能包括订单管理、商品管理、用户管理和数据报表。

技术栈

明确告诉 AI 用什么技术，避免它给出不相关的建议：

## 技术栈
- 框架：React 18 + Next.js 14 (App Router)
- 语言：TypeScript (strict mode)
- 样式：Tailwind CSS
- 状态管理：Zustand
- 测试：Vitest + Testing Library
- 包管理：pnpm

开发命令

把常用命令写清楚，AI 就不需要猜了：

## 开发命令
- pnpm install — 安装依赖
- pnpm dev — 启动开发环境（端口 3000）
- pnpm build — 生产构建
- pnpm test — 运行所有测试
- pnpm lint — 代码检查
- pnpm type-check — TypeScript 类型检查

编码规范

这是最有价值的部分——让 AI 生成的代码符合你的标准：

## 编码规范
- 组件使用函数组件 + 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 知道代码放在哪，生成的代码不会放错位置：

## 目录结构
src/
├── app/          # Next.js App Router 页面
├── components/   # 共享组件
│   ├── ui/       # 基础 UI 组件
│   └── shared/   # 业务共享组件
├── services/     # API 请求
├── stores/       # Zustand stores
└── utils/        # 工具函数

边界与约束

告诉 AI 什么不能做，这比告诉它什么能做更重要：

## 约束
- 不要修改 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——从空白到最佳实践]()