# CLAUDE.md 配置指南

`CLAUDE.md` 是 Claude Code 的**项目级配置文件**。每次启动时，Claude 自动读取项目中的 CLAUDE.md，了解项目架构、编码规范和特殊约定，从而更准确地理解和操作你的项目。

本文从基础到高级，全面介绍 CLAUDE.md 的配置方法和最佳实践。

---

## 一、为什么需要 CLAUDE.md

不使用 CLAUDE.md 时，你需要在每次对话中反复解释：
- "这个项目用 pnpm，不是 npm"
- "测试命令是 `yarn test:unit`，不是 `npm test`"
- "所有组件使用 TypeScript，不要用 any"
- "API 路由在 src/app/api/ 下，不是 routes/"

写入 CLAUDE.md 后，Claude 每次启动自动读取，**一次配置，永久生效**。

### 效果对比

| | 无 CLAUDE.md | 有 CLAUDE.md |
|---|---|---|
| 首次交互 | 需要详细解释项目 | 自动了解项目上下文 |
| 代码风格 | 可能生成不符合规范的代码 | 遵循你定义的规范 |
| 命令执行 | 可能用错误的包管理器 | 使用正确的工具链 |
| 团队一致性 | 每个人的 Claude 行为不同 | 所有人共享同一套规则 |

---

## 二、快速创建

### 自动生成（推荐）

```bash
# Claude 自动分析项目结构并生成
/init
```

Claude 会扫描 `package.json`、目录结构、配置文件等，自动生成包含项目信息的 CLAUDE.md。你可以在此基础上调整。

### 手动创建

```bash
touch CLAUDE.md
```

然后按照下方模板填写。

---

## 三、分层配置详解

Claude Code 读取多个层级的 CLAUDE.md 并**从上到下合并**，下层覆盖上层的同名规则。

### 四层配置架构

```
优先级（从低到高）：
┌─────────────────────────────────────┐
│ 1. ~/.claude/CLAUDE.md              │ ← 全局默认
├─────────────────────────────────────┤
│ 2. 项目根/CLAUDE.md                 │ ← 团队共享规则
├─────────────────────────────────────┤
│ 3. 项目根/.claude/CLAUDE.md         │ ← 个人私有规则
├─────────────────────────────────────┤
│ 4. 子目录/CLAUDE.md                 │ ← 局部覆盖
└─────────────────────────────────────┘
```

### 各层使用场景

| 层级 | 文件位置 | Git 管理 | 使用场景 |
|------|---------|---------|---------|
| **全局** | `~/.claude/CLAUDE.md` | 不纳入 | 个人偏好（语言、风格） |
| **项目** | `项目根/CLAUDE.md` | **提交到 Git** | 团队共享的项目规范 |
| **私有** | `.claude/CLAUDE.md` | **.gitignore** | 个人的 debug 配置、临时规则 |
| **子目录** | `子目录/CLAUDE.md` | 按需 | 子模块特定规则 |

### 实际例子：四层同时生效

**全局 `~/.claude/CLAUDE.md`**：
```markdown
## 个人偏好
- 用中文回答
- 代码注释用英文
- commit message 格式：conventional commits
```

**项目 `CLAUDE.md`**：
```markdown
## 技术栈
Next.js 15 + TypeScript + Tailwind CSS

## 命令
- dev: pnpm dev
- test: pnpm test
```

**私有 `.claude/CLAUDE.md`**：
```markdown
## Debug
当前正在修复 #1234 issue
相关文件：src/auth/login.tsx
```

**子目录 `src/api/CLAUDE.md`**：
```markdown
## API 规范
所有接口使用 Zod schema 验证
错误格式遵循 RFC 7807
```

当 Claude 在 `src/api/` 目录工作时，会合并所有四层的规则。

---

## 四、项目模板

### 模板 1：React + TypeScript 前端

