AGENTS.md 规范

README.md 文件适用于人类：快速入门、项目描述和贡献指南。

AGENTS.md 通过包含额外的、有时详细的上下文编码代理所需的内容来补充这一点：构建步骤、测试和约定，这些可能会使 README 变得混乱或与人类贡献者无关。

我们特意将其分开：

为代理提供一个清晰、可预测的指令位置。

保持 README 简洁并专注于人类贡献者。

提供精确的、以代理为中心的指导，补充现有的自述文件和文档。

我们选择了一种任何人都可以使用的名称和格式，而不是引入另一个专有文件。如果您正在构建或使用编码代理，并且觉得此方法有用，请随时采用。

一个 AGENTS.md 可以跨多个代理运行

您的代理定义与不断增长的 AI 编码代理和工具生态系统兼容：

Sample AGENTS.md file

Dev environment tips

  • Use pnpm dlx turbo run where <project_name> to jump to a package instead of scanning with ls.
  • Run pnpm install --filter <project_name> to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
  • Use pnpm create vite@latest <project_name> -- --template react-ts to spin up a new React + Vite package with TypeScript checks ready.
  • Check the name field inside each package’s package.json to confirm the right name—skip the top-level one.

Testing instructions

  • Find the CI plan in the .github/workflows folder.
  • Run pnpm turbo run test --filter <project_name> to run every check defined for that package.
  • From the package root you can just call pnpm test. The commit should pass all tests before you merge.
  • To focus on one step, add the Vitest pattern: pnpm vitest run -t "<test name>".
  • Fix any test or type errors until the whole suite is green.
  • After moving files or changing imports, run pnpm lint --filter <project_name> to be sure ESLint and TypeScript rules still pass.
  • Add or update tests for the code you change, even if nobody asked.

PR instructions

Title format: [] </li> <li>Always run <code>pnpm lint</code> and <code>pnpm test</code> before committing.</li> </ul>

法典来自 OpenAI放大器朱尔斯来自 谷歌光标工厂RooCode艾德Gemini CLI来自 谷歌千码开放代码凤凰泽德塞姆格雷普经编码剂来自 GitHub CopilotVS 代码奥娜德文来自 认知

示例

在 GitHub 上查看 2 万多个示例

如何使用 AGENTS.md？

1.添加AGENTS.md

在代码库的根目录创建一个 AGENTS.md 文件。如果你礼貌地提出请求，大多数编码代理甚至可以帮你搭建一个。

2.报道重要内容

添加有助于代理高效处理您项目的部分。热门选择：

  • 项目概述
  • 构建和测试命令
  • 代码风格指南
  • 测试说明
  • 安全注意事项

3.添加额外说明

提交消息或拉取请求指南、安全陷阱、大型数据集、部署步骤：您要告诉新队友的任何内容也都属于这里。

4.大型monorepo？对子项目使用嵌套的 AGENTS.md 文件

在每个包中放置另一个 AGENTS.md 文件。代理会自动读取目录树中最近的文件，因此最近的文件优先，并且每个子项目都可以发送定制的指令。例如，在撰写本文时，OpenAI 主仓库中有 88 个 AGENTS.md 文件。

关于

AGENTS.md 源自整个 AI 软件开发生态系统的协作努力，包括OpenAI Codex、Amp、Google 的 Jules、Cursor和Factory。

我们致力于帮助维护和发展它作为一种开放格式，使整个开发者社区受益，无论您使用哪种编码代理。

常问问题

是否有必填字段？

不是。AGENTS.md 只是标准的 Markdown 文件。你可以使用任何你喜欢的标题；代理程序只会解析你提供的文本。

如果指令发生冲突怎么办？

与编辑文件最接近的 AGENTS.md 获胜；明确的用户聊天提示将覆盖所有内容。

代理会自动运行在 AGENTS.md 中找到的测试命令吗？

是的——如果你列出它们的话。代理将在完成任务之前尝试执行相关的程序检查并修复故障。

我可以稍后更新吗？

当然。把 AGENTS.md 当作活文档。

如何将现有文档迁移到 AGENTS.md？

将现有文件重命名为 AGENTS.md 并创建符号链接以实现向后兼容：

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

如何配置 Aider？

配置 Aider 以使用 AGENTS.md .aider.conf.yml：

read: AGENTS.md

如何配置 Gemini CLI？

配置 Gemini CLI 以使用 AGENTS.md .gemini/settings.json：

{ "contextFileName": "AGENTS.md" }