喵斯基部落 
Claude Code 的 CLAUDE.md 怎么写？这 12 条规则，管住 AI Agent 的静默失败
你是否踩过这些坑？
用 Claude Code 写过项目的人，大概率踩过这些坑：
- 迭代了三轮，第四轮 Claude 把第二轮修好的 bug 又写回来了——它忘了自己做过什么
- 让它加个新功能，它一口气重构了旁边三个文件：“顺手优化了一下”
- 六步任务跑到第五步崩了，但它的回复是”完成”——前面第三步就错了，你没注意到
- 12 个测试全绿上线挂掉，回头发现测试只验证”函数返回了值”，没验证”返回了正确的值”
但最折磨人的不是 bug 本身——是盯着 Claude 的 “Done ✓“，盯 diff 盯了三遍，不知道漏了什么。比报错更无力的，是这种”它说做完了，但我不确定”的焦虑。
这不是 prompt 的问题。Agent 模式下，Claude 替你做的隐性决策远比你想的要多——它做对了不会说，做错了更不会说。
下面的这些规则就是为了堵住这些口子。前 4 条管住最基础的代码生成，后 8 条管住 Agent 模式特有的自主行为——从决策边界到验证质量，每一条都附带它防止的真实翻车场景。
12 条 CLAUDE.md 规则
Rule 1 — Think Before Coding
State assumptions, ask if unsure, don’t guess. Point out simpler alternatives. Stop if stuck—say what’s unclear.
不确定就问，别猜。有更简单的方案就直接指出来。卡住了就说哪里不清楚——别硬往下编。
Rule 2 — Simplicity First
Least code to solve the problem. No speculative code, no features beyond the requirement, no abstraction for single use. Self-test: would a senior engineer call this over-engineered? If yes, simplify.
最少代码解决问题。不写投机功能，不为单次使用做抽象。写完问自己一句：高级工程师会说这是过度设计吗？是就简化。
Rule 3 — Surgical Changes
Touch only what must change. No drive-by “optimizations” of adjacent code, comments, or formatting. No refactoring things that aren’t broken. Match existing style.
只碰必须改的。别顺手”优化”旁边的代码、注释、格式。别重构没坏的东西。别在别人的代码里夹带你的风格偏好。
Rule 4 — Goal-Driven Execution
Define success criteria, loop until verified. Don’t follow steps—define success and iterate.
定义什么叫”做完”，循环到真的做完为止。别告诉它步骤，告诉它成功长什么样——它自己找路。
Rule 5 — Model for Judgment Only
Use the model for classification, drafting, summarization, extraction. Don’t use it for routing, retries, deterministic transforms. If code can answer it, let code answer it.
模型做分类、草拟、总结、提取。路由、重试、确定性转换不要交给模型——状态码能判断的事，让代码判断。一段 503 重试逻辑让 Claude 写 if-else，别让 Claude 替你决策要不要重试。
Rule 6 — Token Awareness
Be aware of token budget. Summarize and restart when approaching limits (4k per task, 30k per session). If you exceed limits, report it—don’t silently exceed.
注意 token 消耗。单任务 4000 token、单 session 3 万是硬上限——快到了就总结重开，别让它在一个越来越长的上下文里兜圈子。长 session 里 Claude 会慢慢忘掉自己试过什么，然后推荐第三轮已经被否决的方案。
Rule 7 — Surface Conflicts
When two patterns conflict, pick one (newer / more validated), explain why, flag the other for cleanup. Don’t blend contradictory approaches.
一个项目里同时存在两种错误处理方式，Claude 的新代码两套都调了——错误被吞两次。两种模式冲突，选一边（更新的 / 更验证过的），说清楚为什么，标记另一边等清理。别折中，折中是最差的方案。
Rule 8 — Read Before Write
Before adding code, read exports, callers, shared utilities. “Seems orthogonal” is dangerous. If you don’t know why something is organized this way, ask.
加代码之前，先读 exports、调用方、共享工具。Claude 会在已有函数旁边加一个功能完全相同的——因为它没读那个文件。“看起来正交”是最危险的错觉。不知道为什么要这样组织，就问。
Rule 9 — Tests Verify Intent
Tests encode WHY this behavior matters, not just WHAT it does. If business logic changes but tests don’t fail, the tests are wrong.
测试要验证的是”为什么这个行为重要”，而不是”代码做了什么”。auth 函数写了 12 个测试全绿，生产挂了——因为测的是返回值有没有，不是返回值对不对。业务逻辑变了但旧测试不报错，等于没有测试。
Rule 10 — Checkpoint Every Step
Summarize what was done, what was verified, what remains. Don’t continue from a state you can’t describe. If you lose track, stop.
每步做完总结三件事：做了什么、验证了什么、还剩什么。别从描述不出来的状态继续——六步重构到第四步错了，如果没 checkpoint，第五、六步跑完你才发现，解开比重做还费劲。
Rule 11 — Match Conventions
Intra-codebase consistency > personal taste. If you genuinely think a convention is harmful, raise it—don’t silently fork.
代码库内的一致性大于你的个人偏好。Claude 在 class-component 项目里引入 React hooks——hooks 没毛病，但炸了依赖 componentDidMount 的测试体系。真想改约定，提出来，别默默分叉。
Rule 12 — Fail Loud
If something was skipped, “done” is wrong. If tests were skipped, “passing” is wrong. Default to exposing uncertainty, not hiding it.
有东西被跳过，“完成”就是错的。有测试被跳过，“通过”就是错的。默认暴露不确定性，别藏。数据库迁移到一半遇到约束冲突，14% 记录被默默丢掉，日志写了但你不知道——因为 Claude 只汇报”迁移完成”。
完整规则（直接复制进 CLAUDE.md）
## Coding Rules (12 Rules)
1. **Think Before Coding.** State assumptions, ask if unsure, don't guess. Point out simpler alternatives. Stop if stuck—say what's unclear.
2. **Simplicity First.** Least code to solve the problem. No speculative code, no features beyond the requirement, no abstraction for single use. Self-test: would a senior engineer call this over-engineered? If yes, simplify.
3. **Surgical Changes.** Touch only what must change. No drive-by "optimizations" of adjacent code, comments, or formatting. No refactoring things that aren't broken. Match existing style.
4. **Goal-Driven Execution.** Define success criteria, loop until verified. Don't follow steps—define success and iterate.
5. **Model for Judgment Only.** Use the model for classification, drafting, summarization, extraction.Don't use it for routing, retries, deterministic transforms. If code can answer it, let code answer it.
6. **Token Awareness.** Be aware of token budget. Summarize and restart when approaching limits (4k per task, 30k per session). If you exceed limits, report it—don't silently exceed.
7. **Surface Conflicts.** When two patterns conflict, pick one (newer / more validated), explain why,flag the other for cleanup. Don't blend contradictory approaches.
8. **Read Before Write.** Before adding code, read exports, callers, shared utilities. "Seems orthogonal" is dangerous. If you don't know why something is organized this way, ask.
9. **Tests Verify Intent.** Tests encode WHY this behavior matters, not just WHAT it does. If business logic changes but tests don't fail, the tests are wrong.
10. **Checkpoint Every Step.** Summarize what was done, what was verified, what remains. Don't continue from a state you can't describe. If you lose track, stop.
11. **Match Conventions.** Intra-codebase consistency > personal taste. If you genuinely think a convention is harmful, raise it—don't silently fork.
12. **Fail Loud.** If something was skipped, "done" is wrong. If tests were skipped, "passing" is wrong. Default to exposing uncertainty, not hiding it.CLAUDE.md 怎么用？
放仓库根目录，命名为 CLAUDE.md（不是 .claude.md，不是 CLAUDE.txt）。先复制 12 条规则进去，末尾追加项目特定配置——技术栈、测试命令、已知的坑。总共别超过 200 行。
不用全抄。项目不跑多步 pipeline，规则 10 可以砍。lint 已经管住代码风格，规则 11 可以砍。留你真正踩过坑的那几条，比抄 12 条用不着的强。
每一行规则都应该能回答一个问题： 它防止的是什么错误？ 答不上来，删掉。
好的 CLAUDE.md 不是给 Claude 的说明书，是给你自己的后悔药清单。
支持与分享
如果这篇文章对你有帮助，欢迎分享给更多人或赞助支持！