Appearance
Claude Code CLAUDE.md 使用指南：项目级AI工作手册完全教程
CLAUDE.md是Claude Code中最重要的配置文件，每次启动会话自动读取，作为系统级上下文融入每次对话。通俗说，就是给Claude写的项目工作手册——项目是什么、遵循什么规范、有哪些注意事项，只写一次永久生效。
CLAUDE.md的作用
| 没有 | 有 |
|---|---|
| 每次从零理解项目 | 项目约定一次写永久生效 |
| 反复告诉它用什么包管理器、代码风格 | 团队共享统一规范 |
| Claude容易做出错误决策 | 明确告知风险操作，降低出错 |
四大价值：统一团队行为、减少重复沟通、降低出错概率、加速AI理解。
文件放置位置
| 位置 | 路径 | 作用范围 | 提交git |
|---|---|---|---|
| 项目根目录 | {项目根}/CLAUDE.md | 当前项目所有会话 | ✅ 推荐 |
| 项目本地 | {项目根}/.claude/CLAUDE.md | 当前项目所有会话 | ❌ 个人用 |
| 子目录 | {子目录}/CLAUDE.md | 打开该目录文件时加载 | ✅ 多模块仓库 |
| 全局用户级 | ~/.claude/CLAUDE.md | 当前用户所有项目 | ❌ 个人配置 |
优先级：项目本地 > 项目根目录 > 子目录 > 全局用户级
快速创建
自动生成
bash
/initClaude Code会分析项目结构、代码风格、已有配置，自动生成CLAUDE.md。
手动创建
bash
touch CLAUDE.md内容结构（6大模块）
1. 常用命令
markdown
## 常用命令
### 开发
```bash
pnpm dev # 启动开发服务器
pnpm build # 构建生产版本测试
bash
pnpm test # 运行所有测试
pnpm test -- --watch # 监听模式
### 2. 项目结构
```markdown
## 项目结构
- `src/app/` — App Router页面和API路由
- `src/components/` — 可复用组件
- `src/lib/` — 工具函数、数据库客户端
- `prisma/schema.prisma` — 数据库Schema定义3. 编码规范
markdown
## 编码规范
- 只使用具名导出，禁止default export
- 异步函数使用async/await，禁止.then()
- 字符串一律使用双引号4. 架构约束与禁止事项
markdown
## 注意事项（重要）
- `prisma/migrations/` 已有文件**禁止修改**
- `.env.local` 包含真实密钥，**禁止输出内容**
- `src/lib/auth.ts` 是认证核心，**修改前必须告知我**5. 开发环境
markdown
## 开发环境
- Node.js：v20+
- 包管理器：pnpm（禁止npm或yarn）
- 本地数据库：Docker Compose6. 技术栈
markdown
## 技术栈
- 前端：Next.js 14、TypeScript、Tailwind CSS
- 后端：Next.js API Routes、Prisma ORM
- 数据库：PostgreSQL 15Monorepo配置
my-monorepo/
├── CLAUDE.md ← 全局规范
├── packages/
│ ├── web/
│ │ └── CLAUDE.md ← 前端专属
│ ├── api/
│ │ └── CLAUDE.md ← 后端专属
│ └── shared/
│ └── CLAUDE.md ← 共享包@语法引用外部文件
markdown
## 规范文档
详细的API设计规范请参考：
@docs/api-design-guide.md
数据库设计约定：
@docs/database-conventions.md注意：引用文件建议不超过500行，避免占用过多上下文窗口。
维护建议
保持精简
| 原则 | 说明 |
|---|---|
| 不重复 | 每条规则只写一次 |
| 不写无关信息 | 公司介绍、产品规划不放进来 |
| 不重复代码已表达的 | eslint已配置的不用再写 |
| 控制字数 | 建议500字以内，不超过1000字 |
用命令式语言
| ❌ 模糊 | ✅ 明确 |
|---|---|
| 代码应该比较整洁 | 函数不超过50行，超过必须拆分 |
| 尽量写测试 | 每个新增函数必须有单元测试 |
| 注意安全 | 用户输入必须通过sanitize()处理 |
| 用pnpm比较好 | 只使用pnpm，禁止npm或yarn |
常见问题
| 问题 | 答案 |
|---|---|
| 规则不遵守？ | 检查表述是否明确，或把规则放到文件靠前位置 |
| 越长越好？ | 不是，过多占用上下文窗口，重要规则反而不容易被遵守 |
| 子目录何时加载？ | Claude打开该子目录文件时自动加载 |
| 能引用另一个CLAUDE.md？ | 不能直接引用，用@语法引用独立Markdown文件 |
总结
一句话总结：CLAUDE.md是Claude Code的项目工作手册——4级文件位置、6大内容模块、命令式语言、保持精简，让AI每次都以符合项目要求的方式工作。
