---
title: "AGENTS.md：路径和格式 · DotsAgent"
description: "AGENTS.md 的存放位置、格式和 front matter，全局副本与嵌套副本的合并方式，以及哪些工具会读取它。核验日期：2026-10-01。"
url: https://dotsagent.io/zh/instructions/files/agents-md
---

AGENTS.md

# AGENTS.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。

`AGENTS.md`

```
# 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](https://developers.openai.com/codex/guides/agents-md) | 原生支持。先读取全局文件，再从根目录到工作目录，每个目录最多读取一个文件；默认上限为 32 KiB。 |
| [Claude Code](https://code.claude.com/docs/en/memory) | 从 v2.1.277 起原生支持，但仅在不存在 CLAUDE.md 或 CLAUDE.local.md 时生效；除非设置为 claude-md-and-agents-md。 |
| [Cursor](https://cursor.com/docs/context/rules) | 原生支持根目录和嵌套文件；嵌套文件会与父级文件合并，越具体的文件优先级越高。 |
| [GitHub Copilot (cloud agent, code review, VS Code)](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) | 原生支持，可放在仓库中的任意位置；距离最近的文件优先。 |
| [Devin Desktop (formerly Windsurf)](https://docs.windsurf.com/windsurf/cascade/memories) | 原生支持。根目录文件始终生效；子目录中的文件仅适用于该目录。 |
| [Cline](https://docs.cline.bot/features/cline-rules) | 原生支持，也支持全局文件 ~/.agents/AGENTS.md；可在 Rules 面板中启用或停用。 |
| [Gemini CLI](https://geminicli.com/docs/cli/gemini-md/) | 选择启用：在 .gemini/settings.json 的 context.fileName 中添加 AGENTS.md。 |
| [Aider](https://agents.md/) | 选择启用：在 .aider.conf.yml 中添加 read: AGENTS.md。 |
| [OpenClaw](https://docs.openclaw.ai/concepts/agent) | 原生支持，将其作为 agent 工作区中必需的操作指令文件。 |
| [Listed on agents.md (not individually re-verified)](https://github.com/agentsmd/agents.md/blob/main/components/CompatibilitySection.tsx) | 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 生成器 →](https://dotsagent.io/zh/instructions)

## 其他指令文件

[CLAUDE.md](https://dotsagent.io/zh/instructions/files/claude-md)

[GEMINI.md](https://dotsagent.io/zh/instructions/files/gemini-md)

[.cursor/rules/*.mdc](https://dotsagent.io/zh/instructions/files/cursor-rules)

[.github/copilot-instructions.md](https://dotsagent.io/zh/instructions/files/github-copilot-instructions)

[.devin/rules/*.md](https://dotsagent.io/zh/instructions/files/windsurf-rules)

[.clinerules/](https://dotsagent.io/zh/instructions/files/cline-rules)

[~/.openclaw/workspace/AGENTS.md](https://dotsagent.io/zh/instructions/files/openclaw-workspace)

## 来源

1. [agents.md](https://agents.md/)/
2. [github.com](https://github.com/agentsmd/agents.md)/agentsmd/agents.md
3. [linuxfoundation.org](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foun
4. [openai.com](https://openai.com/index/agentic-ai-foundation/)/index/agentic-ai-foundation/
5. [developers.openai.com](https://developers.openai.com/codex/guides/agents-md)/codex/guides/agents-md

为 AI agent 开发者提供的独立参考资料。与此处提及的任何厂商均无关联。

© 2026 DotsAgent · 事实核查日期：2026年10月1日