AGENTS.md: an open-format file providing guidance for AI-programmed intelligences

AGENTS.md 是一个由OpenAI等机构共同推出的一个简单、开放的开源格式。 它的设计目标是为AI编程智能体（coding agents）提供指导，功能类似于专为AI阅读的README.md文件。 在软件项目中，README.md文件通常是写给人类开发者看的，内容包括项目介绍、如何开始以及贡献指南等。 而AGENTS.md则专注于提供AI智能体在理解和参与项目时所需要的、更具体的技术性指令，例如详细的构建步骤、测试命令和代码库特有的规范。通过将这些专门给AI的指令分离到一个专门的AGENTS.md文件中，可以让README.md保持简洁，同时为AI智能体提供一个清晰、可预测的指令来源，帮助它们更高效、准确地完成编码任务。

Function List

• 提供明确指令: 作为一个专为AI智能体设计的文件，它提供了一个集中且明确的位置，用于存放所有AI在处理代码时需要遵循的指令和上下文。
• 简化项目文档: 将AI专用的技术指令（如构建、测试细节）从主README.md文件中分离出来，使得README.md能更专注于为人类开发者提供核心信息。
• 标准化格式: 作为一个开放格式，AGENTS.md采用标准的Markdown语法，没有强制性的字段要求，开发者可以根据项目需求自由组织内容。
• 支持复杂项目: 在大型的单一代码库（monorepo）中，允许在不同的子项目内部分别放置AGENTS.md文件。智能体会自动读取距离当前工作目录最近的那个文件，从而实现对不同模块的精细化指导。
• 生态系统兼容: 这种格式设计上兼容不断增长的AI编程工具生态，包括来自OpenAI、Google等公司的多种AI编程智能体。

Using Help

AGENTS.md文件旨在成为AI编程智能体理解和操作代码库的“说明书”。它通过提供清晰的指令，帮助AI高效地完成从环境设置到代码提交的各项任务。以下是详细的使用方法和操作流程。

第一步：创建AGENTS.md文件

在你的代码库的根目录下，手动创建一个名为AGENTS.md的文件。这个文件就是AI智能体寻找指令的地方。大多数AI编程智能体被设计为会自动识别并读取这个文件。

第二步：撰写核心内容

AGENTS.md使用标准的Markdown格式，你可以像写普通文档一样创建标题和列表。内容应专注于为AI提供清晰、可执行的步骤。以下是一些建议涵盖的关键部分：

1. 开发环境设置 (Dev environment tips)
这部分告诉AI如何准备本地开发环境，特别是对于使用特定包管理器的项目。

• sample code (computing)::

  # AGENTS.md 示例
  ## 开发环境提示
  - 使用 `pnpm dlx turbo run where <project_name>` 命令跳转到特定包的目录，而不是用 `ls` 扫描。
  - 运行 `pnpm install --filter <project_name>` 为工作区添加依赖，确保Vite、ESLint和TypeScript能够识别它。
  - 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 快速创建一个包含TypeScript配置的React + Vite新包。
  - 检查每个包内 `package.json` 文件中的 `name` 字段来确认包的正确名称，忽略顶层的 `package.json`。
  

2. 测试指令 (Testing instructions)
这部分指导AI如何运行测试，以确保其生成的代码符合项目质量标准。AI会尝试执行这些命令，并根据测试结果修正代码。

• sample code (computing)::

  ## 测试指令
  - CI计划文件位于 `.github/workflows` 文件夹中。
  - 运行 `pnpm turbo run test --filter <project_name>` 来执行该包定义的所有检查。
  - 在包的根目录中，可以直接调用 `pnpm test`。合并代码前必须通过所有测试。
  - 若要专注于某个特定的测试，可以添加Vitest匹配模式：`pnpm vitest run -t "<test name>"`。
  - 修复所有测试或类型错误，直到整个测试套件全部通过。
  - 修改文件或导入后，运行 `pnpm lint --filter <project_name>` 来确保ESLint和TypeScript规则仍然通过。
  - 即使没有被要求，也为你修改的代码添加或更新测试。
  

