目标：使用 CLAUDE.md 定制 Claude 的行为，使其更懂你的项目
预计时间：25 分钟
对应官方文档：Memory、Claude Directory
什么是 CLAUDE.md？
CLAUDE.md 是一个特殊的 Markdown 文件，放在项目根目录的 .claude/ 文件夹中（或项目根目录）。Claude 会在每个会话开始时自动读取它，作为项目级别的系统提示。
你可以把它理解为：
- 📋 项目规范说明书
- 🎯 编码风格指南
- 🔧 常用命令速查
- 🧠 项目背景知识
创建 CLAUDE.md
位置
你的项目/
├── .claude/
│ └── CLAUDE.md # 项目级配置（推荐）
├── src/
├── tests/
└── README.md
或直接在根目录：
你的项目/
├── CLAUDE.md # 也支持
├── src/
└── ...
基本结构
# 项目规范
## 项目概述
这是一个 Python Web API 项目，使用 FastAPI 框架。
## 编码规范
- 使用 Black 格式化代码
- 类型注解必须完整
- 函数文档使用 Google Style
- 测试覆盖率要求 80%+
## 常用命令
```bash
# 运行测试
pytest tests/ -v --cov=src
# 代码检查
black src/ && flake8 src/
# 启动开发服务器
uvicorn main:app --reload架构约定
- 路由放在 src/routes/
- 模型放在 src/models/
- 服务层放在 src/services/
- 不要在路由里写业务逻辑
注意事项
- 数据库使用 PostgreSQL，不要假设 SQLite
- 所有 API 响应必须包含 request_id
- 敏感操作需要记录审计日志
---
## 实际效果
配置了 CLAUDE.md 后，当你说：
添加一个用户注册的 API 端点
Claude 会自动：
- ✅ 使用 FastAPI 风格
- ✅ 添加完整的类型注解
- ✅ 编写 Google Style 文档字符串
- ✅ 把路由放在 `src/routes/`
- ✅ 业务逻辑放在 `src/services/`
- ✅ 包含 `request_id` 和审计日志
**不需要每次都重复说明！**
---
## 高级配置
### 分层配置
大型项目可以使用多层 CLAUDE.md：
项目根目录/ ├── .claude/ │ └── CLAUDE.md # 全局规范 ├── backend/ │ └── .claude/ │ └── CLAUDE.md # 后端特有规范 ├── frontend/ │ └── .claude/ │ └── CLAUDE.md # 前端特有规范 └── shared/ └── .claude/ └── CLAUDE.md # 共享模块规范
Claude 会按层级合并配置，子目录的规范会覆盖父目录的冲突项。
---
### 条件配置
```markdown
## 环境判断
如果项目包含 `pyproject.toml`，使用 Poetry 管理依赖。
如果项目包含 `package.json`，使用 npm/yarn/pnpm（检查 lock 文件确定）。
## 测试策略
- Python 项目：pytest + coverage
- JavaScript 项目：Jest + React Testing Library
包含文件
## 参考文档
- @docs/architecture.md # 架构文档
- @docs/api-spec.md # API 规范
- @CONTRIBUTING.md # 贡献指南Auto Memory（自动记忆）
除了手动编写 CLAUDE.md，Claude 还会自动积累记忆：
> 我们总是把错误处理放在 service 层，不是路由层
[Claude 记住这个偏好]
这些自动记忆存储在：
~/.claude/memory/ # 用户级记忆
项目/.claude/memory/ # 项目级记忆
管理自动记忆
> /memory show # 查看当前记忆
> /memory forget <id> # 删除某条记忆
> /memory clear # 清空所有记忆
最佳实践
| ✅ 推荐 | ❌ 避免 |
|---|---|
| 简洁明了，重点突出 | 过长（超过 200 行效果递减） |
| 具体示例，而非抽象描述 | 模糊的"写好代码" |
| 常用命令直接可复制 | 只写命令名不写参数 |
| 项目特有的约束 | 通用的 Python/JS 知识 |
| 定期更新 | 创建后不再维护 |
验证配置生效
> /context
[查看输出中的 "Project Instructions" 部分]
或：
> 请复述一下项目的编码规范
如果 Claude 能准确说出你的规范，说明配置生效。
示例：完整 CLAUDE.md
# MyProject 开发规范
## 技术栈
- Python 3.11+
- FastAPI + SQLAlchemy 2.0
- PostgreSQL 15
- pytest + httpx
## 代码风格
```python
# 所有函数必须有类型注解
def get_user(user_id: UUID, db: Session) -> User | None:
"""Get user by ID.
Args:
user_id: The user's UUID.
db: Database session.
Returns:
User object or None if not found.
"""提交规范
- 使用 Conventional Commits
- feat: 新功能
- fix: 修复
- refactor: 重构
- test: 测试
禁止事项
- 不要在代码中硬编码密码
- 不要直接返回 SQLAlchemy 模型，使用 Pydantic schema
- 不要在循环中查询数据库（使用 join）
---
## 补充：CLAUDE.md 工作流程与实战
### CLAUDE.md 加载与合并流程
```mermaid
flowchart TD
A[启动 Claude Code] --> B{发现 .claude/CLAUDE.md?}
B -->|是| C[读取项目级 CLAUDE.md]
B -->|否| D{发现根目录 CLAUDE.md?}
D -->|是| E[读取根目录 CLAUDE.md]
D -->|否| F[使用默认行为]
C --> G{当前目录有子级 CLAUDE.md?}
E --> G
G -->|是| H[逐层合并配置]
G -->|否| I[加载完成]
H --> I
F --> I
I --> J[会话开始，AI 遵循项目规范]
完整配置示例
示例 1：前端 React + TypeScript 项目完整 CLAUDE.md
# Frontend 开发规范
## 技术栈
- React 18 + TypeScript 5.3
- Vite 5 + pnpm
- Tailwind CSS + shadcn/ui
- React Query + Zustand
- Vitest + React Testing Library
- Playwright E2E
## 目录结构src/ components/ # 通用组件（只收无状态/低状态） features/ # 功能模块（含业务逻辑） hooks/ # 通用 hooks lib/ # 工具函数 services/ # API 层 stores/ # 全局状态 types/ # 全局类型
## 编码规范
1. 所有组件使用函数式 + hooks
2. Props 必须有 interface，命名 `XXXProps`
3. 异步逻辑必须放在 React Query 或自定义 hook 中
4. 禁止在 JSX 中写内联对象/函数（避免引用不稳定）
5. 样式优先用 Tailwind，复杂样式用 CSS Modules
## 常用命令
```bash
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
# 运行单元测试
pnpm test
# 运行 E2E 测试
pnpm e2e
# 类型检查
pnpm typecheck
# 构建
pnpm build
提交规范
使用 Conventional Commits：
feat:新功能fix:Bug 修复refactor:重构（无行为变更）test:测试相关chore:构建/工具
API 调用规范
// 统一使用 services 层
import { fetchUser } from '@/services/user';
// 组件中只使用 hook
const { data, isLoading } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
});禁止事项
- 不要使用
any类型（必须用unknown+ 类型守卫） - 不要直接调用
fetch/axios（使用 services 层封装） - 不要在组件中直接修改 Zustand store
- 不要引入未评审的第三方库
#### 示例 2：分层配置实战（Monorepo）
my-monorepo/ ├── .claude/ │ └── CLAUDE.md # 全局：通用提交规范、沟通语言 ├── apps/ │ ├── web/ │ │ └── .claude/ │ │ └── CLAUDE.md # 前端：React、Next.js 规范 │ └── api/ │ └── .claude/ │ └── CLAUDE.md # 后端：FastAPI、SQLAlchemy 规范 ├── packages/ │ └── shared/ │ └── .claude/ │ └── CLAUDE.md # 共享库：TypeScript 库开发规范
根目录 `.claude/CLAUDE.md`：
```markdown
# Monorepo 全局规范
## 通用约定
- 使用 pnpm workspaces
- 所有包统一用 ESM
- 提交前必须跑 `pnpm lint` 和 `pnpm test`
- 代码风格：Prettier + ESLint（根配置）
## 分支策略
- main：生产分支
- develop：集成分支
- feature/*：功能分支
## 常用命令
```bash
# 安装所有依赖
pnpm install
# 构建全部包
pnpm build
# 测试全部包
pnpm test
#### 示例 3：条件配置 + 文件引用
```markdown
# 智能项目规范
## 环境判断
- 如果存在 `pyproject.toml` → Python 项目，使用 Poetry
- 如果存在 `package.json` → Node 项目，使用 pnpm（优先）或 npm
- 如果存在 `Cargo.toml` → Rust 项目，使用 cargo
## 语言特定规范
### Python
- 类型注解必须完整
- 使用 Ruff 替代 flake8 + black
- 测试用 pytest
### JavaScript/TypeScript
- 严格模式开启
- 优先使用 `const`，少用 `let`，禁用 `var`
- 异步优先 async/await
## 参考文档
- @docs/architecture.md # 架构决策记录
- @docs/api-spec.md # 接口契约
- @CONTRIBUTING.md # 贡献者指南
- @SECURITY.md # 安全政策
## 自动触发规则
当用户说"添加 API"时：
1. 先检查是 Python 还是 Node 项目
2. 遵循对应语言的目录结构
3. 同时生成对应的测试文件
4. 更新接口文档（如果存在）
实战场景
场景一：团队规范统一（多人协作项目）
背景：一个 8 人团队维护 Python 后端项目，经常因为代码风格不一致、测试写法各异导致 Code Review 效率低下，甚至出现遗漏类型注解的情况。
步骤：
- 技术负责人编写
.claude/CLAUDE.md，明确编码风格、测试要求、目录结构 - 将文件提交到 Git，要求所有成员拉取
- 每位开发者在本地启动 Claude Code 时自动加载规范
- 在规范中写明"每次生成功能代码必须同时生成 pytest 测试"
结果：
- AI 生成的代码自动符合团队风格，减少 60% 的风格类 Review 意见
- 新成员无需阅读冗长文档，通过 CLAUDE.md 即可让 AI 按团队习惯编码
- 类型注解覆盖率从 45% 提升到 92%
场景二：遗留项目改造（老项目接入 AI 辅助）
背景：一个 5 年前的 Django 项目，无类型注解、无测试、目录混乱。团队希望借助 Claude Code 逐步现代化，但担心 AI 不了解项目历史约束。
步骤：
- 在项目根目录创建
CLAUDE.md，开篇说明"这是遗留项目，正在渐进式改造" - 列出当前技术债务：Django 3.2、无类型注解、使用函数视图而非 CBV
- 规定改造原则：
- 新功能必须用基于类的视图
- 修改旧文件时，只给新增/修改的函数加类型注解
- 不要一次性重构整个模块
- 记录业务约束：某些表字段命名历史原因不符合规范，不要重命名
结果：
- AI 不会盲目按最新最佳实践推倒重来，避免破坏现有功能
- 逐步改造过程中，每个新功能都自动符合现代 Django 写法
- 团队成员无需每次重复说明"这是老项目，请注意..."