如何为编程智能体编写 AGENTS.md 文件
写一份简短的 AGENTS.md，包含安装和测试命令、规则与边界，让 Claude Code 和 Gemini CLI 加载它，再用一个小任务测试。
AGENTS.md 是放在代码仓库根目录下的普通 Markdown 文件，用来告诉编程智能体如何处理这个项目：该运行哪些命令、代码放在哪里、哪些东西不要动。它没有必填的章节。保持简短，让每条规则都能核对，并确认每个智能体都加载了它。
本文介绍文件里该写什么、一份模板、Claude Code 和 Gemini CLI 如何找到这个文件，以及一个快速测试。用 Reunified 的 Mono 从手机启动智能体时，步骤也一样。
1. 确定文件里该写什么
agents.md 网站把它称为写给智能体的 README。写入每个会话都需要的信息，跳过智能体能从代码中了解到的内容。
| 写进 AGENTS.md | 不要写进去 |
|---|---|
| 安装、测试和 lint 命令 | 密码、API 密钥和令牌 |
| 主要代码所在的位置 | 完整的文件树或依赖列表 |
| 与默认做法不同的约定 | 冗长的操作流程（改为链接到文档） |
| 绝不能修改的文件、需要先询问的操作 | 个人偏好（写进智能体的用户级文件） |
在 monorepo 中，可以在每个包里各放一个 AGENTS.md。离所改文件最近的那份 AGENTS.md 优先，而你在对话中直接给出的指令又会覆盖它。
2. 从一份简短的模板开始
下面是一个虚构的例子，项目名为“tidy-recipes”，是一个使用 pnpm 的 TypeScript Web 应用：
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.只列出你在这个仓库里实际运行过的命令。命令写错了，智能体也会照单全收。
3. 写智能体能核对的规则
好的规则能让你事后核对智能体是否遵守了它。
| 含糊 | 具体 |
|---|---|
| 测试你的改动 | 完成前运行 pnpm test 和 pnpm lint |
| 保持文件井然有序 | 组件放在 src/components |
| 小心处理数据库 | 绝不修改 db/migrations/ |
| 总结你的工作 | 列出改动的文件和测试结果 |
把边界写成“绝不”和“先询问”两类规则，每行一条。
4. 让 Claude Code 和 Gemini CLI 读取它
agents.md 网站列出了支持这种格式的 Codex、Gemini CLI、opencode 等智能体，但其中一些需要先做设置。
默认情况下，较新版本的 Claude Code 只有在工作目录及其上级目录中都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，才会读取 AGENTS.md（见它的记忆文档）。如果你有其中某个文件，或者用的是旧版本，就在 CLAUDE.md 中导入 AGENTS.md。tidy-recipes 项目里有一个旧的 CLAUDE.md，所以在它顶部加上这一行，只给 Claude 看的说明放在下面：
@AGENTS.md
Prefer small commits.新建一个会话，运行 /context，确认 CLAUDE.md 出现在“记忆文件”（Memory files）下。如果没有 CLAUDE.md，/memory 会改为列出 AGENTS.md 的路径。
Gemini CLI 默认读取 GEMINI.md。要加入 AGENTS.md，把下面的内容写进项目的 .gemini/settings.json（见它的 GEMINI.md 文档）：
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}新建会话，然后运行 /memory show 查看加载了什么。其他智能体请查阅各自的文档。
5. 用一个小任务测试这个文件
在新会话中，给智能体布置这个任务：
先列出你加载的项目规则，以及每条规则来自哪个文件。然后把 src/components/SaveButton.tsx 中的按钮文字“Save recipe”改成“Save”。其他什么都不要改。
对照文件检查结果：
- 它提到了 AGENTS.md（或包含导入行的 CLAUDE.md）。
- 它运行了
pnpm test和pnpm lint，并报告了结果。 - 它没有动 db/migrations/，也没有添加依赖。
- 它列出了改动的文件。
用 git diff 亲自确认这处修改（见如何审查 AI 编程改动）。如果智能体说不出某条规则，文件很可能没有加载，请回到第 4 步。如果它说出了规则却没有遵守，就把规则写得更具体。
6. 保持简短，及时更新
Claude Code 的文档建议把 CLAUDE.md 控制在 200 行以内，因为文件越长，占用的上下文越多，智能体也越难稳定遵守。AGENTS.md 也按这个标准来写。上下文占满后会发生什么，请看上下文窗口指南。
智能体重复犯同一个错误时，就更新这个文件；删除过时的命令和相互冲突的规则。像对待代码一样提交它，并审查对它的修改。
这个文件只是给智能体提供指引，并不能强制执行任何规则。要阻止某个操作，请使用智能体的权限设置，或拒绝它的请求（见工具权限指南）。
在 Mono 中，智能体会在你电脑上项目的工作目录里启动，并在那里查找这些文件。你可以在 Mono 的编辑器中打开 AGENTS.md、CLAUDE.md 或 .gemini/settings.json，在手机上也可以，修改会自动保存。要新建这个文件，可以让智能体来做，或者从项目卡片打开终端。Mono 不会检查这个文件，也不会改变智能体加载哪个文件。Mono 还没有正式推出，你可以加入候补名单。
