用 AI 编程助手的人，多半遇到过这种窝火事：项目明明定了单引号风格，它每次都写双引号；测试命令明明写在文档里，它偏要自己发明一个跑不通的。
你只能在对话里反复纠正。它点头答应，下个会话（session）照旧。原因很简单：每次新会话开始，助手的记忆是空白的，你上次说过什么，它不知道。
CLAUDE.md 和 AGENTS.md 就是冲着这个问题来的。两个都是纯文本的 Markdown 文件，放在项目里，作用一样：AI 助手每次开工先读一遍，把你定下的规矩带上。可以理解成给 AI 的员工手册。
一、CLAUDE.md：Claude Code 的项目记忆
CLAUDE.md 是 Claude Code 的方案。官方文档把它的位置说得很清楚：每次会话开始时加载，内容是「你写给 Claude 的持久指令」。
Claude Code 实际有两套记忆机制，分工不同。CLAUDE.md 是你写的，放编码规范、工作流程、项目架构这些规矩；另一套叫 auto memory，是 Claude 自己记的笔记，写的是你纠正过它的地方、你的偏好。一个管「我要它做什么」，一个管「它自己学到什么」。加载上有个细节：auto memory 每次只带前 200 行或 25KB 进会话，所以别把它当仓库使。
CLAUDE.md 的层级也值得知道。可以放三档：项目根目录一份（全项目生效）、用户主目录一份（你个人的全局偏好）、组织层面一份（全公司规范）。会话开始时按当前目录合并加载。写的时候有一条经验：指令越具体、越简洁，Claude 执行得越稳定。空泛的「写好一点」没用，「函数注释用中文、单引号、测试跑 pnpm test」才有用。
还有一条官方口径：CLAUDE.md 对 Claude 是上下文，不是强制配置。要硬卡某个动作，得用 hooks 这类机制。手册写得再凶，也拦不住个别情况下员工看走眼。
二、AGENTS.md：一份手册，各家通吃
AGENTS.md 走的是另一条路：做成开放格式，谁家的编程助手都能读。官网的介绍很形象：README 是给人看的项目说明，AGENTS.md 是给 agent 看的 README，专门放构建步骤、测试命令、代码约定这些「放 README 里会显得杂乱」的信息。
采纳速度是它最大的亮点。官网挂出的统计是超过 6 万个开源项目已经在用。OpenAI 的 Codex、Google 的 Gemini CLI、Cursor 等主流工具都已支持。对开发者来说，这意味着一份文件不用为每家工具各写一遍。
典型内容就四块：环境怎么装、测试怎么跑、代码风格是什么、有哪些别碰的坑。官网给的示例长这样：
# AGENTS.md
## Setup commands
- Install deps: pnpm install
- Run tests: pnpm test
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
再比如「提交前跑完整测试」「数据库密码在 .env，别读这个文件」。都是那种你懒得每次口述、但每次不说它就犯错的事。
三、两个文件什么关系
Claude Code 的处理方式是个好答案：项目里有 AGENTS.md 的话，Claude Code 直接读它，替代 CLAUDE.md。对使用者来说，这事已经简化成了「写一份 AGENTS.md 放项目根目录」。
给个粗略的选择建议：
- 新项目，直接用 AGENTS.md，通用性最好
- 重度 Claude Code 用户，想要 auto memory、组织级配置这类深度功能，CLAUDE.md 的生态更全
- 拿不准，就 AGENTS.md 放项目里，个人偏好另放主目录的 CLAUDE.md，两者可以共存
四、和系统提示词的关系
你可能在别处见过 system prompt 这个词。它和这两个文件是什么关系？
System prompt 是模型侧的概念：每次请求发给模型的最高优先级指令，由工具厂商写。CLAUDE.md 和 AGENTS.md 是应用侧的做法：把项目指令塞进上下文，效果上像是给每次会话追加了一段系统提示词，但写的人是你。
区别在控制权。system prompt 你改不了，这两个文件是你的地盘。这也是为什么提示词注入是 AI 安全的头号风险：上下文里塞进来的指令，模型很难分清哪些是真规矩。往 AGENTS.md 里贴不明来源的内容，和把陌生人写进员工手册是一个性质。
最后
上手成本几乎为零：新建一个 Markdown 文件，把「你每次都要口头交代的事」写进去，几行就够，之后让 AI 自己慢慢补。
一个观察：编程助手的基础设施正在从「对话里哄」转向「文件里写」。规矩落在文件里，可版本管理、可团队共享、换工具也能带走。这一步很像当年把配置从代码里拆出来，方向不难猜。
参考来源：
- agents.md 官网（AGENTS.md 格式说明与生态统计）
- Claude Code 官方文档：How Claude remembers your project（code.claude.com/docs/en/memory）