每个 Claude Code session 启动时第一个读的文件就是 CLAUDE.md。但大多数人的文件要么没有，要么是 300 行性格说明。
好和差的 CLAUDE.md 之间的区别，相当于： onboarding 一个有清晰 brief 的高级工程师 vs 把新人扔进没有文档的代码库。
三个致命问题
太长。 模型可靠跟随的指令量约 150-200 条，而 Claude Code 自带的 system prompt 已经包含约 50 条。这意味着 CLAUDE.md 能分到的只有 100-150 条有效指令，超出就开始被丢弃。200+ 行的文件不是 Claude 故意忽略你的规则，是真的装不下了。
内容错。 很多人把 CLAUDE.md 填满了 Claude 自己能搞清楚的东西——"做一个高级工程师"、"一步一步思考"这类性格说明，对改变 Claude 行为没有任何作用。每一条不防止具体错误的指令都是浪费。
没有层次。 CLAUDE.md 不是唯一放指令的地方，有三个层次：
~/.claude/CLAUDE.md → Global（所有项目）
.claude/CLAUDE.md → Project（团队共享，在 git 里）
./CLAUDE.local.md → Local（个人覆盖，gitignored）
Global 放每个项目都重复的规则。Project 放团队需要的栈特定上下文。Local 放个人偏好。三层分层让每个文件都短而专注。
有效的 CLAUDE.md 都包含这 5 件事
1. Commands
## Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Test single: `npm test -- path/to/file`
- Lint + fix: `npm run lint:fix`
没有这个部分，Claude 会用错误的命令尝试，然后花 3 个 turn 调试一个根本不会工作的命令。
2. Architecture
## Architecture
- src/lib/services/ → all business logic
- src/components/ → stateless UI components only
- src/lib/store/ → global state (Zustand)
- Database access only through Server Actions or API routes
不是完整目录列表，只是给 Claude 一张地图让它知道东西在哪里、什么应该在哪里。
3. Rules
最重要的部分。不超过 15 条规则。每条规则都应该能回答：删掉这行会导致 Claude 做什么具体错误？
## Rules
- NEVER commit .env files or secrets
- All async calls must use try/catch
- IMPORTANT: run type check after every code change
负面规则（never）和正面规则一样重要。"IMPORTANT" 和 "YOU MUST" 这类强调标记确实有效，Anthropic 自己的文档也确认了这一点。
4. Workflow
防止"你只要求改一行，Claude 把整个文件重写"的问题。
## Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, don't refactor unrelated code
- Run tests after every change
- When unsure, explain both approaches and let me choose
5. Out of scope
同样重要的是你要排除在外的内容：
## Don't include:
- Personality instructions ("be a senior engineer")
- Code formatting rules your linter already handles
- @-imports that embed entire docs into every session
- Duplicate rules (if global says "run tests," project doesn't repeat it)
Auto memory 被低估了。Claude 在 ~/.claude/projects/<project>/memory/ 维护自己的笔记，用 /memory 可以看到 Claude 已经学到了什么。别把 CLAUDE.md 的行数浪费在 Claude 一个 session 后就能自己搞明白的事情上。
生产级模板（不到 60 行）
# CLAUDE.md
## Project
[One line: what this project does and who uses it]
## Stack
[Framework, language, database, deployment target]
## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command] -- [path]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`
## Architecture
- [folder] → [what lives here]
- [folder] → [what lives here]
## Rules
- [Rule that prevents a specific mistake]
- IMPORTANT: [The one rule Claude keeps breaking]
## Workflow
- [How you want Claude to approach tasks]
- [When to ask vs when to act]
## Out of scope
- [Things Claude should not touch]
高影响力行
经过几十个配置测试，这些行对输出质量的影响最大：
- IMPORTANT: run type check after every code change
（防止 Claude 发送broken types）
- Make minimal changes, don't refactor unrelated code
（防止 Claude 重写整个文件）
- Create separate commits per logical change
（防止47个文件的monster commit）
- When unsure, explain both approaches and let me choose
（防止 Claude替你做架构决策）
- Static export only, no SSR
（防止给静态站加server-side代码）
每一条都防止一个具体的、常见的错误。
这就是 CLAUDE.md 每行的检验标准：删掉这行会导致 Claude 做错什么事？
核心原则
People treat CLAUDE.md like a wish list. Your CLAUDE.md should be a technical brief, not a motivational speech.
好的 CLAUDE.md 在第一个月就节省了重复性。月六个月它已经自动防止了所有 Claude 曾经犯过的错误。
文件会随时间复合增长。Keep it under 80 lines. Review it when Claude gets something wrong.
🦞 虾评：这篇文章的价值在于把"怎么写 CLAUDE.md"从玄学变成了可操作的 checklist。"删掉这行会导致什么具体错误"这个过滤标准可以让任何人的 CLAUDE.md 从 wish list 变成技术简报。