CLAUDE.md 最佳实践

CLAUDE.md 是 Claude Code 的核心配置文件，每次会话开始时自动读取。写好它，Claude 的表现会截然不同。

快速生成

claude
# 进入后输入
/init

Claude 会分析项目结构，自动生成一个初始 CLAUDE.md。

应该写什么

写 Claude 猜不到的东西

# 构建与测试
- 用 pnpm 不要用 npm
- 测试命令：pnpm vitest run
- 只跑单个测试：pnpm vitest run src/xxx.test.ts

# 项目规范
- 提交信息用中文
- 分支命名：feature/xxx、fix/xxx
- PR 标题不超过 70 字符

# 注意事项
- src/legacy/ 下的代码不要动，正在迁移中
- 数据库迁移必须用 drizzle-kit generate
- IMPORTANT: 不要自动提交 git

强调重点

用 IMPORTANT、YOU MUST、NEVER 等关键词提高遵守率：

IMPORTANT: 所有 API 路由必须先验证 JWT token
NEVER: 不要删除 migrations 目录下的任何文件
YOU MUST: 每次修改组件后运行 pnpm typecheck

不应该写什么

Claude 读代码就能看出来的东西（比如「这是一个 React 项目」）
标准语言惯例（比如「变量用 camelCase」——TypeScript 项目默认就这样）
详细的 API 文档（改为链接引用）
「写干净代码」这类废话
每个文件的详细说明

原则：删掉这条，Claude 会犯错吗？如果不会，就不需要。

文件层级

CLAUDE.md 支持多级放置，按优先级从高到低：

位置	作用域	是否签入 Git
`~/.claude/CLAUDE.md`	所有项目全局	否
`./CLAUDE.md`	当前项目	是（推荐）
`./CLAUDE.local.md`	当前项目（个人）	否（加入 .gitignore）
`./子目录/CLAUDE.md`	特定子目录	是

Monorepo 用法

repo/
├── CLAUDE.md           # 全局规范
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md   # 前端特定规范
│   └── backend/
│       └── CLAUDE.md   # 后端特定规范

Claude 进入子目录工作时会自动加载对应的 CLAUDE.md。

导入其他文件

用 @ 语法引用外部文件：

# 项目规范
@docs/git-instructions.md
@docs/api-conventions.md

CLAUDE.md vs Skills

	CLAUDE.md	Skills
加载时机	每次会话自动加载	按需加载
适合内容	广泛适用的规范	特定领域知识
文件位置	项目根目录	`.claude/skills/`
上下文成本	每次都占用	只在需要时占用

原则：高频用到的放 CLAUDE.md，偶尔用到的放 Skills。

维护建议

像代码一样管理 — 签入 Git，团队共同维护
出了问题先检查它 — Claude 行为不对？可能是 CLAUDE.md 没写清楚
定期修剪 — 删除过时的规则，保持精简
从错误中学习 — Claude 犯了错，加一条对应的规则

CLAUDE.md 最佳实践

On this page