3. 拉取请求规范 (PR instructions)
如果你希望AI提交的代码符合团队规范，可以在这里明确说明。

• sample code (computing)::

  ## PR 指令
  - 标题格式: [<project_name>] <标题>
  - 在提交（commit）之前，务必运行 `pnpm lint` 和 `pnpm test`。
  

第三步：针对大型项目的特殊配置

如果你的项目是一个单一代码库（monorepo），包含多个独立的子项目或包，你可以在每个子项目的根目录下都放置一个AGENTS.mdDocumentation.

• Working Principle: 当AI智能体在某个子目录中工作时，它会优先读取离它当前位置最近的AGENTS.md文件。这意味着根目录的AGENTS.md可以提供全局指令，而每个子项目的AGENTS.md则可以提供该模块专属的、更具体的指令。
• typical example: 假设项目结构如下：

  /my-monorepo
  ├── AGENTS.md         # 全局指令
  ├── /packages
  │   ├── /frontend
  │   │   ├── AGENTS.md # 前端专用指令
  │   │   └── ...
  │   └── /backend
  │       ├── AGENTS.md # 后端专用指令
  │       └── ...
  └── ...
  

  当AI在/packages/frontend目录中修改代码时，它会遵循该目录下的AGENTS.md文件中的指令。

第四步：持续更新

AGENTS.md应该被当作一份动态的“活文档”。当你的项目构建流程、测试命令或编码规范发生变化时，记得同步更新此文件，以确保AI智能体始终拥有最准确的操作指南。

application scenario

1. 新项目启动与AI协作
   当一个新项目启动时，可以从一开始就创建一个AGENTS.md文件。文件中可以定义好项目的技术栈、环境搭建命令、代码风格和测试流程。这样，后续参与项目的AI编程智能体可以立刻“读懂”项目规范，并直接上手完成编码任务，保证了初始代码库的规范性和一致性。
2. 大型单一代码库（Monorepo）的维护
   在包含多个前端应用、后端服务和共享库的大型代码库中，不同模块往往有不同的构建和测试命令。通过在每个模块中放置一个专属的AGENTS.md文件，可以为AI智能体提供精确的上下文指导，告诉它在修改某个特定模块时应该运行哪些特定的命令，避免了混淆和错误。
3. 自动化代码重构和迁移
   当需要进行大规模的代码重构，例如升级框架版本或替换弃用的库时，可以将详细的操作步骤和需要注意的规则写入AGENTS.md。AI智能体可以依据这份“行动手册”系统性地对整个代码库进行修改，并执行指定的测试命令来验证每一步操作的正确性，极大地提升了重构效率。

QA

1. AGENTS.md 文件有必须填写的字段吗？
   没有。AGENTS.md 使用的是标准Markdown格式，它非常灵活。你可以使用任何你认为合适的标题和内容，AI智能体会解析你提供的文本并遵循其中的指令。
2. 如果用户的聊天提示与 AGENTS.md 中的指令冲突，会发生什么？
   用户的明确聊天提示（prompt）拥有最高优先级，会覆盖文件中的所有指令。在没有直接用户指令的情况下，AI会遵循AGENTS.md的规则。对于嵌套文件，离当前编辑文件最近的AGENTS.md中的指令会生效。
3. AI智能体会自动执行 AGENTS.md 中列出的测试命令吗？
   是的，如果你在文件中列出了测试命令。AI智能体在完成任务前，会尝试执行相关的程序化检查（如单元测试、类型检查等），并根据失败的测试结果来修复代码。
4. AGENTS.md 文件创建后可以修改吗？
   当然可以。你应该把AGENTS.md当作一份动态更新的“活文档”。随着项目的发展，随时更新文件内容，以确保它能准确反映项目的当前状态和规范。