入职第一天，领导就丢给我一个项目，给我开了一个key，让我接好AI，开发一个小程序。我按部就班，一步一步，从安装环境，到接通AI ，再到拉取并梳理项目，一步一步开发，最终有了雏形。
当我得意洋洋的将自己的作品拿给领导看时，领导黑着脸说："你这写的啥呀，这个按钮是红色的，那个按钮是绿色的，这个组件多一个输入框，同一个组件在那里就少了一个输入框，还有就是不同的页面，完全不同的风格......"
问题出在哪？我记得我明明跟AI 反复叮嘱按钮要一个颜色风格呀，大概是自己做的不够细心吧，正当我准备回去再好好修改时，领导淡淡说道："不要急着写，先定好规范！"
如果你发现 自己与AI 对话的时候，总是说了很多遍的东西，它仍然还是写错了，或者不按照你的要求去写，那么你非常需要阅读这篇文章。
一、CLAUDE.md 到底是什么？
一句话定义：Claude Code 启动时自动读取的项目说明书 + 行为准则。
大白话就是：这是 Claude 的"入职培训手册"。
想象一下，你公司来了个新员工（Claude）。他智商 180，什么都会。但如果不给他看《员工手册》，他可能：
代码风格和团队完全不一样
不知道项目依赖什么库
看不懂你们私有的工具链CLAUDE.md 就是这本手册。
每次你打开 Claude Code，它会自动扫描项目根目录下的 CLAUDE.md，把里面的内容当作"背景知识"加载。
你不需要每次都重复说"我们项目用 React 18，状态管理用 Zustand......"------写进这个文件，Claude 一次全记住。
二、为什么必须写 CLAUDE.md？
没有 CLAUDE.md 之前，我每天至少浪费 30 分钟重复这些话：
"我们项目用的是 Vue 3，不是 React"
"API 请求要放在 src/api/ 目录下"
"组件命名用 PascalCase，文件命名用 kebab-case"
"测试要用 Vitest，不是 Jest"有了 CLAUDE.md，我说一遍就够了。
核心价值：
| 没有 CLAUDE.md | 有 CLAUDE.md |
|---|---|
| 每次会话重复解释 | 一次配置，终身生效 |
| Claude 瞎猜你的意图 | Claude 精准理解 |
| 代码风格飘忽不定 | 风格稳定一致 |
| 新人上手要看半天 | Claude 就是最佳向导 |
三、怎么写出一份好用的 CLAUDE.md？
我踩过无数坑，总结出这套"三明治"结构。
第一层：身份与原则（让 AI 知道"我是谁"）
# 项目身份
你是一名资深全栈工程师，负责维护【项目名称】。
## 核心原则
- **代码可读性优先**：别炫技，写让人能看懂、能直接改的代码
- **最小修改原则**：只改我让你改的地方，别顺手"优化"我没提的代码
- **先问后做**：复杂任务（超过5步）先给方案，我确认后再动手
- **安全第一**：绝不允许把密钥、密码写进代码为什么这层重要？
Claude 默认是"热心肠"，你让它修一个 bug，它可能顺便重构整个模块(买一送一)。这层规则就是告诉它：别自作主张，别乱改。
第二层：技术栈（让 AI 知道"我们用什么"）
## 技术栈
- 前端：Vue 3 + TypeScript + Vite
- UI 库：Element Plus
- 状态管理：Pinia
- 后端：Node.js + Express + TypeScript
- 数据库：PostgreSQL + Prisma ORM
- 测试：Vitest（前端）+ Jest（后端）
## 目录结构
src/
├── api/ # API 请求封装
├── components/ # 公共组件
├── composables/ # Vue 组合式函数
├── stores/ # Pinia 状态
├── types/ # TypeScript 类型
└── utils/ # 工具函数
## 命名规范
- 组件文件：PascalCase（`UserProfile.vue`）
- 工具函数文件：camelCase（`formatDate.ts`）
- 常量：UPPER_SNAKE_CASE
- 变量/函数：camelCase为什么这层重要？
Claude 会读你的代码库，但它不一定能推断出"你们用 Pinia 还是 Vuex"。你把技术栈写清楚，它生成的代码就自动对齐。
第三层：操作指南（让 AI 知道"日常工作怎么干"）
## 常用命令
- 开发：`npm run dev`
- 构建：`npm run build`
- 测试：`npm run test`
- Lint：`npm run lint`
- 类型检查：`npm run type-check`
## 避坑指南（本地特殊配置）
- 本地 API 地址：`http://localhost:3000/api`
- Redis 端口是 6380（不是默认的 6379）
- 静态资源 CDN 在本地不生效，用代理
## 代码规范
- 所有 API 请求必须通过 `src/api/` 下的模块，禁止在组件里直接写 `fetch`
- 组件 props 必须定义类型
- 异步操作必须有 loading 和 error 状态
- 用户输入的文本必须用 `escapeHtml()` 转义为什么这层重要？
这些是"经验之谈"，是文档里没有、但每个老员工都知道的"潜规则"。写进 CLAUDE.md，新人（和 Claude）就不会踩坑。
四、实战模板：一个完整的 CLAUDE.md
这是我正在用的真实模板，你可以直接改：
# 项目：电商后台管理系统
## 角色定位
你是一名工作30年的全栈程序员，你也是这个项目的核心维护者，代码必须生产可用。
## 核心规则
- 所有 Vue 组件必须使用 `<script setup>` 语法
- API 调用必须在 `src/api/` 下定义，组件内通过 `import` 调用
- 禁止在组件内直接写 `console.log`，使用 `src/utils/logger.ts`
- 提交代码前确保 `npm run type-check` 通过
## 技术栈
- Vue 3.4+ + TypeScript 5.0+
- Vite 5.0+ / Element Plus 2.5+
- Pinia 2.1+ (状态管理)
- Vue Router 4.2+
## 目录结构
src/
├── api/ # API 接口定义（按模块划分）
├── assets/ # 静态资源
├── components/ # 公共组件
├── composables/# 组合式函数
├── layouts/ # 布局组件
├── router/ # 路由配置
├── stores/ # Pinia 模块
├── types/ # TS 类型定义
├── utils/ # 工具函数
└── views/ # 页面组件
## 常用命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 生产构建
- `npm run test` - 运行单元测试
- `npm run lint` - ESLint 检查
- `npm run format` - Prettier 格式化
## 特殊约定
- 日期处理统一用 `dayjs`（已配置 UTC 插件）
- 金额单位统一用"分"，前端展示时 `/100`
- 所有表单必须有防重复提交机制
- 敏感操作（删除、禁用）必须有二次确认
## 排除范围
- 不要修改 `src/assets/styles/element-override.css`（团队公共文件）
- 不要删除 `src/types/global.d.ts`
- 不要直接在 `main.ts` 里加代码，用插件模块
## 核心思维模式
- **模块化**：逻辑必须解耦，单一职责原则
- **防御性编程**：必须考虑边界条件、错误处理和日志记录
- **性能意识**：避免不必要的计算和重复渲染
- **可读性 > 简洁性**：代码应自解释，除非逻辑复杂否则不写废话注释
## 响应行为规范 (Response Guidelines)
1. **语言限制**：所有解释、思考过程和注释必须使用 **中文**
2. **思考先行**：在给出代码前，先用一句话描述你的核心实现思路
3. **代码完整性**：修改代码时，给出完整的函数块或文件，避免使用 `// ... rest of code` 导致无法直接应用。
4. **验证提醒**：如果你的修改可能破坏现有依赖，必须在末尾发出警告
5. **避免冗余**：使用最少代码实现功能，避免冗余
6. **最小优化**：如果要优化现有代码，确保你的修改是必要的五、项目级 vs 全局级：放哪不一样？
Claude Code 支持多个层级的配置文件：
| 路径 | 作用域 | 适用场景 |
|---|---|---|
| ~/.claude/CLAUDE.md 全局（所有项目） | 全局（所有项目） | 个人编码习惯、通用偏好 |
| ./CLAUDE.md | 当前项目根目录 | 团队共享的规范、技术栈 |
| ./.claude/CLAUDE.md | 前项目根目录（隐藏版） | 同上，不想污染根目录 |
| ./CLAUDE.local.md | 本地（不提交 Git） | 个人私有配置，比如本地 API 地址 |
全局配置放个人习惯：使用中文注释、回答要简洁、禁止生成网络链接
项目配置提交到 Git：技术栈、目录结构、代码规范、特殊约定
本地配置加入 .gitignore：本地数据库连接、个人 API key
区分原则：其他开发者拉项目需要知道的 → 项目级；你自己舒服的 → 全局级。
六、如何让 CLAUDE.md 长期好用？
1. 用 /init 生成初稿
在项目根目录打开 Claude Code，输入 /init，它会自动扫描代码库生成初稿。虽然不完美，但能帮你省 80% 的工作量。
2. 持续迭代
每次 Claude "犯错"，把错误规则写进 CLAUDE.md。比如：
"别在组件里直接用 fetch 了，我刚才已经说过一次了。我帮你把这个写进 CLAUDE.md，下次别犯了。"
3. 定期审查
技术栈会变，规则会过时。每季度看一遍 CLAUDE.md，删除过时内容、补充新的踩坑经验。
4. 团队共享
把 CLAUDE.md 提交到 Git，团队成员拉下来就能用。新同事入职，对着这个文件就能快速上手------而且 Claude 就是他的"贴身导师"。
总结
磨刀不误砍柴工，无论是新项目还是老项目，一定要花点时间 做好这个规范，有了它，不仅能提升我们的与AI 交互效率，还能大幅度降低token（与AI 反复拉扯，token 嘎嘎涨）