很多人刚开始用 Claude Code，都会干一件非常人类、也非常危险的事：

把 CLAUDE.md 当成项目祖传族谱。

项目历史？塞进去。
技术决策？塞进去。
个人偏好？塞进去。
公司价值观？也塞进去。
恨不得再写一句：“Claude，你要像爱护自己的孩子一样爱护这个项目。”

结果呢？

Claude 打开 2000 行上下文，表面上沉着冷静，内心其实已经开始乱码：

“你到底是让我改按钮，还是让我继承公司使命？”

最后它生成了一堆莫名其妙的代码，你一脸懵，它也一脸无辜。

这篇不讲 CLAUDE.md 的标准格式。
我们只聊实战里踩出来的 8 条经验：哪些做法看起来反直觉，但真的好用；哪些坑，踩一次就够了。

---

1. 越短越好，200 行是上限

反直觉点来了：

你以为信息越多，Claude 越懂你。
实际上，信息越多，Claude 越容易变成一个听了三小时需求会但只记住“按钮要大气”的实习生。

claude-code-best-practice 的作者 Boris Cherny 明确建议：

CLAUDE.md 不要超过 200 行。

这不是玄学。
Claude Code 每次会话都会加载 CLAUDE.md。你写的每一行废话，都在占用 Claude 理解代码的脑容量。

❌ 不要这样写

## 项目历史

2023 年，我们的 CTO 在一次 hackathon 上提出了这个伟大的想法。
当时夜色温柔，咖啡很苦，团队很燃……
接下来 300 行讲述公司创业史、品牌愿景、使命价值观……

Claude：
“所以……我要不要改这个 Button.tsx？”

✅ 应该这样写

## Project Overview

B2B 分析仪表盘，面向运营经理。

核心目标：
缩短「从数据到洞察」的时间。

优化优先级：
加载速度 > 交互丰富度 > 视觉花哨。

一个好 CLAUDE.md 的验证标准很简单：

一个没看过你项目的人，读完后能在 30 秒内回答：

1. 这是什么产品？

2. 技术栈是什么？

3. 新代码应该放哪里？

回答不上来，就说明它不是说明书，是散文。

---

2. “不要引入什么”和“要引入什么”同样重要

很多人会在 CLAUDE.md 里写技术栈：

## Tech Stack

- Next.js 15 App Router + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase

然后就放心了。

但 Claude 很热心。
热心到什么程度呢？

你没说不让它用 Redux，它可能觉得：

“这地方状态管理有点复杂，我给你上个 Redux 吧。”

你没说不让它用 Material UI，它可能觉得：

“这里 UI 组件有点多，我给你装个 MUI 吧。”

你没说不让它用 MongoDB，它甚至可能觉得：

“PostgreSQL 很好，但我突然想起 MongoDB 也不错。”

所以，禁止清单非常重要。

## Tech Stack

- Next.js 15 App Router + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase（认证 + 数据）

## Do NOT introduce unless explicitly requested

- Redux：项目已迁移到 React Context + Zustand
- styled-components：全站使用 Tailwind，不接受 CSS-in-JS
- Material UI：与 shadcn/ui 样式体系冲突
- MongoDB：数据层已锁定 PostgreSQL

这块非常值钱。

它防的不是一次小错误，而是防止 Claude 在你没注意的时候，悄悄引入一个不兼容依赖，然后你后面 10 次会话都在帮它擦屁股。

---

3. 规则必须可操作，不要靠感觉

很多 CLAUDE.md 都有这种“正确但没用”的规则：

## Coding Rules

- 写干净的代码
- 保持简洁
- 注重性能

这类规则看起来很专业，实际上对 AI 来说等于：

“你做菜要好吃一点。”

它当然想好吃。
问题是，什么叫好吃？

Claude 不懂“干净”。
Claude 懂的是：

• 用 named export，不用 default export

• 组件不超过 200 行

• 不用 any

• async/await 替代 then 链

❌ 模糊规则

## Coding Rules

- 写干净的代码
- 保持简洁
- 注重性能

✅ 可执行规则

## Coding Rules

- 使用 named export，路由文件除外
- 禁止 any 类型，用泛型或接口替代
- 单个组件不超过 200 行，确有必要时说明理由
- 使用 async/await，避免 Promise then 链
- 变量名全拼，不使用无意义缩写，id/url/ctx 除外
- 只在代码意图不明显时写注释
- 不保留注释掉的旧代码
- 不保留 console.log

