AGENTS.md 完整指南 2026：配置 AI 编程代理的跨工具标准

2026年5月20日

8 min read

AGENTS.md 是 OpenAI 在 2025 年 8 月推出的跨工具 AI 编程代理配置标准，目前由 Linux 基金会下的 Agentic AI Foundation 托管。一个项目里放一份，Codex、GitHub Copilot、Cursor、Windsurf、Amp、Devin 都能读。本文讲清楚它是什么、哪些工具支持、和 CLAUDE.md 怎么搭配，以及怎么写一份真正有用的。

它解决什么问题

AI 编程代理不知道你团队用 Tailwind 而不是 CSS Modules，不知道 /legacy 目录不能动，不知道提交前要跑测试。AGENTS.md 是放在仓库根目录的一份 markdown 文件，把这些约束告诉所有 AI 工具。最小示例：

# 项目：我的 SaaS

## 技术栈
- Next.js 15（App Router）、TypeScript 严格模式、Tailwind CSS
- 数据库：Postgres，通过 Prisma 访问
- 鉴权：NextAuth.js v5

## 约定
- 用具名导出，禁止默认导出
- 所有 API 路由放 /app/api/
- 测试用 Vitest，不用 Jest
- 永远不要修改 /legacy/ 目录，那块代码已冻结

## 提交前
- 跑 `npm run lint && npm run test`
- PR 描述控制在 3 句话以内

没有特殊语法、没有 schema 要学，就是 markdown。

支持的工具一览

工具	是否读 AGENTS.md	备用文件	子目录支持
OpenAI Codex CLI	主文件	AGENTS.override.md	支持
GitHub Copilot	支持	.github/copilot-instructions.md	支持
Cursor	支持	.cursor/rules/*.mdc	支持
Windsurf	支持	.windsurfrules	支持
Amp（Sourcegraph）	支持	回退到 CLAUDE.md	支持
Devin	支持	–	支持
Claude Code	暂不支持	CLAUDE.md	支持（CLAUDE.md）
Gemini CLI	未确认	GEMINI.md	支持（GEMINI.md）
字节 TRAE、通义灵码	部分支持	各自的配置	视版本

跨工具标准基本确立，只有 Claude Code 是例外，要在 CLAUDE.md 里手动引用 AGENTS.md 作为变通。

AGENTS.md vs CLAUDE.md vs .cursorrules

什么时候用哪个？

用 AGENTS.md：团队同时用多个 AI 工具、做开源项目、想要工具无关的项目说明。

用工具专属文件：需要配置工具特有功能（Claude Code 的权限边界、Cursor 的 glob 范围）、团队统一一个工具。

两个都用：把共享约定放 AGENTS.md，工具专属配置放原生文件。最常见的设置：

project/
├── AGENTS.md              # 共享：技术栈、约定、边界
├── CLAUDE.md              # Claude Code 专属
├── .cursor/rules/         # Cursor 专属
└── .github/
    └── copilot-instructions.md  # Copilot 专属

怎么写一份有效的

我看过的 AGENTS.md 文件多数要么太空（「写好代码」）要么太长（贴整本规范）。真正起作用的几个原则：

先写技术栈。让 AI 不用猜框架版本。

## 技术栈
- Python 3.12、FastAPI 0.115、SQLAlchemy 2.0（async）
- PostgreSQL 16、Redis 缓存
- 前端：React 19 + Vite、Tailwind CSS v4
- 测试：pytest + pytest-asyncio

写边界而不是偏好。「优先用函数组件」是建议，「禁止直接改 /migrations/，用 Alembic 生成」是边界，能真正避免事故。

用示例展示约定。与其说「按命名规范来」，不如直接放代码：

@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    user = await user_service.get_by_id(db, user_id)
    if not user:
        raise HTTPException(404, "User not found")
    return UserResponse.model_validate(user)

加验证步骤。告诉 AI 怎么自检：

## 完成前
1. `make lint` 必须零警告通过
2. `make test` 全部通过
3. 新增 API 必须在 /docs/api-reference.md 登记

控制在 500 行内。每行指令都在和实际代码抢上下文窗口。规则太多就拆到子目录的 AGENTS.md。

多 Agent 与 Monorepo

跑多个 Agent 并行时（前端一个、后端一个），子目录的 AGENTS.md 防止它们相互踩。

project/
├── AGENTS.md                # 共享：Git 约定、CI 检查
├── frontend/
│   └── AGENTS.md            # 「你只管 UI，不要碰 /backend」
├── backend/
│   └── AGENTS.md            # 「你只管 API，不要碰 /frontend」
└── infra/
    └── AGENTS.md            # 「你只管 Terraform，apply 前要审批」

常见错误

把整本编码规范贴进去：抽 10 条关键的就行，详细文档单独链
太空泛：「遵循最佳实践」等于没说，要具体到「SQL 参数化查询，禁止字符串拼接」
不更新：写着用 Jest 但已经迁到 Vitest，Agent 一直生成错误代码
工具专属内容混进去：跨工具的放 AGENTS.md，工具专属的放原生文件

现在就开始

掘金、V2EX 上已经有不少国内项目放出自己的 AGENTS.md 模板，搜「AGENTS.md 中文模板」就能找到。在你下个项目的根目录建一个，30 分钟写完，立刻能感觉到 AI 输出质量的提升。