我一开始以为给 AI 下指令就是聊天。后来发现我错了，而且错得很费钱。
去年有一阵，我在一个项目里用 AI 编程助手。每个新会话它都是失忆状态：项目结构要重新讲，代码规范要重新说，连「别动那个生成出来的文件」这种话，我都重复打过四五遍。它不是记不住，是每次都换了个人。会话一关，上一个人就走了，什么都没留下。
后来我知道了 CLAUDE.md 和 AGENTS.md 这两个文件。把项目规则写进去，AI 每次开工都会先读一遍，不用你再交代。这篇文章讲清楚：它们是什么、放哪儿、怎么写有用，以及为什么我以前那些指令老是不生效。
它解决的是「每次都从零开始」的问题
先说原理。Claude Code 的官方文档开头就写了：每个会话都是全新的上下文窗口。对话记录没了，你上次说过的偏好、纠正、背景，也一并清零。
CLAUDE.md 和 AGENTS.md 就是填这个坑的。它们是放在项目里的普通 Markdown 文件，里面写你希望 AI 每次开工都知道的事。AI 启动会话时自动把这些内容读进上下文。
打个比方：新同事入职，你不会每天早上重新介绍一遍公司架构。发一份员工手册，他自己看。这两个文件就是 AI 的员工手册，你写一遍，永久生效（直到你改它）。
CLAUDE.md 和 AGENTS.md 有什么区别
两个文件干的是同一件事：给 AI 编程助手提供项目规则。区别在于出身和覆盖范围。
OpenAI Codex 联合 Amp、Google 的 Jules、Cursor、Factory 这几家具厂商共同推的一个开放格式，现在由 Linux 基金会旗下的 Agentic AI Foundation 负责维护。它的好处是格式通用，一份文件多家通吃。官方页面给过一个数字：已有六万多个开源项目在用。Cursor 的文档里明确写了支持项目根目录和子目录的 AGENTS.md。OpenAI Codex CLI、Google Gemini CLI 也都支持。
CLAUDE.md 是 Anthropic 家 Claude Code 自己的方案。有趣的是，Claude Code 现在也会直接读 AGENTS.md，你的仓库如果只放了 AGENTS.md，Claude Code 可能什么都不用改。规则是这样的：工作目录或上级目录里只有 AGENTS.md，就读 AGENTS.md；如果同时有 CLAUDE.md，就以 CLAUDE.md 为准。
所以怎么选？给个简单结论：只在 Claude Code 一个工具里干活，两个都行；团队里同时用 Cursor、Codex、Claude Code，就写 AGENTS.md，一份文件通吃。
放哪儿有讲究
这两个文件不是随便放的，放的位置决定规则管多大范围。用 Claude Code 举例，从大到小这么几个层级：
全局级：~/.claude/CLAUDE.md。你自己所有项目共享的个人偏好。比如「我习惯四个空格缩进」「回答用中文」。
项目级：项目根目录下的 CLAUDE.md 或 AGENTS.md。跟着仓库走，通过提交进 / 版本控制，全团队共享。这是最常见的用法。编码规范、目录结构说明、常用命令都放这里。
本地级：CLAUDE.local.md。同样是项目级规则，但不提交，只对你自己生效。比如你本地测试环境的地址，或某个只有你会碰到的特殊配置。这个文件要加进 .gitignore。
子目录级：Claude Code 还支持在子目录里放一个自己的 AGENTS.md，大项目用。每个模块可以各管各的规则，AI 打开哪个目录的文件，就读哪个目录的规则。
顺便说一句，位置层级是有优先级的，越具体的文件越后加载、越靠前说话。如果两条规则打架，AI 可能随手挑一条听，官方文档都专门提醒过别在文件里写自相矛盾的规则。文件写完发现 AI 突然变笨，先检查是不是规则打架。
大项目有个联动机制
AGENTS.md 的官方文档里有条 FAQ：大仓库怎么办？答案是在子目录里再放 AGENTS.md。AI 处理哪个子目录的文件，就近读哪个规则，离得近的优先。
这个设计很实在。monorepo（一个仓库装好几个项目）可以每个包有自己的习惯。官方自己也这么用，OpenAI 的主仓库里面放了 88 个 AGENTS.md 文件。
怎么写才有用
文件本身的门槛低到不能再低：纯文本，Markdown 语法，没有强制字段。真正的门槛在「写什么」。
先说官方建议里最值得听的一条：写得具体。对比一下这两种写法：
模糊：「代码要写得整洁。」具体：「缩进用两个空格。」「提交前跑 npm test。」「API 处理函数统一放在 src/api/ 目录下。」
前者 AI 只能自己猜什么叫整洁，猜出来多半不是你想要的。后者每条都能直接执行，机器听完就知道该干什么。官方文档给的原话就是这个意思：写「使用 2 空格缩进」，别写「格式化代码」。
再一条：控制篇幅。Claude Code 官方建议单个文件控制在 200 行以内。原因很简单，这些内容每个会话都要进上下文，写太长既费 token，还会让 AI 抓不住重点。
那多步流程怎么办？两条路。Claude Code 用户可以把只对某几类文件生效的规则挪到 .claude/rules/ 目录，做成按路径加载的规则，用到哪类文件才读哪条；多步骤的固定流程，可以写成单独的技能文件（这是另一个话题，篇幅有限不展开）。这两类内容不留在了 CLAUDE.md 里。
写什么？主题可以参考我之前总结过的三条提示词铁律，那三条在这里同样适用：说清用途，明确输出格式，什么都别绝对化。判断标准更简单：这是不是每次都要跟 AI 交代的事？是，写进去。不是，别写，它是给「必须每次都在场」的信息用的。官方推荐的几类：项目概览、构建和测试命令、代码规范、测试怎么跑、注意事项。
一次说清楚：它不负责哪些事
容易跟这两个文件搞混的，还有两个东西。顺手分清楚。
一个是聊天，就是会话窗口里的对话，跟系统提示词也不是一码事。聊天指令只管这一次，权重最高。官方 FAQ 写得明确：如果聊天里说的话跟 AGENTS.md 不一致，聊天优先。也就是说，这两个文件管长期惯例，聊天管临时调整，你想覆盖某个规则，会话里说就行。
另一个是 Agent Skills，就是 Anthropic 推的那套技能文件夹。两者都是持久化，用途不一样。CLAUDE.md 塞的是「永远该在场的常识」，触发靠开机；Skills 塞的是「特定任务才需要的流程」，触发靠任务匹配。写周报的完整步骤，做成 Skill 合适；「提交前先跑测试」这种一句话规则，写进 CLAUDE.md 合适。
Agent Skills 那套机制之前写过一篇单独的入门，这里不重复，想了解的可以翻翻。上下文窗口本身怎么运作，之前那篇也讲了。
试一下
如果你在用 Cursor、Codex、Claude Code 里的任何一个，现在有个几乎零成本的动作：在项目根目录建一个空的 AGENTS.md，把三条你最常重复交代的事情写进去。比如跑测试的命令、代码风格的偏好、别碰哪些文件。
下次开个新会话，直接说「给我提交一下代码」。如果它没问你怎么写提交信息、自动跑了测试、按你的格式提交，你会马上明白这俩文件是干嘛的。
你有什么规则是每次都得跟 AI 重复交代的？评论区说说，我从里面挑几个通用的，下篇写成模板直接给你抄。