AGENTS.mdAGENTS.md：存放位置及工具读取方式
AGENTS.md 是一个纯 Markdown 格式的项目指令文件，大多数编程 agent 无需额外配置即可读取。OpenAI 已将其贡献给 Linux Foundation 旗下的 Agentic AI Foundation，超过 60k 个开源项目正在使用它。
存放位置
- 仓库根目录下的 AGENTS.md，适用于整个项目。
- 子目录或 package 中的嵌套 AGENTS.md；agent 会使用目录树中距离最近的文件。
- OpenAI Codex：全局文件 ~/.codex/AGENTS.override.md；若该文件为空或不存在，则使用 ~/.codex/AGENTS.md。
- Cline：全局文件 ~/.agents/AGENTS.md。
- Claude Code 也支持 .claude/AGENTS.md。
格式
纯 Markdown，无需 frontmatter 或必填字段；标题格式不限。格式没有大小限制，但 OpenAI Codex 会在 project_doc_max_bytes 处停止读取，该值默认是 32 KiB。
# Acme web app
Customer-facing web app with an admin area and a REST API.
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`
## Code style
- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.
## Never
- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.
优先级与合并
距离正在编辑的文件最近的 AGENTS.md 优先级最高；聊天中明确给出的指令优先于任何文件。OpenAI Codex 会从项目根目录到工作目录，按每个目录拼接一个文件，因此越靠近工作目录的文件越靠后，优先级也越高。只要存在 CLAUDE.md，Claude Code 默认就会跳过 AGENTS.md。
可读取该文件的工具
| 工具 | 支持情况 |
|---|---|
| OpenAI Codex | 原生支持。先读取全局文件，再从根目录到工作目录，每个目录最多读取一个文件；默认上限为 32 KiB。 |
| Claude Code | 从 v2.1.277 起原生支持，但仅在不存在 CLAUDE.md 或 CLAUDE.local.md 时生效；除非设置为 claude-md-and-agents-md。 |
| Cursor | 原生支持根目录和嵌套文件；嵌套文件会与父级文件合并，越具体的文件优先级越高。 |
| GitHub Copilot (cloud agent, code review, VS Code) | 原生支持，可放在仓库中的任意位置；距离最近的文件优先。 |
| Devin Desktop (formerly Windsurf) | 原生支持。根目录文件始终生效；子目录中的文件仅适用于该目录。 |
| Cline | 原生支持，也支持全局文件 ~/.agents/AGENTS.md；可在 Rules 面板中启用或停用。 |
| Gemini CLI | 选择启用：在 .gemini/settings.json 的 context.fileName 中添加 AGENTS.md。 |
| Aider | 选择启用：在 .aider.conf.yml 中添加 read: AGENTS.md。 |
| OpenClaw | 原生支持，将其作为 agent 工作区中必需的操作指令文件。 |
| Listed on agents.md (not individually re-verified) | agents.md 列出的 23 种工具之一，包括 Amp、Jules、Zed、Warp、goose、opencode 和 JetBrains Junie；我们没有逐一核实这些工具。 |
提示
- 要重命名旧的 AGENT.md？agents.md 建议运行 mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md，让两个文件名都能继续使用。
- 列出测试和 lint 命令：agent 会尝试运行找到的检查，并在完成前修复失败项。
- 在 monorepo 中，为每个 package 添加简短的 AGENTS.md，而不是不断扩充根目录下的文件。
- 在 OpenAI Codex 中，同一目录下的 AGENTS.override.md 优先于 AGENTS.md。
通过一个表单，为五种工具生成 AGENTS.md 和对应的规则文件。 打开 AGENTS.md 生成器 →
其他指令文件
CLAUDE.mdGEMINI.md.cursor/rules/*.mdc.github/copilot-instructions.md.devin/rules/*.md.clinerules/~/.openclaw/workspace/AGENTS.md