AGENTS.md 被主流 AI 编程工具集体采纳，Claude Code 为何缺席

核心洞察

AGENTS.md开发规范文件，与 DESIGN.md 协同，定义“如何构建”的规则，形成完整的 AI 开发底座。 这事最有意思的地方在于，它其实是个"反标准"的标准——没什么强制力，没有 schema，就是一份 markdown，但 Codex、Copilot、Cursor、WindsurfAn AI development tool that provides code generation and analysis capabilities. 这些互相竞争的工具居然都认了。这在 AI 工具圈挺罕见的。不过 Claude Code 至今没原生支持，说明标准统一这事还早，现在入场更像是提前占坑。

---

AGENTS.md 是 OpenAI 在 2025 年 8 月推出的跨工具 AI 编程代理配置标准，目前由 Linux 基金会下的 Agentic AI Foundation 托管。一个项目里放一份，Codex、GitHub CopilotAn AI-powered code completion tool that assists developers by generating code suggestions.、Cursor、Windsurf、Amp、DevinCognition 推出的自主 AI 软件工程 Agent，可执行编程任务、审查代码并运行在云端或桌面环境中。 都能读。本文讲清楚它是什么、哪些工具支持、和 CLAUDE.mdClaude Code 专属的配置文件，用于配置 Claude Code 特有的权限边界等设置。目前 Claude Code 不直接读取 AGENTS.md，需要在 CLAUDE.md 中手动引用作为变通。 怎么搭配，以及怎么写一份真正有用的。

核心结论

1. AGENTS.md 是 OpenAI 于 2025 年 8 月推出的跨工具 AI 编程代理配置标准，目前由 Linux 基金会下的 Agentic AI Foundation 托管，采用纯 markdown 格式，无 schema、无强制力。

2. 该标准已获 Codex、GitHub Copilot、Cursor、Windsurf、Amp、Devin 等主流工具支持，但 Claude Code 至今未原生支持，需在 CLAUDE.md 中手动引用 AGENTS.md 作为变通方案。

3. AGENTS.md 的核心价值在于向 AI 代理传递项目约束（技术栈、目录边界、提交前检查），有效写法应聚焦"边界而非偏好"，例如"禁止直接改 /migrations/，用 Alembic 生成"比"优先用函数组件"更能避免事故。

4. 建议将 AGENTS.md 控制在 500 行以内，因为每行指令都在与实际代码争夺上下文窗口；规则过多时应拆分到子目录的 AGENTS.md，这在 Monorepo 多 Agent 并行场景下可防止前后端 Agent 相互干扰。

5. 最常见的四类错误包括：贴入整本编码规范、内容空泛（如"遵循最佳实践"）、长期不更新导致与实际技术栈脱节、以及将工具专属配置混入跨工具文件。

它解决什么问题

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。

支持的工具一览

跨工具标准基本确立，只有 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 输出质量的提升。

相关阅读

• AGENTS.md 标准评测：独立第三方视角的深度评测。
• Vibe Coding 进阶技巧：rules 文件之外的进阶工作流。

常见问题（FAQ）

AGENTS.md 和 CLAUDE.md 到底有什么区别，需要两个都写吗？

AGENTS.md 是跨工具标准，Codex、Copilot、Cursor 等都读；CLAUDE.md 是 Claude Code 专属，它暂不支持 AGENTS.md。常见做法是共享约定放 AGENTS.md，Claude Code 专属配置放 CLAUDE.md，并在后者里引用前者。

哪些 AI 编程工具支持 AGENTS.md？

Codex CLI、GitHub Copilot、Cursor、Windsurf、Amp、Devin 都支持，且多数支持子目录文件。Claude Code 暂不支持，Gemini CLI 未确认，字节 TRAE、通义灵码为部分支持。

AGENTS.md 怎么写才真正有效？

先写清技术栈和版本，让 AI 不用猜；多写边界而非偏好，比如禁止改 /legacy/；用代码示例展示约定；加上 lint、test 等验证步骤；全文控制在 500 行内，规则太多就拆到子目录。