2026年CLAUDE.md核心指南：为何越详细AI越蠢，怎样用最少规则驯服Claude

最近 CLAUDE.md 在开发者圈子里彻底爆了。

随便翻翻公众号、知乎、B 站，全是《CLAUDE.md 最佳实践》《50 条军规》《保姆级教程》。后台也总有人问我：到底该怎么写这个文件？

但有个现象很反常——很多人的 CLAUDE.md 写成一部长篇小说，从 50 行涨到 200 行再涨到 500 行，AI 反而越来越不听话了。

我扒了 Tony Bai 的 50 条核心军规、redreamality 那篇一万字的深度文，还翻了 vercel、openai、karpathy 这些一线团队的真实仓库样本。看完我得出了一个可能得罪人的结论：

大多数人在用 2024 年的方法写 2026 年的 CLAUDE.md。

2024 年的标准答案是“尽量详细”。2026 年的标准答案是——尽量少，但尽量活。

一、写太多了 AI 反而记不住

先看一个反直观的事实。

Anthropic 官方在多次分享中提到一个基准（社区转述，非白纸黑字文档）：**前沿模型能稳定遵循的指令总量大约在 150—200 条左右。**一旦超过，遵守率会快速衰减。

这个数字我没办法百分百核实，但有另一个现象指向相同结论——HumanLayer（一家 agent 公司）的 CEO 透露，他们主仓库根目录的 CLAUDE.md 控制在 60 行以内。

来源：redreamality《一万字讲透 CLAUDE.md/AGENTS.md》中对 HumanLayer《Writing a good CLAUDE.md》的转述

知乎上有人做过一个挺严谨的实验：把 3000 字的 CLAUDE.md 逐步砍短。砍到 1000 字有改善，砍到 800 字明显变好，砍到 400 字时关键信息开始丢失，最后稳定在 800 字左右。

来源：知乎实验，经 redreamality 转述

为什么写多了反而糟糕？因为上下文窗口是稀缺资源，每一行 CLAUDE.md 都在消耗 AI 的注意力预算。你塞进去 50 条规则，相当于让一个新同事入职第一天读完一整本员工手册——他记不住，还会把不重要的条款当成重点。

社区对长度的共识大致是：普通项目根文件 ≤250 行，大型 monorepo 按子目录分片，超过 500 行必须严格分区。

二、“两次原则”：第一次出错别急着记

Anthropic 官方最佳实践里有一条最反直觉的规则，叫 Two Strikes Rule（两次原则）：

同一个错误只有在第二次发生时，才把它写进 CLAUDE.md。

来源：Anthropic 官方 Claude Code 最佳实践文档

为什么会这样？因为第一次很可能只是偶发。如果 AI 每犯一次错你就往 CLAUDE.md 加一条约束，文件很快会被一次性教训塞满——噪声压过信号。两次等于模式，一次只是噪声。

这条原则跟传统软件工程“尽早文档化、全面记录”的直觉完全相反。但它对——因为 CLAUDE.md 的本质不是日志，是规则。规则越精炼，越容易被执行。

我的实操建议：第一次出错，先在心里记一笔或者写进一个临时笔记。第二次再犯，才正式沉淀进 CLAUDE.md 的「Common Pitfalls」章节。

三、最扎心的数字：规则遵守率大约只有 70%

如果你以为把红线写进 CLAUDE.md 就万事大吉，那这个数字会让你清醒一下。

社区共识（基于 Anthropic 官方与一线团队的实测）：CLAUDE.md 中的规则，大约只有 70% 真正被遵守。

来源：redreamality 文章对社区共识的总结

翻译成人话：你写 10 条“绝对不许……”，AI 平均会无视其中 3 条。

这意味着什么？真正的红线，不能只靠 CLAUDE.md 约束。

Anthropic 给出的解法是 hooks：用 PreToolUse 钩子，在 AI 执行危险命令前直接拦截。比如“不许 push 到 main”这条红线，光写在 CLAUDE.md 里不够，得配一个 hook——检测到 git push origin main 直接返回非零退出码，把请求掐死。

来源：Anthropic 官方最佳实践、Tony Bai 50 条军规第 36 条（Hooks）

CLAUDE.md 管 70% 的常规约束，hooks 兜底剩下 30% 的硬红线。这是正确的分工。只写 CLAUDE.md 不配 hooks，等于给金库装了密码锁但没插电源。

四、Karpathy 的范式：写成功判据，别写步骤

Andrej Karpathy（特斯拉前 AI 总监、OpenAI 创始成员）提过一个观点，后来被一份周下载量 4.3 万次的 skill 集合总结成一句话：

“LLMs are extremely good at looping until they hit a specific goal. Don’t tell them how to do it. Give them success criteria and let them run.”