判断一条规则好不好，有个简单测试：

看完这条规则，你能不能在 5 秒内判断一段代码是否符合？

能，就是好规则。
不能，就是给 Claude 喂鸡汤。

---

4. CLAUDE.md 是导航，不是图书馆

很多人想把所有架构文档都塞进 CLAUDE.md。

这就像你去问路，结果对方把整本城市规划史递给你。

CLAUDE.md 的职责不是保存所有信息。
它的职责是告诉 Claude：

需要什么信息，去哪里找。

更好的写法是：

## Project Context

- 架构总览：`docs/architecture.md`
- 工程设计决策记录：`docs/adrs/`
- API 文档：`docs/api.md`
- 部署流程：`docs/deploy.md`

这样 Claude 不需要每次都把全部架构文档读一遍。
它只需要知道：

“我要改接口，去看 docs/api.md。”

“我要理解架构，去看 docs/architecture.md。”

“我要查历史决策，去看 docs/adrs/。”

这就叫 渐进式上下文。

## Context Tiers

Tier 1（每次加载）：
- CLAUDE.md：项目是什么、技术栈是什么、基本规则是什么

Tier 2（按需加载）：
- docs/architecture.md
- docs/api.md
- docs/deploy.md

Tier 3（默认忽略）：
- docs/archive/
- legacy-notes/

普通用户的 CLAUDE.md 是知识大杂烩。
高手的 CLAUDE.md 是路由器。

一个负责装知识，一个负责指路。
后者明显更聪明。

---

5. 给敏感模块单独开一个本地 CLAUDE.md

很多人以为 CLAUDE.md 只能有一个，放在项目根目录。

其实不是。

某些目录的风险比其他目录高得多，比如：

• src/auth/

• src/payments/

• src/billing/

• infra/

• prisma/migrations/

这些地方可不是普通代码区。
这是项目里的“高压电房”。

你让 Claude 随便改登录逻辑、支付逻辑、数据库迁移，那就像让新来的实习生直接操作核反应堆。

解决办法：

在敏感目录里放一个本地 CLAUDE.md。

例如：

# src/auth/CLAUDE.md

## 安全红线

- 绝不修改 token 验证逻辑，除非用户明确要求
- 绝不引入新的认证方式，除非同步更新测试
- 所有认证相关变更必须通过 `pnpm test src/auth`

## 已知陷阱

- Magic link 生成依赖 `crypto.randomUUID()`，不要换成其他随机方法
- Session 存储在 Redis，不是内存，服务重启不会丢失
- 登录失败错误信息不能暴露具体原因，避免被枚举攻击

这就像给危险区域装护栏。

不是不让 Claude 进去。
是让它进去之前先戴安全帽。

---

6. 让 CLAUDE.md 驱动 Hook，不要只靠 Claude 记住

很多人会在 CLAUDE.md 里写：

- 每次修改代码后运行格式化
- 修改核心模块后运行测试

写得很好。
但 Claude 可能转头就忘。

不是它坏，是它太忙。
它一边读代码，一边改逻辑，一边处理上下文，一边还得假装自己很稳。

所以，重要规则不要只写在 CLAUDE.md 里。
要变成 Hook。

CLAUDE.md 里可以这样写：

## Hooks & Quality Gates

以下规则由 `.claude/hooks/` 强制执行，不只是提醒：

- 每次编辑后自动格式化：PreToolUse hook → prettier
- 核心模块变更后自动跑测试：PostToolUse hook → vitest related
- 禁止直接编辑 `src/auth/`、`src/billing/`、`prisma/migrations/`，除非先确认

对应 Hook 示例：

{
  "hooks": [
    {
      "matcher": "Edit|Write",
      "command": "npx prettier --write ${CLAUDE_FILES}",
      "on_failure": "warn"
    }
  ]
}

写在 CLAUDE.md 里的规则是：

“请你记住。”

配了 Hook 的规则是：

“不好意思，你必须执行。”

一个靠自觉。
一个靠制度。

成年人都知道，制度比较靠谱。

---

7. 用 MEMORY.md 建立长期记忆回路

Claude Code 的一个问题是：

每次新会话，它都像刚入职第一天。

你上周刚告诉它：

“这个项目的支付逻辑很特殊，不能动。”

下周它又一脸天真：

