AGENTS.md 与 CLAUDE.md：给 AI 留一份项目说明书
前置阅读：进阶手册：让 AI 更懂你的项目
AGENTS.md 是放在项目根目录的一份项目说明书：Claude Code、Codex、OpenCode 在开工前都会自动读它，不用你每次口头交代技术栈和规矩。
Claude Code 的记忆文件叫 CLAUDE.md，机制相同、文件名不同。本页把两份文件一起配好，让三款工具读同一套内容。
学完你能做什么
- 写出一份放在项目根目录、三款 AI 编码代理都会自动读取的
AGENTS.md - 说清 AGENTS.md 该写哪四块内容，以及为什么不能写成长篇大论
- 给 Claude Code 配好
CLAUDE.md，并保证两份文件永远不打架 - 开一个新会话验证：AI 不用你解释，就能答出项目怎么启动、守什么约定
你现在的困境
- 每次开新会话，都要重新交代一遍「我们用 pnpm 不用 npm」「测试跑
pnpm test」。 - 上个会话说好的规矩，这个会话 AI 全忘了，转头又给你
npm install一通乱装。 - 项目约定只存在你脑子里：换个会话、换个工具、拉个队友协作，全要重新讲一遍。
什么时候用这一招
当你需要：
- 让 AI 在每个新会话自动知道项目的技术栈、常用命令和代码约定
- 把规矩提交进 git，团队里每个人、每个 AI 共享同一份
- 今天用 Claude Code，明天换 Codex 或 OpenCode，说明书照样生效
而且不想：
- 每次开工前，往对话框里粘贴一大段「项目背景」
- 同一套规矩在三个工具里各配一遍，还配得不一样
🎒 开始前的准备
- 读完前置课程 进阶手册：让 AI 更懂你的项目
- 有一个项目目录，刚起步的空项目也行
- 装好任意一款 AI 编码代理：Claude Code、Codex 或 OpenCode。还没装？先看 安装 Claude Code：10 分钟准备就绪
- 留出 10 分钟
核心思路
三款工具的「说明书机制」长得很像，差别在文件名和查找方式：
| 工具 | 读哪个文件 | 项目级放哪 | 全局文件（个人偏好） |
|---|---|---|---|
| Claude Code | CLAUDE.md；没有它时也可直接读 AGENTS.md（需 v2.1.277+） | 项目根目录 ./CLAUDE.md 或 ./.claude/CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md，开工前先读 | 项目根目录 | ~/.codex/AGENTS.md |
| OpenCode | AGENTS.md（V2 只认它，不拿 CLAUDE.md 兜底） | 项目根目录 | ~/.config/opencode/AGENTS.md |
思路就一句话：以 AGENTS.md 为唯一事实源。Codex 和 OpenCode 直接读它；Claude Code 用一份 CLAUDE.md 引用它的内容，再补 Claude 专属的说明。改规矩只改一处，三款工具同步生效。
CLAUDE.md 自己还分作用范围：企业级（组织统一管理）、用户级（~/.claude/CLAUDE.md，放个人偏好，对你所有项目生效）、项目级（进版本控制，团队共享）。本页主要配项目级。
跟我做
第 1 步：在项目根目录新建 AGENTS.md
为什么：说明书越具体，AI 猜得越少。Codex 官方指南给的示例也是一条一行、可直接执行的指令，而不是一句「代码要规范」。
在项目根目录（和 README 同级）新建 AGENTS.md，写四块内容：
# 项目说明
- 一句话：这个项目做什么（例：一个课程预约网站）
- 技术栈：Next.js + TypeScript，包管理用 pnpm
- 常用命令：pnpm install / pnpm dev / pnpm test / pnpm build
- 代码约定：组件放 src/components，提交前跑 pnpm test，不要直接改构建生成的文件每条规矩都写成可验证的指令：「用 2 空格缩进」好过「格式要规范」，「提交前跑 pnpm test」好过「记得测试」。
你应该看到：文件躺在根目录，几十行以内，每条规矩一行。
- 小检查：让一个不懂你项目的人看 30 秒，他能说出项目用什么技术栈、怎么启动
第 2 步：把说明书放对位置
为什么：三款工具找说明书的方式不同，但都认项目根目录——Codex 从项目根一路查到你所在的子目录；OpenCode 先读全局文件，再从当前目录逐级向上收集；Claude Code 读当前目录及上层的 CLAUDE.md。放根目录，三种找法都能命中。
操作：
- 确认
AGENTS.md在项目根目录，别塞进src/这类子目录，也别放桌面。 - 提交进 git。OpenCode 文档明确建议把项目指引文件提交进仓库，让每个协作者拿到同一份指引。
- 个人偏好（比如「回复用中文」）别写进项目说明书，放到各工具的全局提示词文件：Codex 用
~/.codex/AGENTS.md，OpenCode 用~/.config/opencode/AGENTS.md，Claude Code 用~/.claude/CLAUDE.md。
你应该看到：git status 显示 AGENTS.md 已被跟踪；根目录下 ls 能看到它和 README 并排。之后无论你从根目录还是某个子目录启动代理，它都找得到这份说明书。
第 3 步：给 Claude Code 配一份 CLAUDE.md
为什么：Claude Code 默认读 CLAUDE.md。只要工作目录或上层有一份项目级 CLAUDE.md，它就不再读 AGENTS.md——不打通两份文件，Claude Code 会「看不到」你的说明书。
方式 A（推荐）：CLAUDE.md 导入 AGENTS.md
在根目录新建 CLAUDE.md：
@AGENTS.md
## Claude Code 专属
- （可选）只写给 Claude 的额外说明@AGENTS.md 是 Claude Code 的导入语法：AGENTS.md 的内容会被展开加载，Claude 专属的说明写在导入下面。规矩只维护一处。
方式 B：软链接
ln -s AGENTS.md CLAUDE.md一条命令，两份文件永远同步，成功时没有输出。但 Windows 上创建软链接要管理员权限或开发者模式，Git 还可能把它检出成纯文本——只要团队里有人用 Windows，就选方式 A。
方式 C：内容照搬
把 AGENTS.md 的内容复制进 CLAUDE.md。最直观，代价是改规矩要改两处；两处说法不一致时，AI 可能随便挑一条信。
你应该看到：在项目目录运行 claude，输入 /context，Memory files 列表里出现 CLAUDE.md，导入的 AGENTS.md 内容随之加载。
- 小检查：
/context的 Memory files 里有 CLAUDE.md
💡 不建 CLAUDE.md 会怎样？
新版 Claude Code（v2.1.277 起）在没有 CLAUDE.md 时会直接读 AGENTS.md，会话开头会显示一行类似 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 的提示。但个别会话不支持（比如从旧版本升级后的第一个会话），所以配一份 CLAUDE.md 最稳妥。
第 4 步：开新会话验证说明书生效
为什么：三款工具都在会话开始时读说明书——Claude Code 每个会话开始加载记忆文件，Codex 每次运行构建一次指令链，OpenCode 对嵌套指引文件的改动也要新会话才生效。在旧会话里测，测到的是旧规矩。
操作：
- 开一个全新会话：Claude Code 在项目目录运行
claude，Codex 运行codex。 - 直接问：「这个项目怎么启动？有什么代码约定？」
- Codex 用户可以跑官方指南给的验证命令：
codex --ask-for-approval never "Summarize the current instructions."你应该看到：AI 不看你的任何额外解释，就能答出文件里写的启动命令和约定；Codex 会按加载顺序复述全局和项目文件里的指引。
- 小检查：换一个子目录再启动一次，AI 依然找得到说明书
检查点 ✅
AGENTS.md在项目根目录，包含项目简介、技术栈、常用命令、代码约定四块内容- 文件已提交进 git，任何人克隆仓库都能拿到同一份指引
- Claude Code 会话里运行
/context，Memory files 列出了 CLAUDE.md - 开新会话问「项目怎么启动」，AI 不用你解释就能答对
- AGENTS.md 与 CLAUDE.md 内容一致（导入或同步），没有互相矛盾的规矩
踩坑提醒
❌ 写成长篇大论
说明书越长，AI 越抓不住重点。Claude Code 官方建议每个 CLAUDE.md 控制在 200 行以内：太长会吃掉上下文、降低遵循度。Codex 那边也有总量上限，多份指引合计到 32 KiB（默认值）就停止加载。
正确做法：只写 AI 猜不到的事实（命令、约定、禁忌），一条一行，控制在几十行。
❌ 只写原则、不写命令
「代码要规范」是空话，AI 没法执行。
正确做法：写可验证的指令——「用 pnpm dev 启动、pnpm test 测试」「API 处理器放 src/api/handlers/」。
❌ Claude Code 看不到 AGENTS.md
常见原因：工作目录或上层有一份项目级 CLAUDE.md（或 CLAUDE.local.md），Claude Code 就只读 CLAUDE.md，用户级的 ~/.claude/CLAUDE.md 不算；或者版本低于 v2.1.277。
正确做法：claude --version 确认版本；/context 查看实际加载了哪些文件，/memory 列出各处记忆文件的位置；按第 3 步用 @AGENTS.md 导入打通。另外注意：OpenCode V2 只认 AGENTS.md，不拿 CLAUDE.md 兜底——两份文件都得有，别只配一边。
❌ 在旧会话里验证
改完说明书，马上在当前会话里问 AI，它答的还是旧规矩。
正确做法：改完文件，开新会话再测；Claude Code 里也可以直接运行 /context 确认文件已加载。
进阶技巧
- 让 AI 替你写初稿：Claude Code 里运行
/init，它会分析代码库，自动生成一份含构建命令、测试指令和项目约定的 CLAUDE.md 起步文件；文件已存在时它给改进建议，不直接覆盖。 - 给规矩做体检：Claude Code v2.1.283 起可用
/doctor prompt-audit，让 Claude 检查指令文件里过时、互相矛盾、引用了不存在文件的内容。 - 目录级覆盖（Codex）：在子目录放
AGENTS.override.md，Codex 会优先读它；仓库里已有TEAM_GUIDE.md这类文件时，可在~/.codex/config.toml的project_doc_fallback_filenames里登记成备用文件名。 - 挂更多指引（OpenCode）：在
opencode.jsonc的instructions数组里追加文件、glob 或网址，和 AGENTS.md 一起加载。 - 只属于你的项目偏好：Claude Code 支持根目录
CLAUDE.local.md，放个人的项目偏好，记得加进.gitignore。
本课小结
✅ 到这里你已经：
- 写出了一份
AGENTS.md：四块内容、一条一行、放项目根目录并提交进 git - 给 Claude Code 配了引用它的
CLAUDE.md，三款工具读同一套规矩 - 用新会话验证过：AI 不用你交代，就知道项目怎么启动、守什么约定
关键文件回顾：
| 文件 | 推荐位置 | 作用 |
|---|---|---|
AGENTS.md | 项目根目录 | 唯一事实源，Codex、OpenCode 直接读 |
CLAUDE.md | 项目根目录 | Claude Code 的记忆文件，用 @AGENTS.md 导入共享内容 |
~/.claude/CLAUDE.md | 用户主目录 | 个人偏好，对你所有项目生效 |
~/.codex/AGENTS.md | Codex 主目录 | Codex 全局指引，所有仓库继承 |
~/.config/opencode/AGENTS.md | OpenCode 配置目录 | OpenCode 全局指引，到处适用的规矩放这里 |
一句话记住：AGENTS.md 是给 AI 的项目说明书——写具体、放根目录、保持唯一。
下一课预告
说明书让 AI 懂了你的项目，下一课让它长出更多本事：Vercel × AI 编码代理：Plugin、Skills 与 MCP 三件套。
你会学到：
- Vercel 为 AI 编码代理准备的 Plugin、Skills、MCP 三件套分别是什么
- 怎么用官方命令把它们接入你的代理
- 接入之后，AI 和你的 Vercel 项目之间能打通哪些事
想先把「写什么」想清楚，回顾 先规划再动手：把一句话想法变成需求清单；Claude Code 的基础操作见 Claude Code 用法：终端里的 AI 编程代理。