这是啥
CLAUDE.md 是放在项目根目录的一个 markdown 文件。Claude Code 每次启动自动读它，相当于给 AI 的一张”项目说明书”。
官方 claude-code-docs/memory.md 的措辞：
“Claude Code automatically loads CLAUDE.md into context at the start of every session.”
三层结构
重要但大家常忽略：CLAUDE.md 有三层，作用域不同。
| 层 | 路径 | 作用域 | 谁维护 |
|---|---|---|---|
| 项目级 | ~/my-project/CLAUDE.md | 只对这个项目生效 | 团队 |
| 个人项目级 | ~/my-project/CLAUDE.local.md | 只对你本机+这个项目 | 你自己（不进 git） |
| 全局级 | ~/.claude/CLAUDE.md | 所有项目都生效 | 你自己 |
三层都会被读，合并进上下文。规则冲突时，局部覆盖全局。
来源：claude-code-docs/memory.md + best-practices-page.md “Memory” 节。
该写啥、不该写啥
官方 best-practices-page 给的明确表（✅ Include / ❌ Exclude）简化版：
✅ 该写：
- 常用 bash 命令（
npm test、bun run build） - 代码风格约定（用 tab 还是 space、用 literal union 不用 enum）
- 项目结构说明（这个目录放啥）
- 测试怎么跑、部署怎么做
- 常见错误的预防（“不要用 enum”、“不要 stop 容器”）
❌ 别写：
- 应该靠 prompt 每次说的临时要求
- 保密信息（API key、密码、内部 URL）
- 超长的东西（> 2000 行就该拆）
- 无关的历史变更日志
Boris 的核心做法（tip 4+5，单点来源但非常有代表性）
Boris 团队的 CLAUDE.md 有两个关键习惯：
做法 1：错了就记进去（tip 4 原文）
“Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.”
CLAUDE.md 不是一次写完，是持续增长的错题本。Claude 犯一次错 → 加一条规则。
做法 2：PR 评论里直接 @claude 加规则（tip 5）
nit: use a string literal, not ts enum
@claude add to CLAUDE.md to never use enums
Claude 自动把规则加进 CLAUDE.md 并提交。Boris 称这是 “Compounding Engineering”。
一个能直接抄的最小模板
（合成自官方 best-practices + awesome-claude-code 23 份样本的共同结构）
# [项目名]
## 项目简介
（一段话讲这是啥，为谁做）
## 常用命令
- `npm test` — 跑测试
- `npm run dev` — 本地开发
- `npm run lint` — 提交前检查
## 代码约定
- 用 TypeScript，禁用 `any`
- 优先 `type`，不用 `interface`
- 不用 `enum`，用 string literal union
- 文件名小写，用 `-` 连接（不用下划线）
## 目录结构
- `src/` — 源码
- `tests/` — 测试
- `docs/` — 文档
## 不要做
- 不要直接改 `main` 分支
- 不要在代码里写死 API key
- 不要 `git push --force` 到共享分支
## 犯过的错（持续增长）
- 不要把 `async` 函数标成 `void`（2026-04-10 踩过）
- ...23 份真实样本的共同特征
扫了 awesome-claude-code 仓库里 23 份真实项目的 CLAUDE.md，出现频率最高的几段：
- 项目简介（23/23，100%）
- 常用命令（22/23）
- 代码约定/风格（20/23）
- 目录结构（18/23）
- “不要做”清单（15/23，但陈彬认为这一段是最重要的，见下）
陈彬视角
“不要做”清单比”要做”清单重要 3 倍。
原因：AI 犯错的方式远多于做对的方式。你告诉它做对，它有 1000 种做对的方式；你告诉它不要做什么，禁区就是禁区。CLAUDE.md 的价值一大半在禁区描述。
另一个独立观察：CLAUDE.md 写得好不好，基本等于你”工作方式的自我觉察度”有多高。清晰的人写出清晰的 CLAUDE.md；自己都说不清自己咋干活的人，CLAUDE.md 必然一团糟。