```markdown
# MyApp Frontend

## 技术栈
- React 19 + TypeScript 5.x
- 构建工具：Vite 6
- 样式：Tailwind CSS v4（utility-first，不写内联 style）
- 状态管理：Zustand（全局），TanStack Query（服务端状态）
- 路由：React Router v7
- 测试：Vitest + Testing Library + MSW

## 命令
- 开发：`pnpm dev`（端口 3000）
- 测试：`pnpm test`（Vitest watch 模式）
- 单次测试：`pnpm test:run`
- 构建：`pnpm build`
- Lint：`pnpm lint`（ESLint + Prettier）
- 类型检查：`pnpm typecheck`

## 编码规范
- 组件：函数式组件 + Hooks，禁止 class 组件
- Props：使用 interface 定义（不用 type）
- 文件名：组件 PascalCase（UserProfile.tsx），工具 camelCase（formatDate.ts）
- 导入排序：React → 第三方 → 项目内部 → 样式
- 禁止 any 类型，必须显式类型标注
- 异步操作统一用 TanStack Query，不直接 useEffect + fetch

## 项目结构
- src/components/ — 可复用 UI 组件
- src/pages/ — 路由页面
- src/hooks/ — 自定义 Hooks
- src/api/ — API 请求封装（TanStack Query 的 queryFn）
- src/stores/ — Zustand stores
- src/lib/ — 工具函数
- src/types/ — 全局类型定义

## 注意事项
- 包管理器：pnpm（不是 npm 或 yarn）
- Node.js 22+
- 所有 API 请求经过 src/api/client.ts 统一处理（含拦截器）
- 图片放 public/images/，引用时用 /images/ 路径
```

### 模板 2：Python + FastAPI 后端

```markdown
# MyApp Backend

## 技术栈
- Python 3.12 + FastAPI
- ORM：SQLAlchemy 2.0（async）+ Alembic 迁移
- 数据库：PostgreSQL 16
- 缓存：Redis 7
- 测试：pytest + httpx + factory_boy

## 命令
- 开发：`uvicorn app.main:app --reload --port 8000`
- 测试：`pytest -xvs`
- 迁移：`alembic upgrade head`
- 新迁移：`alembic revision --autogenerate -m "描述"`
- Lint：`ruff check .`
- 格式化：`ruff format .`
- 类型检查：`mypy app/`

## 编码规范
- 类型标注：所有函数参数和返回值必须有 type hints
- async/await：所有 I/O 操作使用 async
- Pydantic v2：请求/响应 schema 统一用 Pydantic BaseModel
- 依赖注入：通过 FastAPI Depends() 注入数据库连接、认证等
- 错误处理：业务异常继承自 app.exceptions.AppError

## 项目结构
- app/main.py — 应用入口
- app/api/ — 路由（按资源分文件）
- app/models/ — SQLAlchemy 模型
- app/schemas/ — Pydantic schemas
- app/services/ — 业务逻辑
- app/core/ — 配置、数据库、安全等核心模块
- tests/ — 测试文件（镜像 app/ 结构）
- alembic/ — 数据库迁移

## 注意事项
- 不要修改 alembic/versions/ 中已有的迁移文件
- .env 文件不提交到 Git，通过 app/core/config.py 的 Settings 类加载
- 虚拟环境：`python -m venv venv && source venv/bin/activate`
```

### 模板 3：Go 微服务

```markdown
# MyService

## 技术栈
- Go 1.23
- HTTP 框架：Echo v4
- 数据库：PostgreSQL + sqlc（类型安全 SQL）
- 消息队列：NATS JetStream
- 容器化：Docker + docker-compose

## 命令
- 运行：`go run ./cmd/server`
- 测试：`go test ./...`
- 构建：`go build -o bin/server ./cmd/server`
- 生成 sqlc：`sqlc generate`
- Lint：`golangci-lint run`

## 编码规范
- 错误处理：永远检查 err，不要用 _ 忽略
- 接口命名：单方法接口加 -er 后缀（Reader, Writer）
- 包命名：小写单词，不用下划线
- 日志：使用 slog 结构化日志
- 上下文：所有函数第一个参数传 context.Context

## 项目结构（标准 Go 布局）
- cmd/server/ — 主程序入口
- internal/handler/ — HTTP handler
- internal/service/ — 业务逻辑
- internal/repository/ — 数据访问层
- internal/model/ — 数据模型
- sql/ — SQL 查询文件（sqlc 使用）
```

