CLAUDE.md不是给Claude看的README——它是你项目的大脑外挂。配得好，Claude在你项目里就像待了三个月的工程师；配得差，它每次都要从头理解你在做什么。
你肯定遇到过这个场景
你用Claude Code打开项目，让它加一个新功能。它自信满满地写了一段代码，但你一看——缩进风格全错、用了你团队禁用的库、API调用的方式跟你现有代码完全不一致。
你叹了口气，开始手动修改。等改完发现，AI帮你省下来的5分钟，你用10分钟做了修正。
问题不在AI——在于AI对你的项目一无所知。
Claude Code每次新会话都是一个"失忆"的AI。它只知道通用的编程知识，不知道你们团队用2空格还是4空格缩进、用React Query还是SWR、错误处理是抛异常还是返回Result类型。CLAUDE.md就是填补这个信息差的。
为什么CLAUDE.md比System Prompt更强
Claude Code启动时会自动读取项目根目录下的CLAUDE.md文件，将其内容注入到每次对话的系统上下文中。这和API里拼system prompt不同：
| 特性 | System Prompt | CLAUDE.md |
|---|---|---|
| 持久化 | 每次手动传 | 项目级自动加载 |
| 版本控制 | 不在Git里 | 可以commit，团队共享 |
| 分层优先级 | 仅有全局 | 全局 → 项目 → 子目录 |
| 动态注入 | 不支持 | 支持@引用其他文件 |
CLAUDE.md真正的威力在于分层。你可以在以下位置放置CLAUDE.md，Claude会按优先级合并：
~/.claude/CLAUDE.md # 全局设置（所有项目生效）
项目根目录/CLAUDE.md # 项目级设置
项目根目录/CLAUDE.local.md # 个人偏好（不commit）
子目录/CLAUDE.md # 子模块规则
7个进阶配置模式
模式1：代码风格强制执行
最基础也最重要的配置。把团队规范写进去，AI就不会写出风格迥异的代码。
## 代码风格规则
- 缩进：2空格，不使用Tab
- 分号：不使用分号（除非必须）
- 引号：字符串用单引号，JSX属性用双引号
- 导入顺序：第三方库 → 内部模块 → 类型 → 样式
- 文件名：组件用PascalCase（UserProfile.tsx），工具函数用camelCase（formatDate.ts）
- 函数：优先使用箭头函数，除非需要this绑定
- TypeScript：所有导出函数必须有显式返回类型
模式2：项目架构预加载（最重要的生产力提升）
告诉Claude你的项目怎么组织的，它就能更快定位到正确的文件。
## 项目架构速览
src/
├── app/ # Next.js App Router：页面和API路由
├── components/
│ ├── ui/ # shadcn/ui组件（不要修改）
│ ├── features/ # 功能组件（每个功能一个目录）
│ └── shared/ # 跨功能共享组件
├── lib/
│ ├── db/ # 数据库操作（Prisma）
│ ├── auth/ # 认证逻辑（NextAuth v5）
│ └── utils/ # 工具函数
├── hooks/ # 自定义React Hooks
├── types/ # TypeScript类型定义
└── styles/ # 全局样式
关键入口文件：
- 数据库Schema：`prisma/schema.prisma`
- 认证配置：`src/lib/auth/config.ts`
- API客户端：`src/lib/api/client.ts`
- 环境变量类型：`src/types/env.d.ts`
模式3：技术栈显式声明
明确告诉Claude你用了哪些库，以及它们的版本——版本差异往往是AI写错代码的主因。
## 技术栈（精确版本）
- 框架：Next.js 15.1 + React 19
- 语言：TypeScript 5.6（strict模式）
- 样式：Tailwind CSS 4.0 + shadcn/ui
- 数据库：Prisma 6.0 + PostgreSQL 16
- 状态管理：Zustand 5.0 + TanStack Query 5.60
- 表单：React Hook Form 7.53 + Zod 3.23
- 测试：Vitest 2.1 + Playwright 1.48
⚠️ 注意：我们用的是React 19，不要用React 18的Suspense旧写法。
Next.js 15是async组件默认模式，非页面组件的params不再自动传入。
模式4：安全护栏（防AI犯错的最有效手段）
这是很多人忽略但极其重要的一环。告诉Claude不能做什么，比告诉它做什么更重要。
## 安全护栏
❌ 禁止操作：
- 不要修改package.json中的依赖版本（手动管理）
- 不要修改prisma/schema.prisma（数据库迁移由DBA负责）
- 不要使用eval()或Function()构造函数
- 不要硬编码API密钥，用process.env读取
- 不要在客户端组件中直接访问数据库
- 不要引入超过500KB的新npm包（先问）
- 不要删除任何已有的测试用例
✅ 必须操作：
- 每次修改后运行相关的测试
- 新增数据库查询必须使用Prisma的参数化查询
- API响应的错误信息必须对用户友好（不要暴露内部错误）
- 所有用户输入必须经过Zod schema验证
模式5：输出格式约束
让AI的输出符合你团队的工作流习惯。这个特别适合用在commit message规范上。
## Git提交规范
使用Conventional Commits格式：
- `feat:` 新功能
- `fix:` Bug修复
- `refactor:` 重构
- `docs:` 文档
- `test:` 测试
- `chore:` 构建/工具
### PR描述模板
所有PR描述按以下格式：
变更说明
[一句话描述做了什么]
详细变更
- 变更点1
- 变更点2
测试计划
- [ ] 单元测试通过
- [ ] E2E测试通过
- [ ] 手动测试：场景描述
截图（如有UI变更）
模式6：领域知识注入
对于业务复杂的项目，注入领域知识是AI理解业务逻辑的关键。
## 业务领域知识
### 权限模型
- 角色层级：SuperAdmin > Admin > Manager > Editor > Viewer
- 权限检查通过 `usePermission('resource:action')` Hook
- 资源删除需要Admin以上角色 + 二次确认
### 计费逻辑
- 免费版：每月100次API调用
- Pro版（$29/月）：每月10,000次
- 超额后降级为队列模式（延迟<30s）
- 计费周期：UTC时间每月1日0点重置
### 命名约定
- API端点：`/api/v1/[resource]/[action]`（RESTful风格）
- 数据库表名：snake_case复数（user_profiles）
- GraphQL查询：camelCase（getUserById）
模式7：渐进式交付指令
这是让AI像高级工程师一样工作的关键——先做最小的可行改动，验证后再扩展。
## 工作流程
1. **先理解再动手**：修改前先阅读相关文件，确认影响范围
2. **最小改动原则**：每次只改必要的文件，不要过度重构
3. **测试先行**：如果请求包含新功能，优先写测试用例
4. **渐进交付**：
- 第一阶段：核心功能 + 基本测试
- 第二阶段：边界情况处理
- 第三阶段：性能优化和代码清理
5. **变更后必须**：
- 运行 `npm run type-check`
- 运行相关测试 `npm test -- --related`
- 如果有lint错误，先修复再提交
实战模板：直接复制使用
以下是一个可直接使用的CLAUDE.md模板，覆盖了大多数TypeScript/React项目：
# 项目：AI创业内参 CMS
## 技术栈
- Next.js 15.1（App Router） + TypeScript 5.6 strict
- Tailwind CSS 4.0 + shadcn/ui
- Prisma 6.0 + PostgreSQL 16（Supabase）
- NextAuth v5 + GitHub OAuth
- TanStack Query 5.60 + Zustand 5.0
- Vitest 2.1 + Playwright 1.48
## 目录结构
src/
├── app/ # App Router页面
├── components/ # shadcn/ui + 自定义组件
├── lib/ # 业务逻辑
│ ├── db/ # Prisma客户端和查询
│ └── auth/ # NextAuth配置
├── hooks/ # 自定义Hooks
└── types/ # TS类型
## 代码风格
- 缩进：2空格，无分号，单引号
- 组件名：PascalCase，文件名同组件名
- 导出函数必须有返回类型注解
- 优先使用async/await而非.then()
## 禁止操作
- 不修改package.json版本号
- 不修改prisma schema
- 不硬编码密钥
- 不引入超过100KB的新依赖
- 不删除已有测试
## 工作流程
1. 先理解再动手
2. 最小改动原则
3. 修改后运行type-check和相关测试
4. 自我审核：代码风格一致、无TS错误、无重复逻辑
## 命名约定
- API: /api/v1/资源/操作
- 数据库表: snake_case
- 组件props: {组件名}Props接口
常见坑和最佳实践
坑1：CLAUDE.md太长
CLAUDE.md的内容会占context window。如果超过200行，Claude的有效工作内存会减少。建议控制在50-150行。删除所有显而易见的内容（比如"用TypeScript写代码"这种废话）。
坑2：信息过时
CLAUDE.md是静态文件，项目演进后容易过时。建议在README里标注CLAUDE.md的最后更新时间和负责人，或者用CI检查关键路径是否存在。
坑3：忽略子目录CLAUDE.md
深层嵌套的子项目往往有特殊规则。在packages/database/CLAUDE.md里放数据库相关规则，主CLAUDE.md就不会被DBA的规则污染。
坑4：把CLAUDE.md当成文档
CLAUDE.md不是给人类看的文档——它是给AI看的。用命令式语气、列出规则、去除解释性文字。AI不需要你说"为什么"，它只需要知道"怎么做"。
❌ 错误写法：
"我们使用Prisma作为ORM，因为它提供了很好的类型安全和开发体验..."
✅ 正确写法：
"使用Prisma 6.0访问PostgreSQL。所有查询通过src/lib/db/prisma.ts导出的prisma实例。"
进阶技巧：动态CLAUDE.md
你可以用@语法引用其他文件，让CLAUDE.md保持简洁的同时覆盖更多内容：
## 项目上下文
@README.md # 引用README作为背景
## 类型定义
@src/types/index.ts # 所有TypeScript类型定义
## API文档
@docs/api/openapi.yaml # OpenAPI规范
这样，CLAUDE.md本身只需要写规则，具体文档内容通过引用注入，不会占用主体空间。
总结
CLAUDE.md的本质是项目级AI系统提示词。配置得当，Claude能像一个资深团队成员一样工作；配置不当，你只是在和一个"刚入职的新人"对话。
今天的行动项：
1. 检查你的项目是否有CLAUDE.md（如果没有，立刻创建）
2. 把当前最常让AI"改错"的问题写进禁止操作
3. 把你团队最核心的3条代码规范写进去
4. Commit并分享给团队
配置CLAUDE.md花你30分钟，但每天能帮你省下无数次"AI写错我改"的循环。