上一篇说过：没有 CLAUDE.md 的 Claude Code，每次启动都是"新员工第一天入职"。 这一篇就把这份"入职手册"的写法一次讲透——放哪、写什么、怎么判断该不该写。 全文 10 分钟读完，读完就能动手。
它解决什么问题
Claude Code 的每个会话都是全新开始，它不记得你上次说过什么。于是很多人 每天都在重复同样的对话：
- "用 pnpm，别用 npm" —— 每天说一遍
- "测试要跑 pnpm test:unit" —— 每天说一遍
- "别动 legacy 目录" —— 说晚了，已经动了
CLAUDE.md 就是把这些话写下来的地方。它会在每次会话开始时自动注入， 相当于给每个"新员工"发一份不用你亲自讲的入职手册。
放在哪：三个层级
| 位置 | 作用范围 | 放什么 |
|---|---|---|
项目根目录/CLAUDE.md | 这个项目、所有协作者 | 项目规矩（提交进 git，团队共享） |
~/.claude/CLAUDE.md | 你机器上的所有项目 | 个人偏好（中文回复、常用习惯） |
子目录/CLAUDE.md | 该子目录 | 大型仓库里某模块的特殊规矩 |
新手记住第一行就够了：项目根目录建一个，提交进 git。
写什么：五类硬规矩
1. 命令。构建、测试、检查怎么跑。这是回报率最高的几行字：
- 开发：pnpm dev
- 测试：pnpm test（提交前必须全绿）
- 类型检查：pnpm typecheck
2. 风格禁令。只写"不许做什么"，比写"提倡什么"有效得多：
- 禁止 any 类型，宁可写 unknown + 类型收窄
- 禁止 class component，一律函数式
- 不要引入新依赖，需要时先问我
3. 目录禁区：
- src/generated/ 是代码生成产物，永远不要手改
- migrations/ 只增不改
4. 工作流约定：
- 提交信息格式：feat/fix/chore + 中文描述
- 改完代码必须跑测试再报告完成
5. 项目黑话。团队里"人人都懂"但外人不懂的：
- "工作台"指 src/workbench 模块，不是 dashboard
- 环境变量在 .env.local，模板见 .env.example
一个可以直接抄的完整模板
# CLAUDE.md
## 命令
- 开发：pnpm dev / 测试：pnpm test / 检查：pnpm lint && pnpm typecheck
## 硬规矩
- 包管理只用 pnpm
- 禁止 any；禁止 console.log 进提交
- src/legacy/ 只读；migrations/ 只增不改
- 新依赖必须先询问
## 工作流
- 提交信息：type + 中文一句话
- 任何代码改动，完成前必须跑 pnpm test 并确认全绿
## 项目速查
- 状态管理用 zustand，store 都在 src/stores/
- API 层在 src/api/，用的是 openapi 生成的 client，别手写 fetch
就这么长。短，是特性，不是偷懒——它每个会话都要被读一遍， 你写的每一行都在花你的 token 和它的注意力。
三个最常见的写坏方式
❌ 写成项目介绍 PPT："本项目致力于打造业界领先的……" AI 不需要被感动，它需要知道测试命令是什么。
❌ 直接复制 README：README 是给人看的（怎么安装、什么功能）， CLAUDE.md 是给 AI 看的（怎么干活、什么不许碰），职责完全不同。
❌ 一次写几百行：里面 90% 是"万一用得上"。用不上。 从 10 行开始，让它自然生长。
最重要的心法：它是活文档
CLAUDE.md 不是一次写完的，是养出来的。规则很简单：
每次 Claude 做错一件事，就问自己：哪句话写进 CLAUDE.md 能让它下次不犯？ 写进去。没有这句话就删掉的行，一律不写。
坚持两周，你会得到一份完全贴合你项目的规矩清单——这就是"你的 Claude Code 比别人的聪明"的全部秘密。
这是《Claude Code 中文实战手册》连载的第 2 篇免费章节。完整手册会覆盖 6 份不同项目类型的 CLAUDE.md 模板、权限配置、skills/hooks 自动化、 省钱指南等。评论区有任何 Claude Code 的问题，我都会回。
