AGENTS.md 格式规范

Overview

AGENTS.md 是面向 AI 编程代理的开放格式标准，被描述为”面向代理的 README”。已有超 6 万个开源项目采用，由 Linux 基金会下的 Agentic AI Foundation 托管。本文梳理其格式规范和实践要点。

为什么重要

AGENTS.md 是 Agent 时代的 README——它告诉 AI 编程代理”这个项目是什么、怎么改、不能动什么”。6 万 + 项目采用、Linux 基金会托管，已经成事实标准。任何想让 Claude Code / Codex / Cursor 等 AI 接力顺利运转的项目都需要写一份合规的 AGENTS.md，否则 AI 每次都要重新摸索项目结构，效率衰减、错误增加。

核心理念：地图，而非手册

第一原则是渐进式披露——AGENTS.md 应是一张约 200 行的导航地图，告诉 Agent”去哪里找什么”。

写进去的内容

• AI 理解项目全貌的必要信息（技术栈、仓库结构、核心模块）
• 违反会直接导致问题的硬性规则（编码规约、命名约定、禁止项）

不写进去的内容

详细内容通过链接指向 docs/ 下的专题文档。判断标准：AI 不知道会写出错误代码的放 AGENTS.md，只会写出不够好代码的放详细文档并给链接。

格式规范

标准 Markdown，无必填字段。基础建议章节：Setup commands（构建、运行、测试）、Code style（格式规范）。

兼容工具

OpenAI Codex、Google Jules、Aider、Cursor、GitHub Copilot Coding Agent、Devin、JetBrains Junie、Windsurf 等 20+ 工具。

使用方法

1. 在仓库根目录创建 AGENTS.md
2. 涵盖关键内容：项目概述、构建与测试命令、代码风格指南
3. 添加额外指令：提交信息规范、安全注意事项
4. 大型 monorepo 使用嵌套文件，代理自动读取最近的文件

冲突解决

离被编辑文件最近的 AGENTS.md 优先；用户对话框中的明确指令覆盖一切。

五大实践（来自徐靖峰）

1. 仓库聚合 — monorepo 解决上下文割裂
2. 统一环境配置 — 一键启动脚本
3. 验证闭环 — 改完代码不算完，跑通接口才算完
4. 自动化检查 — shell 脚本扫描规则，Makefile 统一入口
5. 参考项目引入 — git submodule 喂够上下文

See Also

• Agent 开发综合指南 — Agent 开发完整框架
• 高效表达指南 — 精简表达体系