Appearance
同样的Claude Code，有人用起来像神仙搭档，有人用起来像实习生——差别就在这个文件。
写好CLAUDE.md，AI从实习生变老员工——知道你的项目怎么跑、代码怎么写、文件怎么组织，不用你每句话都解释一遍。
CLAUDE.md到底是什么
一个放在项目根目录的Markdown文件，Claude Code每次启动时自动读取。
你可以把它想象成新员工入职第一天拿到的那份手册：
- 公司用什么技术栈
- 代码放哪个目录
- 提交规范是什么
- 有哪些坑千万别踩
没有这份手册，新人只能靠猜。有了，第一天就能干活。
最快上手：用/init自动生成
bash
/init它会自动扫描代码库，生成一份基础版CLAUDE.md。这是起点，不是终点——自动生成的版本大概能打50分，你得自己补到90分。
六块内容，缺一不可
第一块：项目概况
AI第一件要知道的事：这个项目是干嘛的。
markdown
# 项目概况
这是一个在线教育平台的前端项目，使用 React + TypeScript。
面向 K12 学生，支持课程浏览、视频播放、作业提交。
当前处于 v2 重构阶段，正在从 Class 组件迁移到 Hooks。写作要点：
- 一句话说清项目类型和用户
- 写明技术栈
- 提当前处于什么阶段
第二块：常用命令
AI要跑测试、构建项目、格式化代码，得知道命令。
markdown
# 常用命令
- 启动开发服务器：npm run dev
- 构建：npm run build
- 测试：npm test
- 单个测试：npm test -- path/to/test.ts
- 代码检查：npm run lint
- 格式化：npm run format写作要点：
- 只写常用的，不用穷举
- 有特殊参数的命令写完整
- 多环境要写清楚每个环境的启动方式
第三块：代码规范
没有规范，AI写的代码风格可能每次都不一样。
markdown
# 代码规范
- 使用 2 空格缩进，不用 Tab
- 字符串用单引号
- 变量命名用小驼峰（camelCase），组件用大驼峰（PascalCase）
- 优先使用 interface 定义类型，而非 type
- 组件使用函数式写法 + Hooks，不使用 Class 组件
- 每个组件一个文件，文件名和组件名一致
- 注释用中文写作要点：
- 格式类规则最重要（缩进、引号、命名）
- 可以直接写"遵循 ESLint + Prettier 配置"
第四块：项目结构
AI不知道哪个目录放什么，就会在错误的地方创建文件。
markdown
# 项目结构
- src/pages/ — 页面组件，每个页面一个文件夹
- src/components/ — 通用组件，可跨页面复用
- src/hooks/ — 自定义 Hooks
- src/services/ — API 请求层
- src/utils/ — 工具函数
- src/types/ — TypeScript 类型定义
- src/styles/ — 全局样式和主题变量
关键约定：
- 页面组件只能被路由引用，不能被其他页面直接导入
- services 层统一处理错误，组件里不直接调 fetch/axios写作要点：
- 不用列每个文件，只列目录级别
- 关键约定比目录结构更重要
第五块：踩坑记录
这是最被低估的一块。你踩过的坑，不写下来，AI也会踩一遍。
markdown
# 已知问题和注意事项
- 🚫 不要使用 moment.js，项目已全面迁移到 dayjs
- 🚫 不要修改 src/types/global.d.ts，那是第三方类型补丁
- ⚠️ src/services/auth.ts 里的 token 刷新逻辑有特殊处理，修改前务必先读完整个文件
- ⚠️ 构建时偶尔会出现缓存问题，如果 build 失败先试 npm run clean
- 📝 数据库迁移文件按时间戳命名，格式：YYYYMMDDHHmmss_description.sql写作要点：
- 用emoji标记严重程度：🚫禁止、⚠️小心、📝记住
- 不仅写"别做什么"，也写"出了问题怎么办"
第六块：工作流偏好
这一块决定了AI"怎么干活"。
markdown
# 工作流偏好
- 每次修改代码后，自动运行相关测试
- 提交信息格式：type(scope): description
- type 包括：feat / fix / refactor / docs / test / chore
- 改动超过 3 个文件时，先列出改动计划让我确认，再动手
- 不要自动 push 到远程，我只在手动确认后才推送进阶技巧
不同项目用不同的CLAUDE.md
CLAUDE.md是跟着项目走的，放在项目根目录就行。每个项目一份，互不干扰。
团队共享：纳入版本控制
把它提交到Git仓库，团队所有人用Claude Code都能读到同一份规范。
渐进式维护
不用一开始就写完美。先用/init生成基础版，然后每次遇到AI犯错，就加一条规则。
别写太长
CLAUDE.md太长（超过200行），AI反而容易忽略关键信息。控制原则：
- 每个板块5-10行，只写最重要的
- 不确定要不要写？先不写，等AI犯错了再补
- 用简洁的短句，别写散文
常见问题
| 问题 | 答案 |
|---|---|
| 不写会怎样？ | 能用，但体验差很多。写了好用十倍。 |
| 可以放多个吗？ | 可以。项目根目录放全局的，子目录里可以放局部的。 |
| 和.cursorrules区别？ | 功能一样，只是不同工具叫不同名字。 |
| 内容会被发送到哪里？ | 只发送给API，不会公开，不会用于训练。 |
完整模板
markdown
# 项目概况
[一句话描述项目是什么、用什么技术栈、当前什么阶段]
# 常用命令
- 启动：[命令]
- 构建：[命令]
- 测试：[命令]
- 检查：[命令]
# 代码规范
- 缩进：[规则]
- 引号：[规则]
- 命名：[规则]
- [其他3-5条规则]
# 项目结构
- src/[目录]/ — [说明]
- 关键约定：
- [规则1]
- [规则2]
# 已知问题和注意事项
- 🚫 [禁止做的事]
- ⚠️ [要小心的事]
- 📝 [要记住的事]
# 工作流偏好
- 修改后自动跑测试
- 提交格式：[格式]
- [其他偏好]10分钟填完，立刻生效。同样的Claude Code，写好CLAUDE.md之后，像是换了一个AI。
