CLAUDE.md 写了一周后，我不再需要重复解释我的项目
每次开新 session 都要跟 Claude Code 解释一遍项目结构、构建命令、代码风格。一周前我认真写了一份 CLAUDE.md，从此再没说过"不是那个文件""用 ESM 不是 CommonJS""测试命令是 npm test"。这篇聊聊 CLAUDE.md 的结构设计、写什么不写什么、以及几个让我效率翻倍的 trick。
你有没有这种体验：用 Claude Code 改代码，每改一个模块都要先跟它解释一遍项目的基础设定？
"这个项目用 pnpm，不是 npm"
"路由文件在 src/router/ 下，不在根目录"
"测试不要用 jest，用 vitest"
"那个 config 文件是自动生成的，你别动它"
每次我都想，这次说完了它应该记住了吧。下一个 session，同样的问题再来一遍。Claude Code 又没有跨 session 的记忆——每次启动都是一张白纸。你跟它说的话，关门就清零。
所以 Claude 团队设计了一个解决方案：CLAUDE.md。
它不是给你看的，是给 Claude 看的。放在项目根目录下，每次 session 启动时自动加载。
听起来很简单是吧？但怎么写、写什么、不写什么——我踩了不少坑才找到感觉。
先让它自己写一份草稿
Claude Code 自带一个初始化命令。在你的项目根目录下，直接输入：
/init
Claude 会扫描你的项目结构，分析 package.json、tsconfig、测试框架、目录布局，自动生成一份 CLAUDE.md 草稿。
我第一次试的时候，它写出来的大概是这样：
# CLAUDE.md
## Build/Toolchain
- npm run build
- npm test
- npm run lint
## Project Structure
- src/ 源码
- src/components/ React 组件
- src/utils/ 工具函数
- tests/ 测试文件
骨架有了，但这远远不够。真正有价值的东西，需要你根据自己的踩坑经历来填充。
写什么：把那些你重复说过的话写进去
我给自己定了三条规则，决定什么该写进 CLAUDE.md：
- Claude 没法从代码中推断出来的东西
- 你至少跟它说过两次以上的东西
- 搞错了后果比较严重的东西
用这三条筛下来，我写进了以下内容：
# CLAUDE.md
## Build/Test
- Build: npm run build (tsc)
- Test: npm test (vitest，不是 jest)
- Lint: npm run lint (eslint)
- Type check: npx tsc --noEmit
## Code Style
- 使用 ES module (import/export)，不用 CommonJS (require)
- React 组件用函数式 + hooks，不用 class 组件
- 类型定义放在 src/types/ 下，不要散落在各处
- CSS 用 Tailwind，不写单独的 .css 文件
## Project Gotchas
- src/generated/ 下的文件是自动生成的，不要手动修改
- 数据库 schema 定义在 prisma/schema.prisma，不要直接在数据库里改
- API 路由定义在 src/router/ 下，不写在组件里
- 环境变量定义在 .env.example 里，.env 文件不要提交
注意看第二条"代码风格"——这些规则单独看每一条都不难，但你要是一条条跟 Claude 解释，每次开 session 都要花五分钟。写在 CLAUDE.md 里之后，这些对话彻底消失了。
不写什么：写了反而起反作用的
这是我觉得最重要的一节。
CLAUDE.md 不是文档，是配置。它的目的是让 Claude 的行为符合你的预期，不是给你自己看的知识库。
所以以下东西不要写：
Claude 本来就知道的事情。 比如"Python 用 4 空格缩进"——Claude 当然知道。你写进去只会稀释真正重要的指令，让它忽略你的实际要求。
变化频繁的信息。 比如"当前迭代正在开发用户权限模块"——这种信息应该出现在对话里或 issue 里，写进 CLAUDE.md 就等着过时吧。
长篇大论的教程。 不要把整个 API 文档粘进去。CLAUDE.md 应该是小而精的，越长 Claude 越不读。你可以用 SKILL.md（之后会聊）按需加载大块知识。
废话。 我见过有人在 CLAUDE.md 里写"请编写高质量的代码""代码要保持可读性"。这跟没写一样。Claude 不会因为你在配置里说"请写好代码"就突然变厉害。
我给自己的判断标准是：删掉这一行，Claude 会不会犯错？ 不会就删。
一个让我效率翻倍的 trick：每次纠正后更新它
这是我从官方文档里学到最好的一个模式。
每次 Claude 做错了什么，我在纠正它的时候会多加一句：
"不要这么做，更新你的 CLAUDE.md 以免再犯。"
比如有一次，Claude 在改代码时把 import { z } from 'zod' 写成了 const z = require('zod')。我说：
"项目用的是 ESM，不是 CommonJS。引入方式更新到你的 CLAUDE.md。"
它读了我的 CLAUDE.md，发现里面有一行"使用 ES module 语法"，但不够具体。于是它自动加了一条"import 语句不要用 require 替代"。
下次 session 再启，这句话已经被记住了。
这个模式的效果是：每次犯错都变成了配置的迭代。 不是我在反复纠正同一个问题，而是每纠正一次，CLAUDE.md 就更完善一点。运行一周之后，Claude 在我项目里的"低级错误"几乎消失。
多个 CLAUDE.md 怎么组织
根目录的 CLAUDE.md 是全局的。但 Claude Code 支持多级配置，我现在的结构是这样的：
~/.claude/CLAUDE.md # 全局配置（所有项目通用）
~/myproject/CLAUDE.md # 项目配置（跟团队共享）
~/myproject/CLAUDE.local.md # 个人配置（加了 .gitignore）
全局的 ~/.claude/CLAUDE.md 我放的是个人偏好，比如"回复用中文""代码用 2 空格缩进"。这些跟具体项目无关，是我个人的风格。
项目的 CLAUDE.md 我提交到 Git 里，团队一起维护。这样无论谁用 Claude Code 改这块代码，都能享受到同样的配置。
CLAUDE.local.md 放的是我个人的项目 notes，比如"这个模块下周要重构，不要花太多精力优化"。
多级配置会合并——先加载离根目录最近的，然后用子目录的覆盖。所以不用担心冲突的问题。
两个踩过的坑
坑一：CLAUDE.md 太长了 Claude 反而不听话。
我第一版写了将近 80 行，面面俱到。结果 Claude 经常忽略某些指令。我一开始以为是模型问题，后来发现是配置太长了——80 行里真正重要的可能就 15 行，其他的都是噪音。
CLAUDE.md 是加载在每个 session 开头的。越到 session 后期，上下文越满，长配置被"遗忘"的概率越高。精简到 20 行以内之后，Claude 的听话程度明显上升。
坑二：规则的措辞要具体，不能模糊。
我最早写过一条"注意代码质量"——结果就是没任何效果。
改成"每个新函数都要写 JSDoc 注释""公共接口必须使用 async/await 而非 Promise.then""超过 50 行的函数要拆分"之后，Claude 的执行力明显提高。
措辞越具体，Claude 越听话。
一个反直觉的事实
写 CLAUDE.md 最初花了我大概半小时。但算笔账：之前每次开 session 要花 3-5 分钟跟 Claude 解释基础设定。一天开 5 个 session，就是 25 分钟。一周 5 天，125 分钟。半小时的投入换来了每周两小时的节约。
而且这不是一次性的。CLAUDE.md 会随着每次纠正不断迭代，越用越准，越用越厚——不对，越用越精。精简过的 CLAUDE.md 就像一个不断优化的配置文件，每一行都有它存在的理由。
下篇聊 Plan Mode，那个改了我跟 Claude 协作的方式。
评论
发表评论