来源：forrestchang/andrej-karpathy-skills

落到 CLAUDE.md 上就是：写声明式，不写命令式。

  • • ❌ 命令式（写步骤）：“先读 A 文件，再修改 B，然后跑 C 测试”
  • • ✅ 声明式（写判据）：“改完之后 pnpm test 必须全绿，且 git diff 里不许出现 console.log”

前者会把 AI 逼进死胡同——一旦某一步卡住，它就整个流程崩溃。后者只给目标，让 AI 自己组织路径，反而能找到更优解。

这个思路跟传统“先画流程图再写代码”完全相反。但 agent 时代的好规格说明，就是声明式的。

Karpathy 走得更远——他自己的 autoresearch 项目里，指令文件干脆不叫 CLAUDE.md，叫 program.md，范式是 “人类迭代 program.md，agent 迭代 .py”。Markdown 成了源代码，agent 是编译器。

来源：karpathy/autoresearch 仓库

五、最关键认知：把它当成代码，而不是文档

Anthropic 官方最佳实践里有一句原话，我觉得是所有 CLAUDE.md 教程里最重要的一句：

“Treat CLAUDE.md like code: review it when things go wrong, prune it regularly.”
（把它当代码对待：出问题时要审查它，要定期修剪它。）

来源：Anthropic 官方 Claude Code 最佳实践

这一句话否定了两种最常见的错误用法：

**错误一：写成 README。**很多人把 CLAUDE.md 当成项目简介的副本——贴一段介绍、贴一张架构图、贴一段 Getting Started。这些对 AI 几乎没用。AI 不关心你的项目卖点，它只关心：跑测试是 pnpm test 还是 npm run test:unit？哪些目录禁止改动？改完怎么验证？

**错误二：写一次就不再管了。**CLAUDE.md 是活文档。项目在演进，规则也要跟着增减。官方的建议是定期 review，淘汰过时部分。

所以正确姿势是：像 review 代码一样 review CLAUDE.md，像重构代码一样重构它，像清理死代码一样淘汰过时规则。

六、避坑清单：这些写法正在拖垮你的 CLAUDE.md

综合 vercel、openai、karpathy 的真实仓库样本，以及 AgentShield 这类反模式扫描工具的发现，最该避开的五个坑：

❌ 错误写法✅ 正确写法原因
“请写出优雅的代码”“单文件不超过 500 行，超过 800 行必须拆分”模糊词无法执行，AI 会直接忽略
硬编码 API Key用环境变量 + .gitignore扫描工具能直接扫出，安全隐患
使用过期模型 ID（claude-3-opus）使用当前别名（claude-sonnet-4-6）日期版本会失效，产生技术债
跟 README 重复项目介绍只写 AI 需要的运行手册重复内容浪费上下文预算
场景化指令（“如何设计订单 schema”）写成通用规则 + 放进 skills只在你做订单时有用，其余时间是噪声

来源：openai/codex 的 AGENTS.md（单文件 500 LoC 目标）、anthropics/anthropic-cookbook（强制 uv + 当前模型别名）、affaan-m/everything-claude 的反模式扫描

openai/codex 那份 800 行的 AGENTS.md 里有一句特别值得学习——“Resist adding code to codex-core”（抵制往核心包塞东西）。这种带有“反向意图”的规则，比“保持代码简洁”这类正向空话有效得多。

七、后端工程师的实战建议

作为写 Java/Spring Boot 的后端，我给出几条针对这个场景的实用建议：

**1. 多层 CLAUDE.md 各司其职。**Claude Code 支持层级继承——全局 ~/.claude/CLAUDE.md 写跨项目偏好（用中文、Maven 命令规范、表命名规范），项目根写构建测试命令，子模块目录写局部约束。别把所有东西堆在一个文件里。

**2. 把“两次原则”用起来。**后端最容易重复犯的错——比如 MyBatis 的 XML 命名空间写错、JPA 的懒加载序列化问题。第一次踩坑先记临时笔记，第二次再写进 CLAUDE.md。

3. 红线靠 hooks，别靠自觉。“不许直接操作生产库”、“不许提交带密码的配置”——这种事写进 CLAUDE.md 只是建议，配上 PreToolUse hook 才是强制。

**4. 数据库表命名规范写进去。**参考《阿里巴巴 Java 开发手册》——表名小写、下划线分隔、语义后缀（配置表 xxx_config、信息表 xxx_info、日志记录 xxx_log），再加上通用字段。这种固定规范写进 CLAUDE.md 一次，以后生成建表语句就自动对齐，省心。