### 模板 4：Monorepo（Turborepo）

```markdown
# MyPlatform Monorepo

## 技术栈
- 包管理：pnpm workspace
- 构建系统：Turborepo
- 语言：TypeScript 全栈

## 命令
- 全局开发：`pnpm dev`
- 全局测试：`pnpm test`
- 全局构建：`pnpm build`
- 单包开发：`pnpm --filter @myplatform/web dev`
- 添加依赖：`pnpm --filter @myplatform/api add express`

## 包结构
- apps/web/ — Next.js 前端
- apps/api/ — Express 后端
- apps/admin/ — 管理后台
- packages/ui/ — 共享 UI 组件库
- packages/config/ — 共享配置（eslint, tsconfig）
- packages/types/ — 共享类型定义

## 注意事项
- 共享代码放 packages/，不要在 apps 之间直接引用
- 新建包时参考 packages/ui/package.json 的格式
- Turborepo 缓存：构建产物缓存在 node_modules/.cache/turbo
```

### 模板 5：数据科学 / ML 项目

```markdown
# ML Pipeline

## 技术栈
- Python 3.12
- 框架：PyTorch 2.5 + Lightning
- 数据处理：Polars（不用 Pandas）
- 实验追踪：MLflow
- 依赖管理：uv

## 命令
- 训练：`python -m src.train --config configs/experiment.yaml`
- 评估：`python -m src.evaluate --checkpoint runs/latest`
- 数据预处理：`python -m src.preprocess --data-dir data/raw`
- Jupyter：`jupyter lab`
- 测试：`pytest tests/`

## 编码规范
- 配置用 YAML（不要硬编码超参数）
- 数据处理用 Polars（比 Pandas 快，类型安全）
- 所有实验必须记录到 MLflow
- Notebook 仅用于探索，生产代码必须在 src/ 中

## 项目结构
- configs/ — 实验配置 YAML
- data/raw/ — 原始数据（不提交 Git，用 DVC 管理）
- data/processed/ — 处理后数据
- src/ — 核心代码（model, data, train, evaluate）
- notebooks/ — 探索性分析
- runs/ — 训练输出（checkpoints, logs）
```

---

## 五、团队协作最佳实践

### Git 管理策略

```
CLAUDE.md          → 提交到 Git（团队共享）
.claude/CLAUDE.md  → 加入 .gitignore（个人配置）
```

建议在 `.gitignore` 中添加：

```gitignore
# 个人 Claude Code 配置
.claude/CLAUDE.md
.claude/settings.local.json
```

### Code Review 检查项

每次 PR review 时，检查：
- 新增技术栈是否同步更新了 CLAUDE.md？
- 修改了项目结构是否更新了"项目结构"章节？
- 新增了重要命令是否更新了"命令"章节？

### 新人上手指南

CLAUDE.md 同时也是最好的项目入门文档：
1. 新人 clone 项目后，先阅读 CLAUDE.md 了解全局
2. 运行 `claude` → Claude 已经知道所有项目规范
3. 用 `> 帮我理解这个项目` 开始探索

---

## 六、高级技巧

### 动态引用

CLAUDE.md 不宜过长。对于详细文档，引用路径而非内联：

```markdown
## 架构说明
详细架构文档见 `docs/architecture.md`。
API 设计规范见 `docs/api-design.md`。
数据库 schema 见 `prisma/schema.prisma`。
```

