来源：code.claude.com/docs/en/memory · best-practices | 整理时间：2026-04-04
什么是 CLAUDE.md？
CLAUDE.md 是 Claude Code 的项目记忆文件。每次会话开始时，Claude 会自动读取它，了解你的项目规范、技术栈和工作流偏好。
类比：CLAUDE.md 就像给新入职的资深工程师一份《团队规范手册》，让他立刻按你的方式工作。
文件层级
~/.claude/CLAUDE.md ← 全局：所有项目共享
├── ~/projects/myapp/CLAUDE.md ← 项目级：团队共享（建议 commit）
│ ├── src/auth/CLAUDE.md ← 目录级：特定模块
│ └── src/api/CLAUDE.md ← 目录级：特定模块
| 层级 | 作用域 | 典型内容 | 是否提交 Git |
|---|---|---|---|
全局 ~/.claude/CLAUDE.md |
所有项目 | 个人偏好（中文回复、 terse 风格） | 否 |
项目 ./CLAUDE.md |
当前项目 | 构建命令、代码风格、测试指令 | 是 |
目录 ./src/auth/CLAUDE.md |
子目录 | 模块特定的架构决策 | 是 |
所有层级的文件叠加生效，不会互相覆盖。
快速生成
/init # Claude 扫描项目结构，自动生成 CLAUDE.md
/init 会分析你的 package.json、目录结构、配置文件，生成一个初始版本。你可以在此基础上修改。
应该写什么
必写内容
# 项目：MyApp
## 构建与运行
- `npm run dev` — 启动开发服务器
- `npm run build` — 生产构建
- `npm test` — 运行测试
## 代码风格
- 使用 TypeScript strict mode
- ES Modules（import/export），不用 CommonJS
- 组件用 PascalCase，工具函数用 camelCase
- 单文件不超过 300 行
## 测试
- 修改代码后必须运行相关测试
- 优先运行单个测试文件，不是整个测试套件
- 测试文件放在 `__tests__/` 目录
## Git 规范
- commit message 使用中文，格式：`feat: / fix: / refactor:`
- 每个 PR 只做一件事
- 提交前运行 `npm run lint`
## 架构
- 前端：React + Next.js（App Router）
- 后端：Node.js + Express
- 数据库：PostgreSQL，使用 Prisma ORM
- 认证：JWT + refresh token
按项目类型补充
前端项目：
## UI 规范
- 使用 Tailwind CSS，不写自定义 CSS
- 响应式设计：mobile-first
- 颜色变量定义在 tailwind.config.ts
- 组件库：shadcn/ui
后端项目：
## API 规范
- RESTful API，响应格式：`{ code, data, message }`
- 错误使用自定义 AppError 类
- 所有接口需要 JWT 认证，除了 /auth/*
- 分页参数：`?page=1&pageSize=20`
Monorepo：
## 项目结构
- apps/web — 前端应用
- apps/api — 后端 API
- packages/shared — 共享类型和工具
- 使用 Turborevo 管理构建
每个子项目有自己的 CLAUDE.md
不应该写什么
| 不写 | 为什么 |
|---|---|
| Claude 能从代码推断的内容 | 浪费 Token，可能导致冲突 |
| 完整的 API 文档 | 太长会被截断，放链接即可 |
| 几乎不改动的标准规范 | 增加噪音 |
| 具体的文件路径列表 | 容易过时 |
| 超过 200 行的内容 | 太长会被忽略 |
高级模式
模式 1：环境区分
# 开发环境
- 数据库使用 Docker 本地 PostgreSQL
- Redis 使用本地实例
- 环境变量在 .env.local
# 生产环境
- 数据库在 AWS RDS
- 使用 AWS ElastiCache Redis
- 环境变量在 AWS Parameter Store
模式 2：按功能覆盖
src/auth/CLAUDE.md
# 认证模块
## 安全要求
- 密码使用 bcrypt（salt rounds: 12）
- JWT 过期时间：access 15min, refresh 7d
- 登录失败不提示具体原因（防暴力破解）
- 所有路由都要检查认证状态
## 已知问题
- refresh token 轮换在并发场景下有竞态条件
- 不要修改 TokenService 的单例模式
模式 3：团队共享模板
团队可以维护一个标准化的 CLAUDE.md 模板：
# 团队规范（所有项目适用）
- PR 需要 2 人 approve
- 代码审查使用 /review 技能
- 提交前必须通过 CI
- 使用 /commit 生成规范的 commit message
# 项目特定（按需修改）
- [构建命令]
- [技术栈]
- [特殊约定]
Auto Memory（自动记忆）
除了 CLAUDE.md，Claude Code 还有自动记忆系统：
/memory
自动记忆存储在 .claude/memory/ 目录下，Claude 在会话中自动积累关于你的偏好和项目特点的认知。
| 特性 | CLAUDE.md | Auto Memory |
|---|---|---|
| 谁写 | 人写 | Claude 自动写 |
| 内容 | 明确的项目规范 | 偏好、习惯、经验教训 |
| 格式 | Markdown | Markdown |
| 生命周期 | 手动维护 | 跨会话持久化 |
最佳实践
# 告诉 Claude 记住某件事
记住：这个项目使用 pnpm 而不是 npm
# 让 Claude 基于当前会话更新
Add to CLAUDE.md: 我们决定使用 Zod 做 API 参数校验
来自社区的实战建议
来源：howborisusesclaudecode.com · shanraisshan/claude-code-best-practice
- CLAUDE.md 控制在 200 行以内——太长会被截断
- 用
/init起步，手动精简——自动生成的版本往往太长 - 把"为什么"也写上——不只写规则，还写原因，帮助 Claude 在边缘场景做出正确判断
- 定期更新——技术栈变了、架构改了，记得同步更新
- 用 agnix 做 lint——agent-sh/agnix 可以自动检查 CLAUDE.md 质量
相关链接
- 最佳实践
- 技能与钩子
- 社区技巧精选
- 官方记忆文档：https://code.claude.com/docs/en/memory
- 官方最佳实践：https://code.claude.com/docs/en/best-practices
- Claude Code 创建者的 72 个技巧：https://howborisusesclaudecode.com
- CLAUDE.md 最佳实践仓库：https://github.com/shanraisshan/claude-code-best-practice