CLAUDE.md 项目配置文件

CLAUDE.md 是 Claude Code 启动时自动读取的项目配置文件，里面写的内容会注入到每次对话的上下文。

一句话总结

CLAUDE.md = 每次对话都需要让 Claude 知道的全局上下文。 跟 Skills（按需加载）、Slash Commands（手动触发）形成互补。

为什么需要

没有 CLAUDE.md：

你：帮我写个单元测试
Claude：我们用什么测试框架？项目结构是什么样？...
你：（每次都要解释一遍）

有 CLAUDE.md：

你：帮我写个单元测试
Claude：（自动知道用 pytest、放在 tests/ 目录、要 mock 数据库）

加载顺序

Claude Code 会按以下顺序合并多个 CLAUDE.md：

1. ~/.claude/CLAUDE.md           ← 全局（你的所有项目都生效）
2. /项目根/CLAUDE.md             ← 项目级（团队共享）
3. /项目根/CLAUDE.local.md       ← 本地覆盖（个人，不提交 Git）
4. 各子目录的 CLAUDE.md          ← 子目录级

后面的优先级高于前面。

推荐模板

# <项目名>

## 项目概述
一句话说清这是个什么项目、解决什么问题。

## 技术栈
- 语言：TypeScript
- 框架：Next.js 14 (App Router)
- 数据库：PostgreSQL + Prisma
- 部署：Vercel
- 测试：Vitest + Playwright

## 项目结构
\`\`\`
src/
├── app/              # Next.js 路由
├── components/       # React 组件
├── lib/              # 工具函数 + Prisma client
├── hooks/            # 自定义 hooks
└── types/            # TypeScript 类型
\`\`\`

## 开发命令
- `pnpm dev`        启动开发服务器
- `pnpm test`       跑单元测试
- `pnpm test:e2e`   跑 E2E 测试
- `pnpm lint`       ESLint + Prettier 检查
- `pnpm build`      生产构建
- `pnpm db:push`    同步 Prisma schema 到数据库

## 编码规范
- **缩进**：2 空格
- **引号**：单引号
- **命名**：camelCase（函数变量）/ PascalCase（组件/类型）
- **导入顺序**：内置 → 第三方 → 项目内 → 相对路径
- **不要**用 default export（除非 Next.js 强制要求）

## 测试规范
- 单元测试：`*.test.ts` 在同目录
- 测试覆盖率 ≥ 80%
- 新功能必须带测试
- 不要直接调用真实数据库，用 prisma-mock

## Git 工作流
- 主分支：`main`（保护，只接 PR）
- 功能分支：`feature/<task-id>-<desc>`
- 提交格式：`<type>: <desc>`（type: feat/fix/refactor/docs/test）
- PR 标题要写明影响的模块

## 注意事项
- ⚠️ 不要碰 `src/legacy/`（兼容老接口，下个迭代删）
- ⚠️ Prisma migration 必须经过 CI 验证
- ⚠️ 用户密码字段绝对不能 log

写好 CLAUDE.md 的关键

✅ DO

• 写"Claude 看不出来的" —— 隐藏约定、历史包袱、团队偏好
• 简洁 —— 长度 < 200 行最佳
• 可执行 —— 写命令而不是描述（"运行 pnpm test" 而非"用 vitest 测试"）
• 结构化 —— 用 H2/H3 标题分块，方便 Claude 检索

❌ DON'T

• ❌ 重复代码里有的信息 —— Claude 能读源码，不要重复贴
• ❌ 大段抽象方法论 —— "尽量保持代码简洁优雅" → 没用
• ❌ 过时的内容 —— 6 个月前的注意事项要清理
• ❌ 超过 500 行 —— 太长 Claude 会忽略具体指令

CLAUDE.md vs Skills vs Slash Commands

	CLAUDE.md	Skills	Slash Commands
加载时机	每次都加载	按任务匹配自动激活	你主动 / 触发
适合	全局上下文	复用工作流	一次性指令
大小	一直占 context	元数据 ~100 token	调用时占
例子	"我们用 TS strict mode"	"代码审查工作流"	"/test 跑测试"

初始化 CLAUDE.md

cd ~/your-project
claude /init

Claude 会扫描项目结构，自动生成 CLAUDE.md 草稿，你审一遍改改即可。

减肥（关键技巧）

定期 review，问每一行："删掉它 Claude 会犯错吗？" 不会 → 删。

膨胀的 CLAUDE.md 会让 Claude 忽略真正重要的指令。

团队协作

字段	提交 Git?
CLAUDE.md	✅ 团队共享规范
CLAUDE.local.md	❌ 加 .gitignore，个人覆盖
~/.claude/CLAUDE.md	❌ 你的全局偏好

.gitignore：

CLAUDE.local.md

真实例子参考

• hesreallyhim/awesome-claude-code — 收集了大量优秀 CLAUDE.md 案例
• Anthropic 官方最佳实践