Claude 需要时会自动读取这些文件。

### 与 AGENTS.md 的关系

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| 工具 | Claude Code | Codex CLI |
| 格式 | Markdown | Markdown |
| 内容 | 几乎可以复用 80%+ | 几乎可以复用 80%+ |

如果你同时使用 Claude Code 和 Codex，两个文件可以共存：
- **共用内容**：技术栈、命令、编码规范、项目结构
- **工具特定**：Claude 的 `/model`、`/plan` 指令放 CLAUDE.md；Codex 的 approval mode 配置放 AGENTS.md

> 详见 [AGENTS.md 配置指南](/docs/usage/agents-md)。

### 控制上下文消耗

CLAUDE.md 的内容始终存在于上下文中（不会被 `/compact` 删除）。建议：

- **总长度控制在 500 行以内**
- 详细文档用引用路径代替内联
- 不要放经常变化的信息（如当前进度）
- 不要放代码示例（Claude 可以自己读源码）

---

## 七、常见错误和调试

### CLAUDE.md 没有被读取

```bash
# 确认文件在项目根目录
ls -la CLAUDE.md

# 确认 Claude 看到了它
claude
> 你看到了 CLAUDE.md 吗？里面写了什么技术栈？
```

### 内容太长导致上下文不足

```bash
# 检查 CLAUDE.md 行数
wc -l CLAUDE.md
# 超过 500 行建议精简

# 查看上下文使用
/cost
```

### 团队成员配置冲突

每个人的 `~/.claude/CLAUDE.md` 全局配置不同。如果团队行为不一致，检查：
1. 项目根 CLAUDE.md 是否足够具体？
2. 是否有人在 `.claude/CLAUDE.md` 中覆盖了团队规则？

---

## 八、CLAUDE.md 与 AGENTS.md 如何选

Claude Code 原生读取 `CLAUDE.md`（连同 memory 文件和路径作用域规则）。而**其他**绝大多数工具——Cursor、Codex、GitHub Copilot、Cline、Gemini / Antigravity、Aider、Zed 等——读取的是 `AGENTS.md`。到底维护哪个文件，取决于你的团队用几种工具。

| 场景 | 建议 |
|------|------|
| **单工具（只用 Claude Code）** | `CLAUDE.md` 足矣——无需 AGENTS.md |
| **多工具团队** | 以 `AGENTS.md` 作为共享 source of truth，外加一个薄薄的 `CLAUDE.md` 导入它 |

### 单工具：只写 CLAUDE.md

如果团队所有人都用 Claude Code，把所有内容写进 `CLAUDE.md` 即可，再开一个文件没有任何收益。

### 多工具：以 AGENTS.md 为 source of truth

当团队把 Claude Code 与 Cursor、Codex、Copilot 等混用时，把共享规则——技术栈、命令、编码规范、项目结构——放进 `AGENTS.md`，再让 `CLAUDE.md` 成为一个导入它、只补充 Claude 专属内容的薄文件：

```markdown
# 项目规则

@AGENTS.md

## Claude Code 专属
- 大型重构用 /model 切到 Opus 4.8
- 架构文档用路径引用 docs/architecture.md，不要内联粘贴
```

`@AGENTS.md` 这一行会把共享内容拉进 Claude Code 的上下文，于是 Claude 既拿到团队规则，**又**拿到自己的专属补充。**切忌为同一套规则维护两份会逐渐分叉的副本**——这是最大的坑，因为两个文件迟早会失去同步。

> AGENTS.md 的格式与工具生态详见 [AGENTS.md 配置指南](/docs/usage/agents-md)。

---

## 下一步

- [AGENTS.md 配置指南](/docs/usage/agents-md) — Codex 版本的项目配置文件
- [上下文管理](/docs/usage/context-management) — 掌握上下文窗口管理
- [工作流技巧](/docs/usage/workflow-tips) — 建立高效工作流
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — 从零到精通