CLAUDE.md 是什么？
一句话理解
CLAUDE.md 是放在项目根目录下的一个 Markdown 文件，用来告诉 Claude Code 你的项目是什么、怎么运行的。相当于给 Claude 的"项目说明书"。
没有 CLAUDE.md 时，Claude 只能从代码中自己推断项目信息，效果会打折扣。有了它，Claude 能更准确地理解你的项目上下文。
为什么需要它？
每次启动 Claude Code，它会自动读取 CLAUDE.md 文件。这个文件帮助 Claude 了解：
- 技术栈：用什么语言、框架、数据库、工具链
- 目录结构：每个目录存放什么内容
- 常用命令：开发、测试、构建、部署怎么运行
- 代码规范：命名约定、目录约定、设计模式
- 常见问题：已知的坑、特殊配置、注意事项
一个完整的示例
# My Express API
## 技术栈
- 运行时：Node.js 20 + TypeScript
- 框架：Express 4 + Prisma ORM
- 数据库：PostgreSQL 16
- 测试：Vitest + Supertest
- 包管理：pnpm
## 目录结构
- src/ 源代码
- routes/ API 路由定义
- middleware/ 中间件（鉴权、日志、错误处理）
- services/ 业务逻辑层
- models/ 数据模型定义
- utils/ 工具函数
- prisma/ 数据库 schema 和迁移
- schema.prisma 数据模型定义
- tests/ 测试文件（镜像 src/ 结构）
- routes/ 接口测试
- services/ 单元测试
## 常用命令
- pnpm dev 启动开发服务器（热重载）
- pnpm build 编译 TypeScript
- pnpm test 运行所有测试
- pnpm test:watch 监听模式运行测试
- pnpm lint 代码规范检查
- pnpm migrate 执行数据库迁移
- pnpm seed 填充测试数据
## 开发约定
1. 所有 API 路由放在 src/routes/ 下，按模块拆分
2. 数据库操作通过 Prisma Service 层，不直接在路由中调用
3. 错误处理统一使用 src/middleware/errorHandler.ts
4. API 返回格式：{ code, data, message }
5. 提交信息使用 Conventional Commits 规范
6. 新功能必须包含单元测试和接口测试
## 环境变量
- DATABASE_URL PostgreSQL 连接地址
- JWT_SECRET JWT 签名密钥
- PORT 服务端口（默认 3000）
如何创建？
方式一：自动生成
在项目目录中启动 Claude Code，选择生成项目文档：
cd your-project
claude
# 首次启动时选择"生成项目文档"
或用 /init 命令：
/init
Claude 会自动扫描项目并生成 CLAUDE.md。
方式二：手动创建
在项目根目录创建 CLAUDE.md 文件，写入项目上下文。
方式三：让 Claude 生成
claude "分析当前项目，生成一份 CLAUDE.md"
Claude 会读取项目文件，自动整理出技术栈、目录结构、命令等信息。
写什么内容？
| 内容 | 重要性 | 说明 |
|---|---|---|
| 技术栈 | ⭐⭐⭐ | 语言、框架、数据库、工具版本 |
| 目录结构 | ⭐⭐⭐ | 每个目录的用途 |
| 常用命令 | ⭐⭐⭐ | 开发/测试/构建/部署命令 |
| 代码规范 | ⭐⭐ | 命名、目录约定、设计模式 |
| 环境变量 | ⭐⭐ | 需要配置哪些变量 |
| 架构说明 | ⭐⭐ | 核心模块的职责和关系 |
| 常见问题 | ⭐ | 已知的坑和解决方案 |
| 部署流程 | ⭐ | 发布步骤和注意事项 |
和 Memory 的区别
| CLAUDE.md | Memory | |
|---|---|---|
| 作用范围 | 项目级别 | 全局级别 |
| 存放位置 | 项目根目录 | .claude/projects/-root/memory/ |
| 内容 | 项目本身的说明 | 你的个人偏好和习惯 |
| 是否提交 Git | ✅ 会提交 | ❌ 仅本地 |
| 谁维护 | 项目成员共同维护 | 你自己 |
简单说：CLAUDE.md 告诉 Claude 项目是什么，Memory 告诉 Claude 你是谁、怎么工作。
注意事项
- 不要写敏感信息：密码、API 密钥不应放在 CLAUDE.md 中
- 保持更新：技术栈变更后同步更新
- 简洁清晰：关键信息到位即可，不是越长越好
- 中英文皆可：用你舒服的语言写
- 结合 README：CLAUDE.md 是给 AI 看的，README 是给人看的，可以互补
💡 实际使用场景
场景：用 CLAUDE.md 加速新成员 onboarding
前端组来了个新人小刘，项目 README 过时了。TL 花 15 分钟写了一份 CLAUDE.md：
# 电商后台管理系统
## 技术栈
React 18 + TypeScript + Ant Design + Zustand + Vite
## 目录说明
- src/pages/ — 页面组件
- src/components/ — 通用组件
- src/store/ — 全局状态
- src/api/ — 接口调用
## 本地开发
npm install → npm run dev → 访问 localhost:5173
小刘拿到项目后运行 claude，Claude 自动读取了 CLAUDE.md。小刘输入：
根据 CLAUDE.md 的介绍，带我理解这个项目的核心业务流程
Claude 结合项目代码和文档说明，带小刘一步步走通了主要页面和数据处理流程。
场景：为开源项目贡献代码
小张想给一个开源项目提 PR。他先 fork 了项目，然后创建 CLAUDE.md：
claude "分析项目的代码风格和贡献指南，帮我生成一份适合这个项目的 CLAUDE.md"
Claude 读完了 CONTRIBUTING.md 和现有代码后，生成的 CLAUDE.md 包含了代码规范、测试要求、提交信息格式。小张基于这份文档，后续每次提交前 Claude 都能自动遵循项目规范。
场景：脚手架项目标配
团队的所有新项目模板都内置了一份 CLAUDE.md，包含技术栈和目录规范。新项目启动时，开发者只需运行 claude，Claude 就能直接理解项目结构开始工作，不需要额外解释。