CLAUDE.md 配置指南

完整掌握 CLAUDE.md — Claude Code 的项目配置文件，包含分层配置、项目模板、团队协作和高级技巧

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 行为不同	所有人共享同一套规则

二、快速创建 ¶

自动生成（推荐）¶

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

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

手动创建 ¶

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：

## 个人偏好

- 用中文回答
- 代码注释用英文
- commit message 格式：conventional commits

项目 CLAUDE.md：

## 技术栈
Next.js 15 + TypeScript + Tailwind CSS

## 命令

- dev: pnpm dev
- test: pnpm test

私有 .claude/CLAUDE.md：

## Debug
当前正在修复 #1234 issue
相关文件：src/auth/login.tsx

子目录 src/api/CLAUDE.md：

## API 规范
所有接口使用 Zod schema 验证
错误格式遵循 RFC 7807

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

四、项目模板 ¶

模板 1：React + TypeScript 前端 ¶

# 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 后端 ¶

# 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 微服务 ¶

# 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）¶

# 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 项目 ¶

# 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 中添加：

# 个人 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 不宜过长。对于详细文档，引用路径而非内联：

## 架构说明
详细架构文档见 `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 配置指南。

控制上下文消耗 ¶

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

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

七、常见错误和调试 ¶

CLAUDE.md 没有被读取 ¶

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

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

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

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

# 查看上下文使用
/cost

团队成员配置冲突 ¶

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

下一步 ¶

AGENTS.md 配置指南 — Codex 版本的项目配置文件
上下文管理 — 掌握上下文窗口管理
工作流技巧 — 建立高效工作流
Claude Code 完整教程 — 从零到精通

← 上一篇

最佳实践

上下文管理

🚀

开始使用 QCode — Claude Code & Codex

一份套餐同时加速 Claude Code 和 Codex，亚太低延迟

查看套餐定价 → 注册账号

团队 3 人以上？

企业团队版：独立域名 + 子Key管理 + 封号保障，人均低至 ¥250/月

了解企业版 →