AGENTS.md

一种用于指导编码助手的简单、开放格式，已被超过6万个开源项目使用。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# AGENTS.md
## 设置命令
- 安装依赖：`pnpm install`
- 启动开发服务器：`pnpm dev`
- 运行测试：`pnpm test`

## 代码风格
- TypeScript严格模式
- 使用单引号，不加分号
- 尽可能使用函数式模式

为什么需要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

{ "contextFileName": "AGENTS.md" }