AGENTS.md 让 AI 编程助手高效协作的开放标准

摘要

AGENTS.md 是一种专为 AI 编程助手设计的开放文档格式，旨在为项目提供清晰、可预测的上下文和操作指令。它类似于 README，但专注于服务 AI 代理，帮助它们理解项目结构、开发流程和代码规范。AGENTS.md 已被超过 2 万个开源项目采用，成为连接人类开发者与 AI 编程助手的桥梁。通过将针对 AI 的详细说明与面向人的 README 分离，AGENTS.md 让项目文档更简洁，同时为 AI 代理提供所需的全部信息，提升协作效率和自动化能力。

内容框架与概述

AGENTS.md 的核心定位是"为 AI 代理服务的 README"，它为 AI 编程助手提供专属的、结构化的指令和上下文信息。传统的 README.md 文件主要面向人类开发者，内容包括项目简介、快速上手、贡献指南等。而 AGENTS.md 则补充了 AI 代理所需的额外细节，如构建步骤、测试流程、代码规范等，这些内容往往会让 README 变得冗长或对人类贡献者不够友好。

通过将 AI 相关说明单独放在 AGENTS.md 文件中，项目文档可以保持简洁，且 AI 代理能在一个固定位置获取所有必要信息。AGENTS.md 采用开放、通用的 Markdown 格式，无需专有工具或平台，任何项目都可以轻松集成和维护。该标准已被 OpenAI Codex、Amp、Jules（Google）、Cursor、Factory、RooCode 等主流 AI 编程工具支持，形成了广泛的生态兼容性。

核心概念及解读

AI 代理专属文档：AGENTS.md 的核心设计理念是将面向人类的 README 与面向 AI 代理的指令文档分离。README 专注于项目介绍、快速上手等人类开发者关心的内容，而 AGENTS.md 则提供构建、测试、代码风格等 AI 编程助手需要的详细操作指令。

结构化指令体系：AGENTS.md 通常包含项目概览、构建与测试命令、代码风格指南、测试说明、PR 说明等模块。这些内容完全自定义，无强制字段，开发者可根据项目需求灵活组织。对于大型 monorepo 项目，还可在每个子包目录下单独添加 AGENTS.md，实现分层、定制化的指令分发。

开放标准生态：AGENTS.md 已被超过 2 万个开源项目采用，支持包括 Rust、Python、Java、C++ 等多种编程语言。主流 AI 编程工具如 OpenAI Codex、Cursor、Google Jules 等均已集成对该标准的支持，使得项目只需维护一份 AGENTS.md 文件，即可兼容多种 AI 编程助手。

指令优先级机制：当存在多个 AGENTS.md 文件时，AI 代理会优先读取距离目标文件最近的 AGENTS.md。指令优先级为：最近的 AGENTS.md > 全局 AGENTS.md > 用户聊天指令。这种机制确保了大型项目中不同模块可以拥有定制化的操作指令。

活文档与低门槛迁移：AGENTS.md 是可随时更新的"活文档"，能够随着项目演进不断调整。迁移现有项目非常简单，只需将现有 AI 相关文档重命名为 AGENTS.md，或创建符号链接指向现有文档，无需复杂的重构工作。

原文信息

此文档由 AI 自动整理