“我优化了一下支付逻辑。”

你：
“你优化的是我的血压。”

其实不一定需要复杂的向量数据库，也不一定需要一堆记忆系统。

一个简单的 MEMORY.md 就够用了。

在 CLAUDE.md 里加：

## Memory

`MEMORY.md` 记录之前任务中发现的关键洞察、最佳实践和已知陷阱。

每次新任务开始前：
- 先读取 `MEMORY.md`

每次任务结束后：
- 如果发现新的项目规则、踩坑点或重要决策，更新 `MEMORY.md`
- 不记录临时信息
- 不记录无价值的过程细节

MEMORY.md 可以长这样：

# MEMORY.md

## 已知陷阱

- 用户表的 `role` 字段只用于前端展示，权限判断必须走 `permissions` 表
- billing 模块不能直接调用 Stripe SDK，必须通过 `lib/billing/provider.ts`
- dashboard 页面首屏性能优先，不要引入重型图表库

## 项目偏好

- 新组件默认放在 `src/components/feature-name/`
- API 请求统一使用 `lib/api/client.ts`
- 表单优先使用 react-hook-form + zod

这玩意儿简单、可控、可 Git 追踪。

成本：一个文件。
收益：Claude 不再每次都像刚下载的新软件。

---

8. 用 CLAUDE.md 代替每次会话的开场白

很多人每次打开 Claude Code，都要先说一堆：

“你先不要写代码，先给方案。”

“不确定的地方要问我。”

“不要废话。”

“回复用中文。”

“不要乱引包。”

“重大改动前先确认。”

这些话不是不能说。
但每次都说，就像每天上班都要重新教同事怎么呼吸。

更好的办法是，把你的工作风格直接写进 CLAUDE.md。

## My Working Style

- 先给方案，不要直接写代码
- 不确定时列出选项，不要擅自猜测
- 重大变更前先问，小优化可以直接执行
- 不要使用 “Great question!”、“I'd be happy to help!” 这类寒暄废话
- 回复使用中文，代码注释使用英文
- 文件路径使用绝对路径，不要使用相对路径

这几行的价值非常高。

它不是在“训练 Claude 的性格”。
它是在节省你每次新会话的前 5 条消息。

Claude 从第一句就知道：

• 你喜欢什么节奏

• 你讨厌什么废话

• 哪些事可以直接做

• 哪些事必须先问

这比你每次手动提醒高效得多。

---

一张表总结

经验	错误做法	推荐做法
控制长度	写成 2000 行项目百科	控制在 200 行以内
禁止清单	只写要用什么技术	同时写清楚不要引入什么
规则可执行	“写干净代码”	“禁止 any、组件不超过 200 行”
文档定位	把所有文档塞进 CLAUDE.md	用 CLAUDE.md 指向外部文档
敏感模块	所有目录共用一套规则	auth/billing/infra 单独放本地 CLAUDE.md
质量保障	指望 Claude 记得跑测试	用 Hook 强制执行
长期记忆	每次会话重新解释	用 MEMORY.md 记录项目经验
工作风格	每次开场重复交代	写进 CLAUDE.md 固化下来

---

现在就能做的 5 件事

不用等“有空再优化”。
现在打开你的 CLAUDE.md，直接做这 5 件事：

1. 删到 200 行以内
   删不掉的，通常都没那么重要。

2. 加一个 Do NOT introduce 区块
   至少列出 3 个不能随便引入的库或方案。

3. 把模糊规则改成可验证规则
   不写“保持简洁”，改写“组件不超过 200 行”。

4. 给敏感目录加本地 CLAUDE.md
   重点照顾 auth、billing、infra、migrations。

5. 加一个 MEMORY.md 机制
   让 Claude 把项目里的坑记下来，而不是每次重新摔一遍。

---

最后说句人话

CLAUDE.md 不是一次写完就供起来的神龛。
它应该是一个活文件。

Claude 每踩一次坑，你就补一条规则。
Claude 每次做对一件事，你就沉淀一条经验。
Claude 每次乱引一个库，你就更新一次禁止清单。

一个月后你再看，会发现 Claude 从一个刚入职、到处问“这个能不能删”的菜鸟实习生，慢慢变成了一个真正懂你项目的高级工程师。

前提是：

别再把 CLAUDE.md 当垃圾桶。

它不是垃圾桶。
它是 Claude 的作战地图。