CLAUDE.md 是你与 Claude Code 之间最重要的沟通桥梁。写得好，Claude 如虎添翼；写得差，Claude 会在无用的探索中浪费上下文窗口。这篇文章基于官方文档和社区经验，总结 CLAUDE.md 的最佳实践。
CLAUDE.md 是什么？
CLAUDE.md 是 Claude Code 启动时自动加载的配置文件，告诉 Claude 关于你项目的一切：代码规范、构建命令、架构决策、团队约定。它会占用约 1,800 个 Token 的上下文空间。
文件位置和优先级
~/.claude/CLAUDE.md # 全局配置（适用于所有项目）
./CLAUDE.md # 项目根目录（团队共享）
./src/CLAUDE.md # 子目录（Claude 进入该目录时加载）
优先级：子目录 > 项目根 > 全局。
黄金法则
1. 控制在 200 行以内
CLAUDE.md 每次会话都会加载。越长 = 越多上下文消耗 = 越少的工作空间。
markdown
# ❌ 不好：把所有文档都塞进来
完整的 API 文档...（500行）
所有数据库表结构...（300行）
# ✅ 好：精炼的关键信息
## 构建
- `npm run dev` 启动开发服务器
- `npm test` 运行测试（vitest）
- `npm run build` 生产构建
## 架构
- Next.js App Router + TypeScript
- Prisma ORM + PostgreSQL
- 认证：NextAuth.js2. 指令 > 描述
告诉 Claude「怎么做」而不只是「是什么」：
markdown
# ❌ 描述性（Claude 需要自己推断）
我们使用 TypeScript 和 React。
# ✅ 指令性（Claude 直接执行）
- 所有新文件使用 TypeScript，不要 .js
- React 组件用函数组件 + hooks，不用 class
- 类型定义放在 types/ 目录
- 导出类型时用 `export type`3. 写最常用的命令
Claude 不知道你的项目用什么命令，除非你告诉它：
markdown
## 开发命令
- 启动：`pnpm dev`
- 测试全部：`pnpm test`
- 测试单个：`pnpm test -- path/to/file`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`
- 格式化：`pnpm format`4. 记录非显而易见的决策
markdown
## 决策记录
- 用 Zustand 不用 Redux：更简单，够用
- 数据库用 SQLite（开发）+ PostgreSQL（生产）
- 不用 ORM 的 cascade delete：手动管理关联删除
- API 路由不做版本化：内部服务，前后端同步发布5. 指明错误处理偏好
markdown
## 错误处理
- API 错误统一用 AppError 类
- 前端用 Error Boundary 包裹页面
- 不要用 try/catch 吞掉错误
- 日志级别：error（必须处理）、warn（应该关注）、info（可选）高级技巧
使用路径限定规则
把详细的规范从 CLAUDE.md 移到独立规则文件，只在需要时加载：
markdown
# .claude/rules/api-conventions.md
---
paths: src/api/**
---
所有 API 路由必须：
1. 参数验证用 zod schema
2. 错误返回标准格式 { error: string, code: string }
3. 成功返回 { data: T }
4. 每个路由有独立的 rate limit这样只有当 Claude 读取 src/api/ 下的文件时才加载这些规则，节省上下文。
使用 Skills 替代长文档
markdown
# ❌ 在 CLAUDE.md 里写详细的部署流程
## 部署
1. 先运行测试...
2. 构建 Docker 镜像...
3. 推送到 ECR...
（50行部署指南）
# ✅ 用 Skill 替代
## 部署
运行 /deploy skill分层配置
~/.claude/CLAUDE.md → 个人偏好（编码风格、语言偏好）
./CLAUDE.md → 项目规范（构建、架构、团队约定）
./src/frontend/CLAUDE.md → 前端特定规则
./src/backend/CLAUDE.md → 后端特定规则
模板
markdown
# 项目名称
简短一句话描述。
## 技术栈
- 前端：XXX
- 后端：XXX
- 数据库：XXX
## 常用命令
- `command1` — 做什么
- `command2` — 做什么
## 代码规范
- 规则1
- 规则2
## 架构要点
- 关键决策1
- 关键决策2
## 注意事项
- 不要做XXX
- 总是做YYY常见错误
- 写太多：上下文是有限资源
- 写太泛："写好代码" 没有信息量
- 忘记更新：技术栈迁移后 CLAUDE.md 没跟上
- 重复信息：CLAUDE.md 和 README 大量重叠
- 过度限制：太多 "不要" 会让 Claude 畏首畏尾
原文整理自 Claude Code Memory 文档 和社区最佳实践 | 来源：Claude Code 官方文档 + 社区