大家好，我是程序员鱼皮。
最近我发现一个现象，很多同学开始用 Claude Code、Cursor 这些 AI 编程工具了，但用了一阵子之后就开始抱怨：AI 怎么总是不听话？让它改个 Bug 反而引入三个新 Bug，让它加个功能结果技术栈都给换了。
这些问题的根源，往往不是 AI 笨，而是你没有给它足够的上下文。
AI 每次开始新会话，都是一张白纸。它不知道你的项目用的是什么技术栈，不知道你们团队的代码规范，不知道你之前做了什么决策。
你不说，它就猜。猜对了算你运气好，猜错了你就得返工，把你的 tokens 全拿走，把回忆化成空~
那有没有一种方法，让 AI 每次开始工作前就自动了解你的项目？
必须有啊！就是今天要聊的 CLAUDE.md。
一、CLAUDE.md 是什么？
CLAUDE.md 是 Claude Code 里的一个 Markdown 文件，放在项目根目录下。
Claude Code 每次启动会话时，都会自动读取这个文件，把里面的内容当作项目的背景知识。
你可以把它理解为 给 AI 写的「入职手册」。就像新员工入职第一天，你会给他一份文档，介绍公司用什么技术、代码怎么写、测试怎么跑、有什么坑要注意。CLAUDE.md 干的就是这个事。
比如一个最简单的 CLAUDE.md 长这样：
# 我的博客系统
Next.js 16 + TypeScript + Tailwind CSS + Supabase
## 常用命令
- npm run dev # 启动开发服务器
- npm run test # 跑测试
- npm run build # 生产构建
## 代码规范
- 使用函数式组件，不用 class 组件
- 样式只用 Tailwind CSS，不写自定义 CSS
- 所有组件必须有 TypeScript 类型定义
AI 每次开始工作前都会先读一遍，然后所有生成的代码都会自动遵循这些规范，不用你每次都重复交代。
不过有一点需要注意，CLAUDE.md 对 AI 来说 是建议 而 不是强制执行 的配置。它的效果取决于你写得有多具体、多简洁。越精确的指令 AI 遵循得越好，写了一大堆模糊的要求反而可能被选择性忽略。
二、更通用的 AGENTS.md
你可能会想，这是 Claude Code 的专属功能吗？我用 Cursor 怎么办？
其实几乎所有主流 AI 编程工具都有类似的机制。比如 Cursor 也支持 .cursor/rules/ 和 AGENTS.md 来做同样的事。
必须要知道的是 AGENTS.md，它是一个跨工具的开放标准，由 OpenAI、Google、Cursor 等多家公司联合推出，目前已经有好万个开源项目在用，支持 30 多种 AI 编程工具。
Claude Code 虽然默认只读 CLAUDE.md，但你可以在 CLAUDE.md 里用一行 @AGENTS.md 把它导入进来，两边就打通了。
这些 Markdown 文件本质上都是一回事，就是 给 AI 写一份项目说明书。你学会写好这份说明书，换任何 AI 编程工具都能用。
而且 AGENTS.md 的用途不只是项目开发指导，它同样可以作为指导 AI 做事的工作流文档。比如我自己就用 AGENTS.md 来定义各种工作流，像图文创作、产品客服、数据分析这些场景，都可以用一份 Markdown 文件把 AI 的工作方式固定下来，每次启动自动加载，省得重复交代。
后面我会统一用 CLAUDE.md 来讲解，但里面的技巧对所有工具都适用。
三、为什么一定要写好这个文件？
你可能觉得，不就是个配置文件吗，随便写写不就行了？
大错特错！CLAUDE.md 的质量直接决定了 AI 帮你干活的效率和准确度。
以我自己天天用 AI 编程的体验来看，一个好的 CLAUDE.md 至少能解决 3 个问题：
第一，减少重复沟通。
没有 CLAUDE.md 的时候，每次新会话我都得重复交代一遍技术栈、代码规范、项目结构。有了它，这些信息 AI 自动就知道了。
第二，提升代码一致性。
之前 AI 有时候用 React 函数组件，有时候给我整个 class 组件出来；有时候用 CSS Modules，有时候给我写内联样式。规范写进 CLAUDE.md 后，这种问题基本消失了。
第三，降低出错率。
比如我的项目里有个特殊的 API 响应格式 { success, data, error }，不写进规则的话，AI 每次都按自己的习惯来。写进去之后，Claude 就会自动遵循，不用我每次纠正。
之前我在另一篇文章里提到过，规则文件在 50 行左右时遵循率可以达到 94%，但如果一股脑堆到 400 行，遵循率就掉到了 71%。
所以 CLAUDE.md 不是越多越好，而是要精准。
这就引出了最核心的问题，也是本文的重点，怎么写好 CLAUDE.md 文档？
四、怎么写好 CLAUDE.md？
下面这些技巧，很多是经过社区大量实践和我个人验证的经验，建议仔细阅读，细细品味。
1、控制在 200 行以内
这是 Claude Code 官方文档给出的建议。
CLAUDE.md 的内容会在每次会话开始时加载到 AI 的上下文窗口中。这个窗口是有限的，你的规则文件越长，留给实际工作内容的空间就越少。
而且 AI 对指令的遵循能力跟指令数量负相关。社区有人引用过一项研究，AI 大概能合理遵循 150 到 200 条指令，超过这个数之后，遵循质量会均匀下降，不仅仅是忽略新加的，而且全部都开始变差。
所以写 CLAUDE.md 要像写简历一样，精炼再精炼。
对于每一行，问自己一个问题：删掉它 AI 会犯错吗？
如果答案是不会，就果断删掉。
2、只写 AI 猜不到的东西
官方文档专门列了一个 CLAUDE.md 中应该写和不该写的清单，非常值得参考。
应该写进去的：
-
AI 不可能猜到的构建命令和测试命令 -
跟默认不同的代码风格规则 -
团队的 Git 规范（分支命名、PR 格式） -
项目特有的架构决策 -
开发环境的特殊要求（必需的环境变量之类） -
容易踩坑的地方
不该写进去的：
-
AI 读代码就能知道的东西 -
通用的语言规范（AI 本来就会） -
详细的 API 文档（放别的地方，CLAUDE.md 里放链接就行） -
写干净的代码、注意性能这种废话
像我做编程导航项目时，就把一些即使读代码也容易忽略的约定写进了 CLAUDE.md，比如 API 响应统一使用 BaseResponse 包装类、异常统一用 BusinessException 抛出。虽然 AI 深入分析代码也能发现这些模式，但写进规则之后能省掉它每次重新推断的过程，效率高很多。
3、用正面指令代替否定指令
这个技巧其实有点儿反直觉。。
有篇论文研究发现，87.5% 的 AI 规则违反都来自同一个原因，就是否定句反而把被禁止的概念给激活了。你写「不要使用分号」，AI 看到分号这两个字，反而更容易在后续生成中产出分号。
这跟心理学里的白熊效应一模一样。叫你不要想白熊，你脑子里马上就全是白熊。
所以正确的做法是用正面表述替代：
-
❌ 不要使用 class 组件 → ✅ 使用函数式组件和 Hooks -
❌ 不要用 any 类型 → ✅ 所有变量必须有明确的 TypeScript 类型定义 -
❌ 不要在主分支直接提交 → ✅ 所有变更通过 feature 分支提交 PR
4、指令要具体可验证
模糊的指令等于没有指令。AI 很擅长处理具体的规则，但对抽象的要求就会自行发挥。
举些例子：
-
❌ 正确格式化代码 → ✅ 使用 2 空格缩进 -
❌ 测试你的更改 → ✅ 提交前运行 npm test -
❌ 保持文件有序 → ✅ API handlers 放在 src/api/handlers/
越具体的指令，AI 越容易判断自己有没有遵循，违反了也更容易被发现。
5、用 Hooks 来强制执行
CLAUDE.md 本质上只是建议，不是 100% 生效的禁令。
像代码格式化、提交前跑测试、危险命令拦截这些任务，应该用确定性的自动化脚本来执行。
Claude Code 提供了 Hooks 机制，可以在 AI 操作的关键节点自动执行你预设的脚本。
比如你想让每次文件编辑后自动跑 ESLint，写一个 Hooks 配置就搞定了，AI 根本不介入，100% 会执行。
一句话总结就是，CLAUDE.md 负责建议，Hooks 负责强制操作。
6、大项目用路径规则按需加载
如果你的项目比较大，200 行根本装不下所有规范。这时候不要硬往 CLAUDE.md 里塞，而是用 .claude/rules/ 目录来拆分。
每个规则文件可以用 YAML frontmatter 指定只对特定路径的文件生效：
---
paths:
-"src/api/**/*.ts"
---
# API 开发规范
-所有API端点必须包含输入验证
-使用标准的错误响应格式
-添加OpenAPI文档注释
这样只有当 Claude 操作 src/api/ 下面的 TypeScript 文件时，这些规则才会加载到上下文中，既省了上下文空间，又不会用不相关的规则干扰 AI。
7、用 @import 做渐进式披露
社区里最受推崇的高级技巧叫渐进式披露，核心思想就是不要把所有东西塞进 CLAUDE.md，而是告诉 AI 去哪里找它需要的信息。
做法很简单。在项目中创建一个 docs/ 目录，放各类专题文档，然后在 CLAUDE.md 中用简短描述加触发条件来引用：
## 参考文档
### API 架构 — @docs/api-architecture.md
何时阅读：添加或修改 API 端点时
### 数据库设计 — @docs/database-design.md
何时阅读：创建或修改数据模型时
这样 Claude 只在真正需要的时候才会去读取对应的文档，平时不占用上下文空间。
CLAUDE.md 的 @path 导入语法支持相对路径和绝对路径，最多可以嵌套 4 层。
这个思路其实跟我之前讲的上下文工程和 Agent Skills 是类似的。AI 编程工具的上下文窗口是有限的，你不能一股脑把所有信息都塞进去。Anthropic 官方把这个策略叫 just-in-time，就是让 AI 按需获取信息，而不是全量加载。
8、让 AI 帮你维护
CLAUDE.md 不是写好了就不管了，它应该是一份随着项目成长不断完善的 “活” 文档。
Claude Code 的创始人推荐了一个习惯：每次 Claude 犯错，不要只修正错误，还要顺手让它把纠正写进 CLAUDE.md。
我自己也是这么做的，比如 Claude 用了错误的导入路径，纠正完之后跟它说一句：把这条规则更新到 CLAUDE.md 里，下次别再犯。
Claude 特别擅长给自己写规则，时间久了，你的 CLAUDE.md 就变成了一份完整的项目知识库，出错率会明显下降。
另外 Claude Code 现在还有一个 Auto Memory 自动记忆功能，Claude 会自动记录它在工作中发现的模式和偏好，存到 ~/.claude/projects/<项目>/memory/ 目录下。这些笔记每次会话都会自动加载，相当于 AI 给自己做了一份备忘录。
你随时可以用 /memory 命令查看和编辑这些记忆。
五、如何快速创建？
看到这里你可能会想，这些技巧我都记住了，但从零开始写一份完整的 CLAUDE.md 还是有点头疼。
别担心，有几个快速起步的方法。
用 /init 命令自动生成
在 Claude Code 中输入 /init，Claude 会自动分析你的代码库，生成一份包含构建命令、测试指令和项目规范的 CLAUDE.md。如果文件已经存在，它会建议改进而不是覆盖。
不过需要注意，自动生成的内容可能不够精确，毕竟 AI 只能看到你的代码成果，不理解背后的过程。
社区有人说过，CLAUDE.md 影响你工作流的每个阶段和产出的每个文件，一条不好的指令产生的破坏力远超一行坏代码。所以自动生成之后，一定要自己过一遍，该删的删、该补的补。
让 AI 从对话中沉淀
我自己经常用的一种方法是，先不急着写 CLAUDE.md，正常跟 AI 协作完成一两个任务。做完之后，让 AI 回顾整个对话过程，帮你总结出需要记住的项目规范和注意事项，直接写成 CLAUDE.md。
这样得到的规则文件是从实战中提炼出来的，比凭空想象要精准得多。
像我自己带团队做项目时，每次 Code Review 中发现 AI 犯的错误，都会让 Claude 把修正追加到 CLAUDE.md 里。做了一个月之后，这份文件已经沉淀了几十条非常有针对性的规则，新同事用 Claude Code 的时候上手也快了很多。
参考优秀的开源项目
GitHub 上有个 awesome-claude-md 仓库，收录了 100 多个真实项目的 CLAUDE.md 示例，覆盖各种技术栈和项目类型，包括 Anthropic 官方的、Cloudflare 的 monorepo 项目等等。
另外还有个 awesome-claude-code 仓库，整理了 Skills、Hooks、斜杠命令等 Claude Code 生态工具，也值得收藏。
有时间的话，可以让 AI 帮你分析一下这些案例，找个跟你项目技术栈接近的参考着写，比从零开始快多了。
记住，CLAUDE.md 的内容宁缺毋滥。
先从最关键的 20 行开始，在实际使用中再慢慢补充。
六、多层级配置和团队协作
如果你在团队中使用 Claude Code，或者同时做多个项目，有一些进阶玩法值得了解。
四层作用域
CLAUDE.md 不只能放在项目根目录，它支持四个层级，按加载顺序从先到后排列：
1）组织级，公司 IT 统一部署的规范，所有人强制生效
2）用户级 ~/.claude/CLAUDE.md，对你本机的所有项目生效
3）项目级 ./CLAUDE.md，只对当前项目生效，可提交到 Git
4）本地级 ./CLAUDE.local.md，只对当前项目生效，不提交到 Git
加载越靠后的内容，AI 越倾向于优先遵循，所以优先级是 本地级 > 项目级 > 用户级。但组织级比较特殊，它虽然加载最早，却 不可被个人或项目设置排除，属于公司强制执行的底线规范。
建议团队共享的规范写在项目级，个人偏好写在本地级，两边互不干扰。
团队共建 CLAUDE.md
Claude Code 的创始人推荐把 CLAUDE.md 用 Git 来管理，让团队成员共同维护。
每当有人在 Code Review 中发现 AI 犯了什么错误，就把修正追加到 CLAUDE.md 里。时间久了，这个文件就沉淀了团队的开发经验和规范，变成了整个团队的 AI 使用手册。
我们自己团队也是这么做的。像面试鸭后端项目的 AGENTS.md，里面沉淀了技术栈选型、Spring Boot 分层规范、统一响应格式、异常处理方式、数据库命名规则等约定。新同事入职直接看这份文件就能上手，Claude 也能自动遵循这些规范生成代码，省了大量沟通成本。
重要规则一定要存文件
当你在对话中用 /compact 压缩上下文时，项目根目录的 CLAUDE.md 会被重新读取和注入。但你在对话中口头说的指令，比如后面的代码都用 async/await，压缩后就没了。
所以，凡是重要的规则，一定要写进 CLAUDE.md，不要只在对话里说。这一点跟我之前讲的上下文工程也是相通的，持久化的信息要落到文件里，别光靠 AI 的短期记忆。
七、排查不生效的问题
如果你发现 AI 好像没在遵守 CLAUDE.md 里的规则，可以按这个顺序排查：
1）运行 /memory 命令，看看你的 CLAUDE.md 有没有被正确加载
2）检查指令是不是太模糊了。比如格式化好代码这种 AI 没法执行，改成使用 2 空格缩进、单行不超过 80 字符
3）检查不同文件之间有没有矛盾的指令。如果 CLAUDE.md 里说用 MyBatis Plus，某个 rules 文件里又说用 MyBatis Flex，AI 可能随便选一个
4）如果某个操作必须在特定时机执行，比如每次提交前跑 lint，就不要靠 CLAUDE.md 了，改用 Hooks
最后哔哔
没想到吧，就这么一个 Markdown 文件，其实是 AI 编程时代最重要的基础设施之一。
以前我们写 README.md 是给人看的，现在写 CLAUDE.md 是给 AI 看的。但本质都一样，就是把项目的重要信息组织好、传达清楚。区别在于，给 AI 写的说明书要更精炼、更具体、更可执行。
如果你还没有为自己的项目写一份 CLAUDE.md，马上就可以试试。从最简单的 20 行开始，把技术栈、构建命令、和 AI 总是犯错的几个规则写进去，你会立刻感受到它的强大。
我是鱼皮，持续分享 AI 编程干货。觉得有用的话记得点赞收藏和关注~
也欢迎在评论区聊聊：你用 AI 编程时，踩过哪些坑？最讨厌 AI 跟你回复什么？