AGENTS.md

一个用于指导编程助手的简单、开放的格式，已被超过60,000个开源项目使用。

为什么需要 AGENTS.md？

我们特意将其分开，目的是：

给助手一个清晰、可预测的位置来放置指令。

我们并非引入另一个专有文件，而是选择了一个对任何人都可用的名称和格式。如果你正在构建或使用编程助手，并觉得这有帮助，请随意采用它。

示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 示例 AGENTS.md 文件

## 开发环境提示
- 使用 `pnpm dlx turbo run where <项目名称>` 来跳转到某个包，而不是用 `ls` 扫描。
- 运行 `pnpm install --filter <项目名称>` 将包添加到你的工作区，以便 Vite、ESLint 和 TypeScript 能够识别它。
- 使用 `pnpm create vite@latest <项目名称> -- --template react-ts` 启动一个新的 React + Vite 包，并准备好 TypeScript 检查。
- 检查每个包的 package.json 中的 name 字段以确认正确的名称——跳过顶层的那个。

## 测试指令
- 在 .github/workflows 文件夹中找到 CI 计划。
- 运行 `pnpm turbo run test --filter <项目名称>` 来运行为该包定义的每个检查。
- 从包根目录可以直接调用 `pnpm test`。在合并前，提交应通过所有测试。
- 要专注于一个步骤，可以添加 Vitest 模式：`pnpm vitest run -t "<测试名称>"`。
- 修复所有测试或类型错误，直到整个套件全部通过。
- 移动文件或更改导入后，运行 `pnpm lint --filter <项目名称>` 以确保 ESLint 和 TypeScript 规则仍然通过。
- 为你更改的代码添加或更新测试，即使没有人要求。

## PR 指令
- 标题格式：`[<项目名称>] <标题>`
- 在提交前始终运行 `pnpm lint` 和 `pnpm test`。

如何使用 AGENTS.md？

1. 添加 AGENTS.md

在代码仓库的根目录创建一个 AGENTS.md 文件。如果你客气地请求，大多数编程助手甚至可以为你搭建一个。

2. 涵盖重要内容

添加有助于助手有效处理你的项目的部分。流行的选择包括：

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

3. 添加额外指令

提交信息或拉取请求指南、安全注意事项、大型数据集、部署步骤：任何你会告诉新队友的内容都可以放在这里。

4. 大型单体仓库？为子项目使用嵌套的 AGENTS.md 文件

在每个包内放置另一个 AGENTS.md。助手会自动读取目录树中最近的文件，因此最接近的文件优先，每个子项目都可以提供量身定制的指令。例如，在撰写本文时，主要的 OpenAI 仓库就有 88 个 AGENTS.md 文件。

关于

AGENTS.md 诞生于 AI 软件开发生态系统的协作努力，参与者包括 OpenAI Codex、Amp、谷歌的 Jules、Cursor 和 Factory。

我们致力于帮助维护和发展这个开放格式，使其惠及整个开发者社区，无论你使用哪种编程助手。

AGENTS.md 目前由 Linux 基金会旗下的 Agentic AI 基金会负责管理。了解更多 →

常见问题

有必填字段吗？

没有。AGENTS.md 只是标准的 Markdown。使用你喜欢的任何标题；助手只是解析你提供的文本。

如果指令冲突怎么办？

距离被编辑文件最近的 AGENTS.md 文件生效；明确的用户聊天提示覆盖所有内容。

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

是的——如果你列出了它们。助手会尝试执行相关的程序化检查，并在完成任务前修复失败。

我之后可以更新它吗？

当然。将 AGENTS.md 视为活的文档。

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

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

1

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

如何配置 Aider？

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

1

read: AGENTS.md

如何配置 Gemini CLI？

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

1
2
3


{
  "contextFileName": "AGENTS.md"
}