**5. CLAUDE.local.md 已经废弃了。**如果你还在用旧版的本地覆盖文件，换成 @~/.claude/personal-overrides.md + .gitignore，或者使用 @path 导入语法（最多 5 跳递归）。这是 Anthropic 官方 issue #2950 确认的。

来源：anthropics/claude-code issue #2950

八、一份可以直接套用的骨架

下面是我自己在用的、控制在 200 行以内的骨架，照着填就行：

# 项目名  
  
## CRITICAL RULES（红线，绝对禁止）  
- 永远不要直接操作生产数据库  
- 不要提交带密钥的配置文件  
  
## BUILD & TEST COMMANDS（精确到命令）  
- 构建：mvn clean compile  
- 打包：mvn clean package -DskipTests=true  
- 单测：mvn test  
  
## CODE STYLE（带示例，不写废话）  
- 使用 Lombok 简化 POJO  
- 优先用基础类型 int 而非 Integer  
- 方法名驼峰，类名 Pascal  
  
## DATABASE CONVENTIONS（参考阿里 Java 手册）  
- 表名小写、下划线分隔，语义后缀：配置 xxx_config、信息 xxx_info、日志记录 xxx_log  
- 通用字段：id / created_at / updated_at  
  
## COMMON PITFALLS（踩坑清单，按两次原则积累）  
- MyBatis XML 命名空间必须与 Mapper 接口全限定名一致  
- [踩到第二次时再往这里加]  
  
## VERIFICATION（声明式判据，不是步骤）  
- 改完任何代码，mvn compile 必须通过  
- 提交前 git diff 不许出现 TODO 或测试密码

注意几点：每个章节都用指令式强约束词（ALWAYS / NEVER / MUST），命令精确到命令行，避坑按“两次原则”慢慢积累。这份骨架初始可能只有 80 行，随着项目演进长到 150-200 行就该 review 了，超过 250 行就该分片。

你可能还想问

Q：CLAUDE.md 和 AGENTS.md 是什么关系？用哪个？

AGENTS.md 是 2025 年 8 月 OpenAI、Google、Cursor 等联合推出的跨工具开放标准，一份文件可同时被 Codex、Cursor、Claude Code 等读取。如果你多个 AI 工具混用，建议主文件写 AGENTS.md，CLAUDE.md 只写一行 See @AGENTS.md。只用 Claude Code 的话，CLAUDE.md 就够了。

Q：怎么让 AI 自动帮我维护 CLAUDE.md？

运行 /init 命令，Claude 会自动分析项目生成初始版本。之后可以用 @.claude 在 PR review 时标记要更新的规则。但切记“两次原则”——别让它每错一次就加一条，否则文件会膨胀。

Q：CLAUDE.md 写多长最合适？

普通项目 150-250 行，控制在 800 字以内。Monorepo 按子目录分片。判断标准不是行数，而是“能不能一眼看出重点”——如果你自己都得找半天某条规则，AI 也一样找不到。

Q：规则写进去 AI 不遵守怎么办？

先确认是不是写得太模糊（“保持代码整洁”这种就是废规则）。如果规则明确还不遵守，那就是那 30% 的不可控区间，用 hooks 强制兜底。别指望 CLAUDE.md 是 100% 保险。

结尾

回到开头那个问题：为什么 CLAUDE.md 越写越长，AI 却越来越蠢？

因为很多人把 CLAUDE.md 当成“我说的越多 AI 越懂”的提示词，而它本质上是一份需要克制、需要演化、需要与 hooks 配合的运行手册。

2026 年写 CLAUDE.md 的核心就八个字：尽量少，但尽量活。

  • • 少——因为每一行都在消耗 AI 的注意力预算
  • • 活——因为规则不是静态合同，而是持续演化的团队记忆

记住 Anthropic 那句原话：把它当代码对待。像 review 代码一样 review 它，像重构代码一样重构它，像清理死代码一样淘汰过时规则。

能做到这一点，你的 AI 才会从一个健忘、恭维、动不动自作主张的实习生，变成一个靠谱的专业新同事。

至于那些把 CLAUDE.md 写成 500 行项目百科的教程——看看就好。真正好用的 CLAUDE.md，从来不是最长的，而是最精炼的。

参考来源：

  • Anthropic 官方：Claude Code Best Practices
  • redreamality：一万字讲透 CLAUDE.md/AGENTS.md
  • Tony Bai：Claude Code 官方最佳实践 50 条核心军规
  • HumanLayer：Writing a good CLAUDE.md
  • karpathy/autoresearch：program.md 范式
  • openai/codex：800 行 AGENTS.md 样本
  • vercel/vercel：247 行 monorepo 模板
  • InfoQ：Claude Code 官方内部团队最佳实践
  • 博客园 knqiufan：Claude Code 完全指南