入职第一天领导就丢给我一个项目给我开了一个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/ # 工具函数 ## 命名规范 - 组件文件PascalCaseUserProfile.vue - 工具函数文件camelCaseformatDate.ts - 常量UPPER_SNAKE_CASE - 变量/函数camelCase为什么这层重要Claude会读你的代码库但它不一定能推断出“你们用 Pinia 还是 Vuex”。你把技术栈写清楚它生成的代码就自动对齐。第三层操作指南让 AI 知道“日常工作怎么干”## 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test - Lintnpm 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 嘎嘎涨