Claude Code 每次启动都是全新上下文。但有了 CLAUDE.md，你的编码规范、架构约定、工作流规则可以永远"在线"——每次会话 Claude 都会读取它。
什么是 CLAUDE.md？
CLAUDE.md 是你放在项目根目录的一个普通 Markdown 文件，Claude Code 在每次对话开始时自动读取。它是 Claude Code 的两个记忆系统之一：
| 机制 | 谁写 | 内容 | 用途 |
|---|---|---|---|
| CLAUDE.md | 你 | 规则和指令 | 编码规范、工作流、架构约定 |
| Auto Memory | Claude 自动 | 学到的规律 | 构建命令、调试技巧、你的偏好 |
快速开始：自动生成
cd your-project
claude /initClaude 会分析你的代码库（构建系统、测试框架、代码模式），生成一个基础 CLAUDE.md，你在此基础上完善即可。
文件放在哪里？四个级别
| 级别 | 路径 | 作用范围 | 适合放什么 |
|---|---|---|---|
| 组织级 | /etc/claude-code/CLAUDE.md（Linux） | 所有用户 | 公司编码标准、安全策略 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 整个项目 | 项目架构、团队规范 |
| 用户级 | ~/.claude/CLAUDE.md | 你的所有项目 | 个人编码偏好 |
| 子目录级 | src/api/CLAUDE.md | 按需加载 | 特定模块说明 |
优先级：越具体的路径优先级越高。
写出高效的 CLAUDE.md
关键原则
1. 控制长度：目标 200 行以内
CLAUDE.md 内容会进入上下文窗口，太长会消耗 token 并降低遵守率。超过 200 行时，使用 imports 或 .claude/rules/ 拆分。
2. 具体可验证，不要模糊描述
❌ 模糊："好好格式化代码"
✅ 具体："使用 2 空格缩进"
❌ 模糊："提交前测试一下"
✅ 具体："提交前运行 npm test"
❌ 模糊："保持文件整洁"
✅ 具体："API Handler 放在 src/api/handlers/ 目录"
3. 用 Markdown 结构组织
分组清晰比密集段落更易遵守。
示例 CLAUDE.md
# 代码规范
- 使用 ES modules（import/export），不用 CommonJS（require）
- 尽量解构导入：`import { foo } from 'bar'`
- TypeScript strict mode，不允许 any
# 架构约定
- API 调用统一放 /services 目录
- 组件不直接调用 API，通过 Zustand store
- 数据库操作只在 /db 目录
# 工作流
- 修改完成后跑 typecheck：`npm run typecheck`
- 优先跑单个测试文件，不跑全套：`jest src/auth/login.test.ts`
- 提交前确保 lint 通过：`npm run lint`
# 常用命令
- 启动开发服务器：`npm run dev`
- 构建：`npm run build`
- 跑所有测试：`npm test`按路径范围规则：.claude/rules/
对于大型项目，不同类型文件需要不同规则。用 .claude/rules/ 按文件类型或目录限定规则：
.claude/
rules/
frontend.md # 适用于 src/components/
backend.md # 适用于 src/api/
tests.md # 适用于 **/*.test.ts
frontend.md 示例：
---
description: Frontend component rules
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
---
- 使用 Tailwind CSS，不要自定义 CSS
- 组件使用 named export，不用 default export
- Props 类型必须显式声明引入外部文件
CLAUDE.md 支持 @path/to/file 语法导入其他文件：
# 项目概览
参考 @README.md 了解项目背景，@package.json 查看可用 npm 命令。
# Git 工作流
@docs/git-workflow.md
# 个人偏好（不入库）
@~/.claude/my-preferences.md最多支持 5 层嵌套导入。个人偏好文件放在 ~/.claude/ 不提交到代码库。
Auto Memory：Claude 自动记笔记
除了手写的 CLAUDE.md，Claude Code 还有自动记忆功能。当你纠正 Claude 时，它会自动记下学到的东西：
- 你的项目构建命令
- 常见调试技巧
- 你的代码偏好
自动记忆保存在工作区，每次会话加载前 200 行。
查看和编辑自动记忆：
/memory
开启/关闭自动记忆：
// settings.json
{
"autoMemory": {
"enabled": true
}
}常见问题排查
Claude 不遵守 CLAUDE.md 的规则
- 检查规则是否足够具体（"用 2 空格缩进" vs "好好格式化"）
- 检查是否有矛盾的规则（不同文件的规则相互冲突）
- 减少文件长度，超长会降低遵守率
- 用
/init验证文件确实被加载
CLAUDE.md 太大了
- 把特定模块的规则移到子目录 CLAUDE.md（按需加载）
- 用
.claude/rules/按 glob 规则拆分 - 用
@import语法拆为多个小文件
/compact 后规则好像丢失了
CLAUDE.md 在每次会话开始加载，但如果对话被压缩（compaction），后续轮次可能没有重新加载。解决方法：在 compact 后重新明确关键规则，或用 /clear 重开新会话。
团队协作建议
./CLAUDE.md（或.claude/CLAUDE.md）提交到代码库，团队共享- 只放项目级规范，个人偏好放
~/.claude/CLAUDE.md - 用
@import把个人偏好文件链接进来，但 import 目标不入库 - Monorepo 中用
claudeMdExcludes跳过其他团队的 CLAUDE.md
来源：Store instructions and memories - Claude Code Docs | Anthropic 官方文档