AGENTS.md 规范完整指南
OpenAI · Google · Cursor · Factory 联合提案 · CLAUDE.md 兼容 · 实战案例集
为什么需要 AGENTS.md
2025 年上半年, 每个 AI 编程工具都有自己的项目记忆文件格式 — Cursor 用 .cursorrules, Claude Code 用 CLAUDE.md, Codex 用 instructions.md, Aider 用 .aider.conf.yml。开发者一旦切换工具, 项目知识就要重写一遍。2025 年 8 月, OpenAI、Google、Cursor、Factory 等团队联合发布 AGENTS.md 跨厂商标准, 让一份配置文件可以被任何兼容的 Agent 工具读取。
规范五大核心 Section
AGENTS.md 规定了 5 个标准化 section, 用 Markdown H2 标题分隔, 兼容所有 Markdown 编辑器:
Identity:Agent 身份、角色定位、响应语言
Capabilities:能力声明、工具偏好、模型版本
Tools:可用工具列表、权限范围、外部 API 配置
Memory:项目背景、约定、术语表、过往决策
Constraints:禁止行为、安全规则、合规要求
与 CLAUDE.md / .cursorrules 互操作
AGENTS.md 不是要取代现有格式, 而是作为跨工具的最大公约数。Claude Code 团队已宣布 AGENTS.md 优先, CLAUDE.md 作为 Claude Code 特定的扩展层共存。Cursor 在 1.2 版本起原生读取 AGENTS.md。Codex CLI 默认查找 AGENTS.md 后再 fallback 到 instructions.md。
工具链支持现状
CursorCursor 1.2+:原生支持, AGENTS.md 优先于 .cursorrules
Claude CodeClaude Code:同时识别 AGENTS.md 和 CLAUDE.md, 项目特化指令放后者
Codex CLICodex CLI:2026-02 起默认查找 AGENTS.md, 跨 OpenAI 全系列工具
AiderAider:0.65+ 实验性支持, 通过 --agents-md 启用
5 个常见反模式
1) 把全部历史决策塞进 Memory 让文件膨胀到 10KB+;2) Identity 节写成营销文案而非可执行指令;3) Constraints 不写具体禁止行为只写抽象原则;4) Tools 列表过时但没及时清理;5) 与 .gitignore 混用 — AGENTS.md 必须进版本控制让团队共享。
如何在国内稳定调用 Claude Code 跑 AGENTS.md
读者常问:「国内开发者用 Claude Code 跑 AGENTS.md 项目, 经常卡 API 连不上, 怎么办?」这是访问稳定性问题, 与规范本身无关。解决思路有几种:直接订阅官方(适合海外稳定网络);使用品牌 API 订阅服务(如 QCode.cc, 国内访问优化 + 统一计费 + 4 大模型一把 key);企业自建网关(开发周期长)。