这篇讲什么
CLAUDE.md 不是给人看的 README——它是 agent 每次 session 都会加载的系统 prompt。当成系统 prompt 写，输出质量直接上一档；当成 afterthought，agent 每次都要重新发明你的约定。这篇给在真项目里跑 Claude Code、反复遇到同样摩擦的工程师看：它忽略你的 import 顺序、改你说过不许碰的文件、跑错测试命令、把本该遵循的写法重写掉。
本文涉及的工具 / 概念：
- Claude Code: Anthropic 的命令行 AI 编程 agent，能在你的终端里读、写、运行项目代码。
- CLAUDE.md: 项目根目录（或子包）的 Markdown 文件，Claude Code 自动加载为持久上下文。
- 子目录 CLAUDE.md: 子文件夹的 CLAUDE.md 会继承 / 覆盖根的；monorepo 里不同包用不同 stack 时尤其有用。
这篇适合谁看
在真项目（比脚本大）里用 Claude Code 的人。Monorepo、多语种代码库、或潜规则比 README 还多的仓库里尤其有用。
什么时候适合用
新仓库上 Claude Code 时；agent 反复犯同样错误时；带新人上手 AI 协作时——CLAUDE.md 同时也是人类的速查表。
开始前准备
- 重新读一遍现有 README。任何只面向人或带营销腔的内容不要放进 CLAUDE.md。Agent 不需要功能列表，它需要约束。
- 列三条希望 agent 做得更好的行为。这些会变成显式规则。
- 找出禁碰路径：自动生成代码、vendored 库、迁移、密钥。Agent 永远不该改这些。
- 命令（test / lint / build）选一个真相源。CLAUDE.md 里写的命令 agent 会遵守，哪怕和 package.json 里有出入。
具体步骤
- 顶部 3-5 句：这是什么项目、谁在跑、主入口。例：
Next.js 15 应用，App Router，Vercel 部署。入口：app/page.tsx。后台任务：lib/jobs/*.ts。 - 约定块：import（命名导出不要默认）、命名（kebab-case）、格式（prettier 默认加 100 字符宽）、错误处理模式。每条规则一个小例子，不要段落。
- 禁碰块：agent 不许改的路径。明确写：
不要编辑 src/generated/*、prisma/migrations/*、或任何 *.gen.ts 文件。agent 出乎意料地服。 - 质量门：lint / 类型 / 测试的精确命令。例：
Test: pnpm test --run。Lint: pnpm lint。Type: pnpm typecheck。任务完成前都跑一遍。 - 任务级提示：“被要求加路由时”那节列出要碰的 4 个文件和顺序。组件、迁移、测试也各来一段。
- 错题本：底部一小节，写过往 session 里 agent 做错的事和正确做法。每次有 drift 都补一条。
第一次实操怎么跑
- 翻一个最近 review 过的 PR，写下你给作者的 top 3 nit。
- 把每条 nit 转成 CLAUDE.md 里一句规则。
- 让 Claude Code 跑一个类似代码的小任务，确认它遵循新规则。
- 没遵循就把措辞写紧（具体例子 > 抽象原则），重跑。
完成后检查
- CLAUDE.md 是不是一两屏？再长就被忽略。砍掉历史背景和功能描述。
- 命令能原样复制粘贴吗？措辞稍变 agent 就糊涂（“跑测试” vs
pnpm test --run）。 - 每条规则都带一个小具体例子？没例子的抽象规则会退化。
- 实操里 agent 真遵守吗？没遵守就是措辞太模糊——改成显式 do/don’t。
怎么复用这套流程
- CLAUDE.md 跨项目模板化：同样的小节（说明、约定、禁碰、门、任务级、错题），具体内容定制。
- 团队共享模板——跨仓库一致的 CLAUDE.md 让新人 onboarding 和切项目更快。
- 每月把 CLAUDE.md 和上月版本 diff 一下，看自己学到了什么 agent 行为。
- Monorepo 留一份根 CLAUDE.md 写全局规则，每个包再放一份写 stack 特定规则。
建议的操作流程
写 CLAUDE.md → 跑小任务 → agent 做了你不想的，更新 CLAUDE.md → 重复。这个文件永远不算完；约第二个月规律使用后会稳定下来。
FAQ
- CLAUDE.md 多长合适？: 一到两屏。再长 agent 会略读，底部规则被忽略。
- 密钥能写 CLAUDE.md 吗？: 不能。CLAUDE.md 提交到仓库，当源码对待。引用环境变量名，不要值。
- 不同目录约定不同怎么办？: 用子目录 CLAUDE.md。Agent 合并，深层覆盖浅层。
- 和 README 有什么区别？: README 给人类 onboarding。CLAUDE.md 给当下操作的 agent。受众不同、内容不同。
- Claude Code 会严格遵守 CLAUDE.md 吗？: 带例子的显式 do/don’t 基本会；模糊规则（“写干净代码”）会被忽略。
- 个人项目需要吗？: 15 行也比没有强。没它 agent 每次重新推导约定。
容易踩的坑
- 写一次就不再更新——agent 行为在变、代码在演进，文件很快过时。
- 模糊约束如”写干净代码”，而不是”用命名导出，不要默认导出”。
- 让它涨过 3 屏——长文件被部分加载，底部规则被忽略。
- 把人类 onboarding 内容和 agent 规则混在一起——拆 README.md 和 CLAUDE.md，分开。
- 忘了列禁碰路径——你不说，agent 早晚会改自动生成代码。
- 没写精确的 test/lint/build 命令——agent 自己猜，常猜错。
相关阅读
标签: #AI 编程 #教程 #Claude Code