agents.md

Brief

AGENTS.md 是一种常用格式，用来向参与项目的 AI 编码代理提供说明。
它本质上相当于面向代理的 README 文件，没有任何必填字段或强制格式要求，只需要使用 Markdown 即可，依赖的是基于大语言模型的编码代理去理解由人类撰写、供人阅读的指引内容。

典型用途包括：

• 如何在当前编码环境中使用各种工具的提示；
• 测试相关的操作说明；
• 管理提交（commits）时的推荐实践等。

虽然各种 AI 工具有很多不同的上下文工程（context engineering）方法，但 AGENTS.md 的价值在于：它为这样一个文件建立了一个简单的约定，使其可以作为整个过程的起点。

来源：技术雷达

Details

2.1 AGENTS.md 的定位与作用

1. 文件本质
   • AGENTS.md 是面向「AI 编码代理」的项目说明文件。
   • 类似人类开发者使用的 README，但目标读者是 LLM 驱动的编码代理（或协同开发的 AI 工具）。
2. 设计目标
   • 提供统一、可约定的入口文件，让 AI 工具在接入项目时，有一个清晰的起点。
   • 通过自然语言 + Markdown 的方式，减少对特定 schema、配置格式的依赖。
   • 把「人类对项目工作方式的经验和偏好」显式固化下来，让多代理、多工具共享。
3. 与其他文档的关系（类比）
   • 与 README：README 面向人类开发者，AGENTS.md 面向 AI 代理；二者可以内容互补。
   • 与配置/提示工程文件：AGENTS.md 不替代复杂的 prompt/config，而是提供一个「通俗、统一的门牌号」。

2.2 使用场景与典型内容

1. 工具使用指引
   • 说明项目中可用的工具链与调用方式，例如：
     • 构建工具（如 Make、npm scripts、Gradle 等）；
     • 代码生成/分析工具；
     • 内部脚本或 CLI 工具的入口和使用方式。
   • 明确哪些操作应由 AI 自动执行，哪些需要人类开发者介入或审批。
2. 测试与质量控制说明
   • 测试命令：如何运行单元测试、集成测试、端到端测试等。
   • 测试策略：
     • 代码变更前后需要哪些级别的测试；
     • 什么情况下需要跑全量测试或关键路径测试。
   • 质量门槛约定：
     • 测试失败时的处理准则；
     • 覆盖率或静态检查（lint、type check）的要求。
3. 提交与变更管理实践
   • Commit 规范：
     • Commit message 风格（如 Conventional Commits）；
     • 单次提交的粒度控制（避免过大/过小）。
   • 分支策略：
     • 是否采用 GitFlow、Trunk-based 等；
     • 哪些分支允许自动提交，哪些只能由人类合并。
   • Code review 约定：
     • AI 改动需要怎样的人类审核流程；
     • 哪些目录或模块必须有人类最终确认。

2.3 格式与灵活性

1. 格式要求
   • 唯一硬性要求：使用 Markdown。
   • 不规定任何必填字段、章节结构或元数据格式。
   • 依赖 AI 代理对自然语言文本的理解能力，而非结构化 schema。
2. 内容组织建议
   • 即使没有强制结构，也建议采用清晰的层次：
     • 项目简介与目标；
     • 环境与工具；
     • 开发/生成代码约定；
     • 测试与交付流程；
     • 风险与禁止事项（例如不得触碰的目录、不能自动修改的配置）。
   • 保持简洁、可维护，避免演变为过度复杂的「文档系统」。

2.4 在上下文工程中的位置

1. 多种上下文工程手段并存
   • 现代 AI 工具通常支持：
     • 系统提示（System Prompt）；
     • 工具/函数调用定义；
     • 模型配置文件；
     • 外部知识库（向量库、搜索索引）等。
   • AGENTS.md 并不与这些方法竞争，而是提供一个通用、易识别的入口。
2. AGENTS.md 的独特价值
   • 轻量约定：任何项目中只要放置一个 AGENTS.md，就为 AI 工具提供了「默认入口」。
   • 人类友好：内容是「给人写的」，也完全可以被人类开发者阅读与维护。
   • 跨工具兼容：不同 LLM、不同代理框架都能识别并利用同一份文档。

2.5 对架构与团队协作的影响

1. 面向 AI 协作者的「工程规范」载体
   • 把「团队如何与 AI 合作写代码」这一套规范沉淀在代码库中，而不是散落在口头或文档外。
   • 让 AI 在参与项目时遵循既定工程实践，降低「风格不一致」和「破坏流程」的风险。
2. 可演进的协同接口
   • 随项目演化调整：
     • 新增工具/脚本时更新 AGENTS.md；
     • 测试策略或分支策略变更时同步在此处说明。
   • 让 AGENTS.md 成为「AI 接入协议」的一部分，便于新工具、新代理直接接入。
3. 治理与审计
   • 团队可以审视 AGENTS.md 中对 AI 行为的约束和授权范围，确保符合法规、合规和安全要求。
   • 为后续引入更复杂的自动化与自治代理打基础：先通过简单约定规范行为，再逐步自动化。

2.6 建议的落地实践

1. 在每个需要 AI 参与的代码仓库根目录创建 AGENTS.md。
2. 保持内容短小可读（首版控制在 1–2 页），强调：
   • 项目背景与边界；
   • 最关键的工具使用方式；
   • 最不可违反的流程和限制。
3. 随迭代进行版本化管理：
   • 每次明显变更 AI 使用方式时更新 AGENTS.md；
   • 在变更记录中注明对 AI 行为约束的变化。
4. 将 AGENTS.md 纳入代码评审范围，确保人类与 AI 对协作规则有一致理解。