AGENTS.md 和 CLAUDE.md，其实就是写给 AI 的那份 README

用 AI 写代码，有一件事挺磨人的：每开一个新对话，AI 就像第一天来上班的新同事，项目怎么跑、代码怎么写、哪些坑千万别踩，你都得从头再交代一遍。交代一次还好，交代十次，人就烦了。

AGENTS.md 和 CLAUDE.md 要解决的，就是这个问题。

先说它们到底是什么

其实这两个文件干的是同一件事。它们都是放在项目里的 Markdown 说明文件，AI 编程助手每次开工前先读一遍，从里面知道这个项目怎么构建、怎么测试、要守哪些规矩。

那区别在哪？我觉得最简单的理解是：看谁在用。

AGENTS.md 是一个开放的通用格式，不属于任何一家公司。按 AGENTS.md 官网的说法，已经有 6 万多个开源项目在用，支持它的工具也不少，OpenAI Codex、Google Jules 和 Gemini CLI、Cursor、GitHub Copilot 的编程代理、Windsurf、Zed、Aider 等都在列。官网给它的定位是「给 AI 看的 README」，README 是写给人看的，而那些 AI 需要、但塞进 README 又会把它弄得一团乱的细节，就放进 AGENTS.md。顺带提一句，标准写法是复数、全大写的 AGENTS.md，别写成 agent.md。

CLAUDE.md 则是 Anthropic 家 Claude Code 专用的。按 Claude Code 官方文档，它可以分层放：组织级的由 IT 统一下发，Linux 上放在 /etc/claude-code/CLAUDE.md；个人级的放在 ~/.claude/CLAUDE.md，对你所有项目都生效；项目级的就放在仓库里，跟团队共享。另外它还支持用 @路径 去引用其他文件。

说到这里，可能有人会问，那我到底该写哪个？好在两者现在是能互通的。仓库里只有 AGENTS.md、没有 CLAUDE.md 的时候，Claude Code 会直接把 AGENTS.md 当成项目说明来读。所以选择其实不复杂：项目要给好几种 AI 工具用，写一份 AGENTS.md 最通用；只用 Claude Code，而且确实需要个人级或者组织级的规则，再上 CLAUDE.md。

那这个文件是 AI 自己生成的吗

两种情况都有。比较常见的做法，是先让 AI 生成一份，再由人来改。

Claude Code 里输入 /init，它会把代码库读一遍，自动写出一份 CLAUDE.md 初稿；OpenAI Codex 也有 /init，生成的是 AGENTS.md。Claude Code 还有个「自动记忆」功能，会根据你的纠正自己记点心得，不过那是另外一套，和 CLAUDE.md 是分开存的，别搞混了。

但这里有个问题，你仔细想想就明白：AI 生成的初稿，多半只是把目录结构和常用命令扫了一遍。真正有价值的东西，比如团队的规范、哪些事是禁忌、之前踩过哪些坑，这些在代码里是看不出来的，AI 再聪明也扫不出来。

通常会写成什么样

没有强制模板。官网说得很明白，它就是普通的 Markdown，没有必填字段，标题想怎么起就怎么起。不过大家的写法慢慢也趋同了，常见的结构基本是：项目概览、构建和测试命令、代码风格、测试要求、安全注意事项，再加一段提交规范。

举个例子，一份骨架大概长这样（里面的内容只是示意，换成你自己项目的实际情况就行）：

# 项目说明
一句话讲清这是什么项目、技术栈（如 Next.js + TypeScript）。

## 常用命令
- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 跑测试：`pnpm test`（提交前必须全部通过）

## 目录结构
- `src/api/handlers/`：接口处理
- `src/components/`：前端组件

## 代码规范
- TypeScript 严格模式，2 空格缩进
- 禁止使用 any

## 注意事项（踩过的坑）
- 不要改 `migrations/` 里已有的文件，只能新增
- 密钥只从环境变量读，禁止写进代码

## 提交规范
- 提交信息用 `feat:` / `fix:` 开头

怎么写才真的有用

这部分我觉得 Anthropic 官方文档里的建议挺实在的，值得单独拿出来说。

先是什么时候该往里加东西。AI 第二次犯同一个错的时候；代码审查发现了 AI 本该知道的事的时候；你在聊天里又打出了上次打过的那句纠正的时候；或者这条背景新同事也需要知道的时候。官方的说法我很认同：把它当成一个记录你原本要反复解释的事情的地方。

然后是写得具体，能验证。写「用 2 空格缩进」，而不是「格式要规范」；写「提交前跑 npm test」，而不是「要测试」；写「接口放在 src/api/handlers/」，而不是「文件要有条理」。后面那几种写法，人看了都不知道具体该怎么做，更别说 AI 了。

还有就是短一点。每份文件控制在 200 行以内，文件越长，占的上下文越多，AI 照着做的程度反而越低。只跟某个目录有关的规则，可以拆成按路径生效的规则文件；多步骤的流程，就做成技能（skill）。组织方式上，用标题加列表，分好组的条目比一大段文字更容易被遵守。

另外要定期清理矛盾。两条规则互相冲突的时候，AI 可能随便挑一条去执行，这就很麻烦了。Claude Code 可以跑一下 /doctor prompt-audit，帮你检查过时或者互相矛盾的内容。

最后一点我觉得特别要记住：这个文件是参考，不是强制。AI 把它当上下文看，并不保证一定照办。真正必须禁止的操作，得用 hook（在工具执行前拦截的脚本）来硬性挡住，别指望一句「禁止」就能管住。

人一定要亲自动笔吗

不用。你完全可以用大白话跟 AI 说一句「以后别动 migrations 里的旧文件」，让它自己整理成规范的条目写进去。Claude Code 里输入 /memory，就能直接打开这些说明文件改。

不过有两点得留个心眼。一是写完要扫一眼，AI 有时候会把你的意思写宽了或者写窄了，甚至顺手加几句你根本没说过的话。二是内容的来源只能是你。AI 能把话写得很专业，但哪里踩过坑、什么事绝对不能做，只有你自己知道。

所以比较顺手的流程大概是这样：先用 /init 生成一份初稿，把显而易见的内容删掉；之后每纠正 AI 一次，就顺口让它补一条进去；隔一段时间再整体审一遍，把过时的、冲突的条目清掉。

人不一定要亲自动笔，但把关这件事，还是得自己来。

参考资料：AGENTS.md 官网、Claude Code 官方文档