看累了听个音乐吧
3.2 CLAUDE.md 深度指南
它是你最重要的配置文件
第二章里我们用 /init 生成了一份 CLAUDE.md，大概扫了一眼就过了。
这一节，我们认真聊聊它——因为一份写得好的 CLAUDE.md，真的能把 Claude Code 的体验提升一个档次。
三层作用范围
CLAUDE.md 可以放在三个地方，分别对应不同的作用范围：
| 位置 | 作用范围 | 适合写什么 |
|---|---|---|
./CLAUDE.md（项目根目录） | 这个项目的所有人 | 代码规范、构建命令、架构说明 |
~/.claude/CLAUDE.md（用户主目录） | 你的所有项目 | 个人偏好、惯用工具、私人快捷方式 |
| 系统目录（由 IT 管理员部署） | 全公司所有人 | 公司安全策略、合规要求 |
优先级： 更具体的位置优先级更高。项目级的规则会覆盖用户级的同类规则。
实际使用中，你最常接触的是前两个：
- 项目级：check in 到 git，团队共享
- 用户级：只属于你，不进版本控制
写什么 vs 不该写什么
这是 CLAUDE.md 写作里最重要的判断，官方给了一张很好的参考表，我把它扩充了一下：
✅ 应该写进去的：
| 类型 | 示例 |
|---|---|
| 构建和测试命令 | npm run dev / npm test / pnpm build |
| 包管理器偏好 | "用 pnpm，不要用 npm 或 yarn" |
| 代码风格规则（和默认不同的） | "用 2 个空格缩进，不用 tab" |
| 提交前的必要步骤 | "提交前必须跑 npm run lint" |
| 项目架构关键点 | "src/api/ 是接口层，src/db/ 是数据层" |
| 特殊约定 | "不要直接修改 dist/ 下的文件，它是自动生成的" |
| 环境变量提示 | "需要 .env 文件，参考 .env.example" |
❌ 不该写进去的：
| 类型 | 原因 |
|---|---|
| Claude 看代码就能推断的事 | 浪费 token，没有额外价值 |
| 标准语言约定（如"写干净的代码"） | 废话，它本来就知道 |
| 详细的 API 文档 | 太长，放链接就够了 |
| 频繁变动的信息 | 很快就会过时，维护成本高 |
| 逐文件描述整个项目 | 太冗长，不如让它自己读 |
一个判断标准： 问自己——"如果没有这条规则，它会做错什么？" 如果答案是"不会做错"，就不需要写。
写法：具体可验证，而不是模糊建议
这是 CLAUDE.md 写作最容易踩的坑。
❌ 模糊的（没用）：
markdown
- 保持代码整洁
- 遵循最佳实践
- 写好的注释Claude Code 看到这些规则，不知道该怎么执行。"整洁"是什么意思？"最佳实践"是哪些实践？
✅ 具体可验证的（有用）：
markdown
- 使用 2 个空格缩进，不用 tab
- 函数超过 30 行时考虑拆分
- 每个公共函数必须有 JSDoc 注释
- 用 ES module（import/export），不用 CommonJS（require）这些规则清晰、可执行、可检验。
@ 导入语法：引用其他文件
CLAUDE.md 支持导入其他文件的内容，用 @ 语法：
markdown
# CLAUDE.md
参考 @README.md 了解项目背景。
构建命令见 @package.json。
## Git 规范
@docs/git-workflow.md这样可以避免在 CLAUDE.md 里重复已经写在其他地方的内容，保持文件简洁。
⚠️ 注意：第一次使用外部导入，Claude Code 会弹出确认框问你是否信任这些文件。确认一次之后就不再问了。
.claude/rules/：按文件类型分拆规则
当项目比较复杂，不同类型的文件有不同规则时，可以用 .claude/rules/ 目录来分拆：
.claude/
└── rules/
├── frontend.md # 只对 .tsx/.jsx 文件生效
├── backend.md # 只对 src/api/ 下的文件生效
└── tests.md # 只对 *.test.ts 生效每个规则文件的 frontmatter 里指定它对哪些文件生效：
markdown
---
paths:
- "**/*.tsx"
- "**/*.jsx"
---
# 前端规则
- 使用函数组件，不用 class 组件
- 状态管理用 Zustand，不用 Redux
- 样式用 Tailwind CSS这样做的好处是：只有在 Claude Code 打开相关文件时，这些规则才会加载——不会在写后端代码时把前端规则也塞进上下文。
一份完整的真实示例
下面是一个中等规模 Node.js + React 全栈项目的 CLAUDE.md 示例，可以直接参考：
markdown
# CLAUDE.md
## 项目概述
全栈 Todo 应用，前端 React + TypeScript，后端 Express + PostgreSQL。
## 常用命令
### 开发
- 启动后端：`pnpm dev:server`（端口 3001）
- 启动前端：`pnpm dev:client`（端口 3000）
- 同时启动：`pnpm dev`
### 测试
- 所有测试：`pnpm test`
- 只跑后端测试：`pnpm test:server`
- 只跑前端测试：`pnpm test:client`
- 单个测试文件：`npx jest path/to/test.ts`
### 构建 & 部署
- 构建：`pnpm build`
- 数据库迁移：`pnpm db:migrate`
## 代码规范
### 通用
- TypeScript，严格模式，禁止 `any`
- 使用 pnpm，不用 npm 或 yarn
- 提交前必须跑 `pnpm lint` 和 `pnpm test`
### 后端（`server/`）
- 路由处理在 `server/routes/`
- 业务逻辑在 `server/services/`
- 数据库查询只在 `server/db/` 里写，不要在 routes 里直接查库
### 前端（`client/`）
- 组件用函数组件 + hooks
- 全局状态用 Zustand（`client/store/`）
- API 调用统一在 `client/api/` 里封装
## 注意事项
- `server/db/migrations/` 下的文件不要手动修改
- `.env` 文件不进 git，参考 `.env.example` 创建
- `client/dist/` 是构建产物，不要手动编辑保持简洁的铁律
最后一条，也是最容易被忽视的：CLAUDE.md 越短越好，控制在 200 行以内。
太长的 CLAUDE.md 有两个问题：
- 每次会话都要消耗更多 token 来加载它
- Claude Code 看到一大墙文字，会开始"选择性忽视"——你最重要的规则可能被淹没在大量噪音里
如果你发现 CLAUDE.md 越写越长，先考虑这两件事：
- 能不能把部分内容移到
.claude/rules/里按需加载？ - 这条规则如果删掉，Claude Code 真的会做错吗？
定期修剪你的 CLAUDE.md，把它当成代码一样维护。
下一节，我们来看 Auto Memory——那个 Claude Code 会自己悄悄维护的记忆文件。