夜雨聆风
很多人第一次用 Claude Code 改项目，都会遇到同一个问题：它不是不会写代码，而是不知道这个项目的默认规则。
怎么启动？
怎么跑测试？
哪些目录不能动？
改完怎么算真的完成？
失败了能不能跳过检查？
这些问题，如果你每次都靠聊天回答，就等于每次都在重新培训 Claude Code。
我的做法很简单：
把这些固定答案写进项目根目录的 CLAUDE.md。
很多人以为 Claude Code 不够懂项目，其实是项目没有给它一份“默认上下文”。
这篇给你两份可以直接复制的模板：
• 一份 20 行最小版，今天就能放进项目 • 一份 60 行完整版，适合长期维护
先用起来，再把 Claude Code 反复问你的问题补进去。
先说结论：CLAUDE.md 只回答一种问题
只回答一个问题：
Claude Code 每次进这个项目，都必须提前知道什么？
注意这里的关键词：每次。
如果某个信息只对今天这个任务有用，不要写进 CLAUDE.md，直接写在 prompt 里。
如果某个流程偶尔才用一次，比如写公众号、做 code review、查日志、生成发布说明，不要全塞进 CLAUDE.md，更适合做成 Skill 或 slash command。
如果某个规则只属于你自己，不属于团队，比如“我喜欢先让 AI 给我三个方案”，放到 ~/.claude/CLAUDE.md 或 CLAUDE.local.md。
项目根目录的 CLAUDE.md，只放这类东西：
• 这个项目怎么跑 • 怎么验证改动 • 哪些目录负责什么 • 哪些规则不能违反 • 哪些坑新同学一定会踩 • Claude Code 做完以后要交付什么证据
价值标准只有一个：下次不用再解释。
先给 20 行最小版
如果你只想今天就用，先复制这 20 行。
# CLAUDE.md## Project这个项目是：<一句话说明项目用途>。做改动时优先保持现有架构和代码风格，不做无关重构。## Commands- 安装：`<command>`- 开发：`<command>`- 测试：`<command>`- 只跑单测：`<command>`- 类型检查：`<command>`- 构建：`<command>`## Structure- `<path>`：<核心入口>- `<path>`：<业务逻辑>- `<path>`：<测试>- `<path>`：<生成文件/不要手改>## Rules- 改动超过 3 个文件，先给计划- 优先复用现有模式，不要新增不必要依赖- 不要修改生成文件、密钥、真实用户数据- 不要为了通过检查而删除测试或降低断言## Done完成时说明：- 改了哪些文件- 跑了哪些命令- 结果是什么- 哪些没验证到## Gotchas- `<gotcha>`- `<gotcha>`就这几段，已经能解决很多问题。
Claude Code 最常问你的，通常就是：
“怎么跑？”
“哪里改？”
“什么不能动？”
“改完怎么证明？”
这些问题有固定答案，就不要每次用聊天来回答。
如果你想让 Claude Code 在项目里更稳定，再看下面的 60 行完整版。
60 行完整版 CLAUDE.md 模板
下面这份可以直接复制。
先别追求完美。填 60 行以内，跑几次 Claude Code，再把它反复问的问题补进去。
# CLAUDE.md## 0. 项目一句话这个项目是：<用一句话说明产品/系统/仓库的真实用途>。Claude Code 在这个项目里的目标是：- 优先完成可验证的小步改动- 保持现有架构和风格一致- 不引入不必要的新依赖## 1. 常用命令依赖安装：- `<command>`本地开发：- `<command>`类型检查：- `<command>`格式化 / lint：- `<command>`单元测试：- `<command>`只跑某个测试：- `<command>`构建：- `<command>`如果命令失败，先阅读报错并定位根因，不要通过跳过检查、删除测试、放宽类型来“修复”。## 2. 项目结构- `<path>`：<这个目录负责什么>- `<path>`：<这个目录负责什么>- `<path>`：<这个目录负责什么>重要入口：- `<path>`：<应用入口 / 服务入口 / 路由入口>- `<path>`：<核心业务逻辑入口>- `<path>`：<测试或验证入口>不要在这里写每个文件的解释。Claude 可以自己读代码。这里只写“应该先去哪儿看”。## 3. 改代码前先做在修改文件前，Claude Code 应该：1. 先搜索现有实现，复用项目已有模式2. 如果改动超过 3 个文件，先给出简短计划3. 如果涉及接口、数据库、权限、支付、登录、发布流程，必须先说明风险4. 不确定时先提问，不要靠猜测补全关键业务规则## 4. 代码约定这个项目的特殊约定：- `<rule>`：例如“API 错误统一用 AppError，不直接 throw 普通 Error”- `<rule>`：例如“前端请求必须走 src/lib/api，不在组件里直接 fetch”- `<rule>`：例如“状态管理优先用现有 store，不新增全局状态库”只写本项目特有的约定。不要写“代码要清晰”“注意性能”这种 Claude 本来就知道、也无法执行的空话。## 5. 验证标准Claude Code 完成任务前，必须说明：- 实际改了哪些文件- 运行了哪些验证命令- 每个命令的结果是什么- 哪些部分没有验证到，以及原因默认完成标准：1. 相关测试通过2. 类型检查通过3. lint / format 没有新增问题4. 用户可见改动需要说明如何人工检查如果无法运行验证命令，必须明确原因，不能只说“应该可以”。## 6. 禁止事项Claude Code 不要做这些事：- 不要修改 `<generated path>` 下的生成文件，除非任务明确要求- 不要提交密钥、token、cookie、真实用户数据- 不要为了让测试通过而删除测试或降低断言- 不要在没有说明原因的情况下新增依赖- 不要大范围重构与当前任务无关的代码- 不要用临时 mock 掩盖真实集成问题## 7. 已知坑这个项目里容易踩的坑：- `<gotcha>`：<为什么容易错，正确做法是什么>- `<gotcha>`：<为什么容易错，正确做法是什么>- `<gotcha>`：<为什么容易错，正确做法是什么>如果 Claude Code 在同一个问题上错了两次，把新规则补到这里。## 8. 更新这份文件的规则当出现下面情况时，更新 `CLAUDE.md`：- Claude Code 反复问同一个项目问题- Claude Code 反复违反同一条项目约定- 项目的启动、测试、构建命令发生变化- 新增了重要目录、服务或边界更新原则：- 新增规则要短，最好一行说清- 删除过期规则- 不把一次性任务背景写进来- 文件过长时，优先删除 Claude 可以从代码中自己推断的信息主模板到这里。
不要把 CLAUDE.md 写成百科全书，要写成默认决策表。
下面只拆两件事：每段该填什么，以及什么不该填。
你知道吗Anthropic 文档里明确建议先用
/init生成 starterCLAUDE.md，再人工删改。项目根目录的CLAUDE.md适合提交到 git；个人偏好更适合放在CLAUDE.local.md或~/.claude/CLAUDE.md。
0. “项目一句话”不是介绍项目，是校准目标
很多人的 CLAUDE.md 第一段会这样写：
这是一个基于 Next.js 和 PostgreSQL 的全栈项目。这句话没错，但信息密度低。
Claude Code 看 package.json 和目录结构，大概率也能猜出来。
更有用的是这种：
这是一个给内容创作者使用的公众号选题和发布工作流项目。核心目标不是“功能多”，而是让选题、写作、审稿、发布形成可复用流程。第一种告诉它技术栈。
第二种告诉它取舍。
当 Claude Code 要不要新增一个复杂抽象、要不要引入新依赖、要不要把功能做得很通用时，第二种信息会影响它的判断。
CLAUDE.md 里最值钱的部分，通常不是“用了什么”，而是“在乎什么”。
1. 常用命令：给 Claude 一个可执行的验收按钮
Claude Code 的优势在于：写完代码后，它能自己跑命令，看结果，再修。
但前提是：它知道该跑什么。
如果你每次都要补一句：
“我们这里不是 npm，是 pnpm。”
“测试不要全跑，跑这个 package 就行。”
“构建命令不是 build，是 check。”
那这些就应该写进 CLAUDE.md。
命令区要尽量具体。
不要写：
运行测试。要写：
单元测试：- `pnpm test -- --runInBand`只跑某个测试：- `pnpm test path/to/file.test.ts`这里的深层逻辑是：你在给 Claude 一个可以闭环的按钮。
没有验证按钮，Claude Code 做完只能说“我改好了”。
有验证按钮，它才能说：
“我改了这 3 个文件，运行了类型检查和相关测试，结果都通过；E2E 没跑，因为本地缺少浏览器环境。”
前一种要你兜底，后一种能交给证据。
这一句可以直接写进去：
如果命令失败，先定位根因，不要通过跳过检查、删除测试、放宽类型来修复。2. 项目结构：不要画地图，要标入口
CLAUDE.md 最容易写废的地方，就是项目结构。
很多人会把目录树贴进去：
src/ components/ pages/ utils/ hooks/ services/这对 Claude Code 帮助不大。
它自己 ls 一下就能看到。
你应该告诉它：
• 业务入口在哪里 • 旧代码和新代码的边界在哪里 • 哪些目录是生成物 • 哪些目录看起来能改，但其实不能乱动 • 做某类任务应该先看哪里
比如：
- `apps/web/src/app`：Next.js App Router 页面入口- `packages/domain`：核心业务规则，前端不要绕过这里直接拼逻辑- `packages/generated`：接口生成代码，不要手改- `scripts/publish-wechat.ts`：公众号发布入口，改发布逻辑先看这里这不是目录介绍。
这是项目导航。
你要把 Claude Code 当成一个刚入职、但搜索能力极强的新同事。
不用把每条路都讲一遍，告诉它应该从哪个门进去。
这一句可以直接写进去：
不要在这里解释每个文件，只写做某类任务应该先看哪个入口。3. 代码约定：只写 Claude 猜不到的东西
我不建议在 CLAUDE.md 里写一堆通用好习惯。
比如：
- 写干净代码- 注意性能- 保持可维护性- 遵循最佳实践这些话没错，但没有执行力。
Claude Code 不会因为你写了“注意性能”，就知道这个项目里缓存应该放 Redis 还是内存。
更好的写法是：
- API 错误统一返回 `Result<T, AppError>`，不要在 handler 里直接 throw 普通 Error- 前端组件不要直接请求后端，统一走 `src/lib/api-client`- 新增数据库字段必须同时更新 migration、schema 类型和 seed 数据- 文案生成逻辑不要写死在页面里，放到 `modules/content-rules`这类规则有三个特征：
第一，它是本项目特有的。
第二，它能指导具体修改。
第三，如果不写，Claude Code 真的可能做错。
CLAUDE.md 的每一行都应该经得起这个问题：
删掉这一行，Claude 会不会更容易犯错？
如果不会，就删。
这一句可以直接写进去：
只写本项目特有约定，不写“代码要清晰”“注意性能”这类空话。4. 改代码前先做：把“别乱来”变成流程
Claude Code 的风险常常来自速度。
你刚说完“帮我优化一下”，它可能已经开始改 8 个文件。
这时候你再说“等等，不是这个方向”，已经晚了。
所以我会在 CLAUDE.md 里写一段“改代码前先做”。
这段不是限制它，而是给它触发条件：
• 小改动，可以直接做 • 超过 3 个文件，先计划 • 涉及数据库/权限/支付/发布，先讲风险 • 不确定业务规则，先问
这比你每次临时提醒有效。
因为 Claude Code 每次开新会话都会读到。
我特别建议写这一句：
如果改动超过 3 个文件，先给出简短计划，不要直接修改。这条规则能挡住很多“AI 写太快导致返工”的情况。
小任务直接做。牵涉面变大，先让它停一下。
5. 验证标准：让“完成”变成证据，而不是语气
Claude Code 最容易出现的一种回答是：
“现在应该可以了。”
我最不喜欢这个“应该”。
问题不在语气，在于没有证据。
所以我会把完成标准写进 CLAUDE.md：
完成任务前必须说明：- 实际改了哪些文件- 运行了哪些验证命令- 每个命令的结果是什么- 哪些部分没有验证到，以及原因这段会把 Claude Code 的交付，从“给你一个结论”变成“给你一组证据”。
你看它的最终回复时，不需要重新猜：
• 它到底有没有跑测试 • 它是不是只改了代码没验证 • 它有没有因为环境问题跳过某个检查 • 它有没有动到不该动的文件
我判断一个 agent 工作流是否成熟，主要看它能不能把验证过程交代清楚。
这一句可以直接写进去：
完成前必须说明：改了哪些文件、跑了哪些命令、结果是什么、哪些没验证到。6. 禁止事项：不要写道德口号，要写事故清单
“不要乱改代码”没用。
什么叫乱改？
Claude 不知道。
禁止事项要写成事故清单：
- 不要修改 `generated/` 下的生成文件- 不要为了测试通过删除测试- 不要把真实 token 写进示例配置- 不要在没有说明原因的情况下新增依赖- 不要改与当前任务无关的大段代码这类规则越具体越好，最好来自真实事故。
比如你发现 Claude Code 曾经为了让 TypeScript 过，直接把类型改成 any。
那就补一条：
- 不要用 `any` 绕过类型错误；如果必须使用，说明原因和边界。你发现它喜欢在前端组件里直接 fetch。
那就补一条：
- 不要在 React 组件里直接请求后端，统一走 `src/lib/api-client`。CLAUDE.md 不是一次写完的。
它应该像防错清单一样，从你真实踩过的坑里长出来。
这一句可以直接写进去：
不要为了让检查通过而删除测试、降低断言、改成 any，除非明确说明原因和边界。7. 已知坑：这是最值得写的部分
如果只能保留 CLAUDE.md 的一个区块，我可能会保留“已知坑”。
因为这是 Claude Code 最难从代码里推断出来的东西。
代码能告诉它“现在是什么”。
但不一定告诉它“为什么不能那样改”。
比如：
- 登录态同时存在 cookie 和 localStorage，是历史迁移遗留。不要只改其中一个，否则老用户会掉登录。- `legacyPayment` 看起来没人用，但企业客户还在走这个入口。删除前必须确认迁移状态。- 测试里不能连真实数据库，必须用 `TEST_DATABASE_URL`。这类信息非常值钱。
它来自团队经验，也是新人最容易问老同事的问题。
你把它写进 CLAUDE.md，Claude Code 就不会每次都像第一天入职。
8. 更新规则：让它越用越准，而不是越写越肿
CLAUDE.md 最大的风险之一，是越写越长。
一开始你写 50 行，很清楚。
过一个月，变成 300 行。
里面混着旧命令、废弃目录、一次性任务背景、个人偏好、已经不存在的架构。
这时候 Claude Code 更容易忽略关键规则。
所以我建议给 CLAUDE.md 自己也写维护规则：
当 Claude 反复问同一个问题时，补一行。当 Claude 反复犯同一个错时，补一行。当某条规则过期时，删掉。不要把一次性任务背景写进来。我自己的判断标准是：
每次只补一条能减少下次沟通成本的规则。
不要整理今天的聊天记录。不要塞进所有知识。只沉淀会重复发生的东西。
一个坏 CLAUDE.md 长什么样
坏的 CLAUDE.md 通常有四种。
第一种，百科全书型。
把 README、接口文档、目录树、历史背景、开发计划全塞进去。
看起来很完整，实际信号很低。
第二种，口号型。
全是“写高质量代码”“遵循最佳实践”“考虑边界情况”。
这些话没有错，但不够具体，Claude Code 很难执行。
第三种，过期型。
命令已经变了，目录已经迁了，但文件还没更新。
这种最危险。
过期规则比没有规则更糟，因为它会让 Claude Code 坚定地走错路。
第四种，混杂型。
团队规则、个人偏好、一次性任务、临时想法全放在一个文件。
结果每次会话都背着一大包不相关上下文。
我会这样分：
• 项目长期规则：放 ./CLAUDE.md• 个人偏好：放 ~/.claude/CLAUDE.md或CLAUDE.local.md• 一次性任务背景：放当前 prompt • 偶尔使用的复杂流程：做成 Skill • 大段参考资料：用 @file引用，不要整段复制
别让 CLAUDE.md 承担所有事情。
它只负责项目默认记忆。
我现在的使用流程
我一般这样做：
第一步，在项目根目录跑：
/init让 Claude Code 先生成一版。
第二步，不直接相信它生成的内容。
我会删掉三类东西：
• 它从文件树里显而易见能看出来的 • 太泛的好习惯 • 不确定、可能过期、像猜出来的描述
第三步，补上它猜不到的东西：
• 测试命令 • 生成文件边界 • 不能碰的目录 • 项目特殊约定 • 常见坑
第四步，正常使用 Claude Code。
只要它重复问我一个问题，我就想：
这是不是应该写进 CLAUDE.md？
只要它重复犯一个错误，我就想：
这是不是应该变成一条明确规则？
第五步，定期删。
我不追求 CLAUDE.md 越来越长。
我追求它越来越像一份高密度的项目操作手册。
真正的作用：把你的判断前置
Claude Code 的效率不只来自模型能力。
项目环境会直接决定它的表现。
同一个 Claude Code：
在一个没有规则、没有测试命令、没有目录说明的项目里，它会一直问、一直猜、一直等你兜底。
在一个写好 CLAUDE.md、有清晰验证命令、有明确边界的项目里，它会更像一个已经熟悉团队习惯的同事。
没写之前，你在回答 6 个低级问题。
写完之后，它至少能先读入口、跑检查、带着验证结果回来。
你只是把重复沟通提前写下来了。
所以我不太建议一上来就追各种“Claude Code 神级技巧”。
先做一件很朴素的事：
把你已经回答过两次的问题，写进 CLAUDE.md。
它不会让 Claude Code 突然变成架构大师。
但它会让 Claude Code 少问很多低级问题。
也会让你少做很多无意义的复述。
CLAUDE.md 的价值很朴素：
让 AI 更懂你这个项目。
