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

AGENTS.md is a simple, open source format that was put together by OpenAI and others. It is designed to provide guidance for AI programming agents, and functions similarly to the AI-specific readingREADME.mdDocumentation. In a software project, theREADME.mdDocumentation is usually written for human developers and covers things like project descriptions, how to get started, and contribution guidelines. WhileAGENTS.mdInstead, it focuses on providing the more specific, technical instructions that AI intelligences need to understand and participate in a project, such as detailed build steps, test commands, and codebase-specific specifications. By separating these instructions dedicated to the AI into a specializedAGENTS.mdfile, it is possible to have theREADME.mdKeep it simple while providing a clear, predictable source of instructions for AI intelligences to help them perform coding tasks more efficiently and accurately.

Function List

• Provide clear instructions: As a file designed specifically for AI intelligences, it provides a centralized and well-defined location for all the instructions and context that the AI needs to follow when processing code.
• Streamline Project Documentation: Remove AI-specific technical instructions (e.g., build, test details) from the mainREADME.mdfile is separated out, making theREADME.mdCan focus more on providing core information to human developers.
• Standardized format:: As an open format.AGENTS.mdUsing standard Markdown syntax, there are no mandatory field requirements, developers can freely organize content according to project needs.
• Support for complex projects: In large monorepo repositories, it is permissible to place separate sub-projects inside theAGENTS.mdFiles. The Intelligent Society will automatically read the one closest to the current working directory, thus enabling fine-grained guidance for different modules.
• ecosystem-compatible: This format is designed to be compatible with the growing ecosystem of AI programming tools, including a wide range of AI programming intelligences from OpenAI, Google, and others.

Using Help

AGENTS.mdThe documentation is intended to be an "instruction manual" for AI programming intelligences to understand and manipulate the code base. It helps AIs efficiently accomplish tasks from environment setup to code submission by providing clear instructions. Below is a detailed description of how to use it and how to operate it.

Step 1: Create the AGENTS.md file

In the root directory of your codebase, manually create a file namedAGENTS.mdThe file. This file is where the AI intelligences look for instructions. Most AI programming intelligences are designed to automatically recognize and read this file.

Step 2: Write Core Content

AGENTS.mdUsing the standard Markdown format, you can create headings and lists just like you would write a regular document. Content should focus on providing clear, actionable steps for AI. Here are some suggestions of the key sections to cover:

1. Dev environment tips
This section tells AI how to prepare a local development environment, especially for projects that use a specific package manager.

• 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
This section instructs the AI on how to run tests to ensure that the code it generates meets the project's quality standards.The AI attempts to execute these commands and corrects the code based on the test results.

• 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. Pull request instructions (PR instructions)
If you want AI submissions to conform to team specifications, you can explicitly state that here.

• sample code (computing)::

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

Step 3: Special configurations for large projects

If your project is a single codebase (monorepo) containing multiple independent subprojects or packages, you can place aAGENTS.mdDocumentation.

• Working Principle: When an AI intelligence is working in a subdirectory, it will prioritize reading the nearestAGENTS.mdfile. This means that the root directory'sAGENTS.mdGlobal commands can be provided, and each subproject'sAGENTS.mdThen more specific instructions exclusive to that module can be provided.
• typical example:: It is assumed that the project is structured as follows:

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

  When the AI is in/packages/frontenddirectory, it will follow theAGENTS.mdinstructions in the file.

Step 4: Continuous updating

AGENTS.mdIt should be treated as a dynamic "living document". When your project's build process, test commands, or coding specifications change, remember to synchronize and update this document to ensure that AI intelligences always have the most accurate instructions.

application scenario

1. New Project Launch and AI Collaboration
   When a new project is started, it is possible to create from the very beginning aAGENTS.mdDocumentation. The file can define the project's technology stack, environment construction commands, code style and testing process. In this way, subsequent AI programming intelligences involved in the project can immediately "read and understand" the project specifications and directly start to complete the coding task, ensuring the standardization and consistency of the initial code base.
2. Maintenance of large single code base (Monorepo)
   In large codebases containing multiple front-end applications, back-end services, and shared libraries, different modules often have different build and test commands. By placing an exclusiveAGENTS.mdfile that can provide the AI intelligence with precise contextual guidance on which specific commands it should run when modifying a particular module, avoiding confusion and errors.
3. Automated Code Refactoring and Migration
   When large-scale code refactoring is required, such as upgrading a framework version or replacing deprecated libraries, detailed steps and rules to be aware of can be written into theAGENTS.mdAI intelligences can systematically modify the entire code base based on this "action manual" and execute specified test commands to verify the correctness of each step, greatly improving refactoring efficiency.

QA

1. AGENTS.md Are there mandatory fields in the document?
   No.AGENTS.md The standard Markdown format is used and it is very flexible. You can use whatever headings and content you see fit, and the AI intelligence will parse the text you provide and follow the instructions in it.
2. If the user's chat prompt is not the same as the AGENTS.md What happens when the instructions in the
   The user's explicit chat prompt (prompt) has the highest priority and will override all instructions in the file. In the absence of direct user instructions, the AI follows theAGENTS.mdrules. For nested files, the closest file to the current edited fileAGENTS.mdThe instructions in the will take effect.
3. AI Intelligence will automatically execute AGENTS.md the test commands listed in the
   Yes, if you list test commands in the file. the AI intelligences will try to perform relevant programmatic checks (e.g., unit tests, type checks, etc.) before completing the task and fixing the code based on the results of the failed tests.
4. AGENTS.md Can a file be modified after it is created?
   Sure. You should putAGENTS.mdThink of it as a "living document" that is dynamically updated. As the project evolves, the document is updated to ensure that it accurately reflects the current status and specifications of the project.