昨天我发布了面向企业团队的 CLAUDE.md 指南。几小时内，三个人问了同一个问题：“那并非全部押注 Claude Code 的团队呢？”
说得有理。如果您的组织一些团队使用 GitHub Copilot，另一些使用 Cursor，后台任务用 Codex，复杂重构用 Claude Code——而且这越来越普遍——您需要一种到处都能用的方案。
那就是 AGENTS.md。
AGENTS.md 是什么（以及不是什么）
AGENTS.md 是一个厂商中立的 markdown 文件，告诉 AI 编码代理如何在您的代码库中工作。它位于仓库根目录（或在子目录中用于范围限定的规则），包含与您给新开发者第一天工作的同类信息：构建命令、测试协议、编码约定、项目架构和明确边界。
与 README.md 的关键区别在于：它为机器而非人类结构化。README 可能会说"我们使用 React 配 TypeScript"，而 AGENTS.md 会说：
## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4
确切版本。没有叙述。代理不需要您的起源故事。
该格式源于一个实际问题。在 AGENTS.md 之前，每个代理都有自己的配置文件——Aider 用 CONVENTIONS.md，Roo Code 用 .roomodes 文件，Cline 用 .clinerules 目录，Claude Code 用 CLAUDE.md。运行多个代理的团队维护着冗余、分化的配置。AGENTS.md 将此统一为单一事实来源，现在已有超过 60,000 个开源项目采用。
为什么企业团队应该关注
数据说明了一切。GitHub 分析了超过 2,500 个仓库，发现代理成功率在有适当指导时会大幅提升：
- 无 AGENTS.md — 40-60% 任务成功率
- 最小化 AGENTS.md — 60-70% 成功率
- 完善的 AGENTS.md — 85-90% 成功率
对于每天早上排队五个代理任务的企业团队（WorkOS 团队用 Codex 开创的模式），这就是每天两次失败与零失败的差别。在整个组织中放大，ROI 显而易见。
但真正的企业价值不仅仅是成功率。而是跨工具的标准化。当您的前端团队用 Cursor、平台团队用 Claude Code、DevOps 团队试用 Codex 时，单一 AGENTS.md 确保它们都遵循相同约定。写一次，每个代理都读它。
各主要代理如何使用 AGENTS.md
并非所有代理都以相同方式消费 AGENTS.md。理解差异有助于您编写在各处都好用的文件。
GitHub Copilot
Copilot 从工作区根目录和子目录自动发现 AGENTS.md。GitHub 团队专门分析了那 2,500+ 个仓库以改进 Copilot 对该格式的解读。Copilot 还支持 .agent.md 文件——一种单独的格式，带 YAML frontmatter，用于定义具有特定工具和角色的自定义代理角色。
Cursor
Cursor 自动发现 AGENTS.md 并将其馈送到指令系统中。无需配置——将文件放入仓库，Cursor 就会拾取它。简单有效。
Windsurf
Windsurf 拥有最成熟的集成。它将 AGENTS.md 视为其规则引擎的一部分，带自动范围限定：根文件成为始终启用的全局规则，而子目录文件根据位置自动应用 glob 模式。Windsurf 会扫描整个工作区中的所有 AGENTS.md 文件。
Claude Code
Claude Code 在其原生 CLAUDE.md 格式之外支持 AGENTS.md。两者互补——AGENTS.md 用于通用约定，CLAUDE.md 用于 Claude 专用功能，如自动记忆、MCP 服务器声明以及我在 Claude Code 项目剖析中介绍的三层架构。
OpenAI Codex
Codex 在启动时自动发现并加载 AGENTS.md，在任务执行期间频繁引用命令。这正是 WorkOS 案例研究出彩之处——他们的团队每天早上为 Codex 排队 4-5 个维护任务（TypeScript 修复、webhook 更新、身份认证迁移），并报告在范围明确的工作上达到 85-90% 成功率。
Aider
Aider 已通过 --conventions-file 支持约定文件。AGENTS.md 成为标准默认位置，现有的 CONVENTIONS.md 文件仍可向后兼容使用。
其他
Roo Code、Google Jules、Factory.ai Droids 和 Zed 都以不同程度的成熟度支持 AGENTS.md。Factory.ai 将其作为主要简报机制，在目录间进行全面发现。趋势很明确：AGENTS.md 正成为基本要求。
每个 AGENTS.md 需要的六样东西
GitHub 对 2,500+ 仓库的分析确定了六个核心领域，它们带来最大差异：
1. 可执行命令
把这些放在最前面。代理会不断调用它们。
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test single: `pnpm test -- --grep "test name"`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`
2. 测试说明
不仅仅是如何运行测试，还有如何编写测试。用什么框架、什么模式、放在哪里。
## Testing
- Framework: Vitest with React Testing Library
- Location: `__tests__/` directories adjacent to source
- Pattern: one test file per component, named `ComponentName.test.tsx`
- Run single file: `pnpm test src/components/__tests__/Button.test.tsx`
3. 项目架构
带简要注释的文件结构。代理用它在陌生代码库中导航。
## Architecture
- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `src/shared/` — Shared types and utilities
- `infra/` — Terraform modules and Bicep templates
- `scripts/` — CI/CD and automation scripts
4. 代码风格（带示例）
抽象规则不落地。具体示例才落地。
## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Example:
```tsx
export function UserCard({ name, role }: UserCardProps) {
const [expanded, setExpanded] = useState(false);
return (
<Card onClick={() => setExpanded(!expanded)}>
<h3>{name}</h3>
{expanded && <p>{role}</p>}
</Card>
);
}
```
5. Git 工作流
提交标准、分支约定、PR 要求。
## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks
6. 明确边界
三层约束结构对企业团队至关重要：
## Boundaries
**Always do:**
- Include unit tests for new functions
- Run lint before committing
- Use environment variables for configuration
**Ask first:**
- Database schema changes
- Adding new dependencies
- Modifying CI/CD pipelines
- Changes to authentication or authorization logic
**Never do:**
- Commit secrets, API keys, or connection strings
- Modify files in `vendor/` or `node_modules/`
- Edit generated migration files
- Push directly to main branch
- Modify `.env.production`
Monorepo 模式
这是 AGENTS.md 对企业团队变得有趣的地方。该格式支持分层嵌套——子目录文件继承并覆盖父文件，最近的文件优先。
/AGENTS.md ← 全局：安全规则、提交约定
/frontend/AGENTS.md ← React 模式、CSS 约定、组件规则
/frontend/components/AGENTS.md ← 组件库细节
/backend/AGENTS.md ← API 模式、数据库规则、服务约定
/infra/AGENTS.md ← Terraform/Bicep 规则、命名约定
OpenAI 在其仓库中维护着大约 88 个嵌套的 AGENTS.md 文件。这不算过分——而是精确。每个团队拥有其子目录的代理指导，全局规则从根目录向下级联。
对于企业团队，这自然映射到团队所有权。平台团队拥有根级规则。前端、后端和基础设施团队拥有各自子目录的文件。变更像代码一样通过拉取请求进行。
AGENTS.md、CLAUDE.md 和 SKILL.md — 如何组合
如果您在使用 Claude Code（如果您读了我们的 CLAUDE.md 指南，很可能在用），您可能想知道这些文件如何关联。以下是思维模型：
AGENTS.md — “如何在此代码库中工作。“厂商中立。每个代理都读。包含命令、架构、约定和边界。
CLAUDE.md — “Claude 在这里具体应如何工作。“仅限 Claude Code。添加自动记忆、MCP 服务器声明、hook 配置和 Claude 专用优化。
SKILL.md — “如何执行此类任务。“可重用的专业知识包——不是代码库特定，而是任务特定。我在关于 Claude Code 和 Gemini CLI 技能工具的文章中介绍了技能创建工作流。
把它想成一个堆栈：
- 系统提示 — 模型基线（您不控制这个）
- AGENTS.md — 代码库上下文（通用）
- SKILL.md — 任务专业知识（按需）
- CLAUDE.md / .agent.md — 代理专用配置（按工具）
- MCP 服务器 — 外部系统访问（实时数据）
对于多代理团队，将大部分精力投入到 AGENTS.md。它覆盖面最广。然后为代理专用优化叠加 CLAUDE.md 或 .agent.md 文件。
企业入门模板
以下是一个即用即贴的企业团队模板。自定义具体内容，保留结构：
# AGENTS.md
## Project Overview
[One sentence: what this system does and who it serves]
## Tech Stack
- [Language] [version], [Framework] [version], [Build tool] [version]
- Database: [system] [version]
- Infrastructure: [platform] (Terraform/Bicep/CDK)
- CI/CD: [platform]
## Commands
- Install: `[command]`
- Dev: `[command]`
- Build: `[command]`
- Test all: `[command]`
- Test single: `[command] [path]`
- Lint: `[command]`
- Format: `[command]`
## Architecture
- `src/` — Application source code
- `src/api/` — [description]
- `src/web/` — [description]
- `src/shared/` — [description]
- `infra/` — Infrastructure as code
- `tests/` — Integration and E2E tests
- `scripts/` — Automation and CI/CD
- `docs/` — Architecture decisions and runbooks
## Code Style
- [2-3 concrete rules with examples]
- Example:
```[language]
// Preferred pattern
[code example]
```
## Testing
- Framework: [name]
- Location: [pattern]
- Naming: [convention]
- Coverage: [minimum threshold if any]
## Git Conventions
- Commits: [format]
- Branches: [naming pattern]
- PRs: [requirements]
## Boundaries
**Always do:**
- [list critical always-do items]
**Ask first:**
- [list items requiring human approval]
**Never do:**
- [list absolute prohibitions]
15 分钟入门
您不需要第一天就有完美的 AGENTS.md。从最小化开始并迭代。
步骤 1（5 分钟）： 在仓库根目录创建 AGENTS.md。添加构建、测试和 lint 命令。这些影响最立竿见影。
步骤 2（5 分钟）： 添加带确切版本的技术栈和简要架构部分，列出目录结构。
步骤 3（5 分钟）： 添加边界部分。从"绝不做"开始——如果代理做了会造成真正损害的事情。为需要人工判断的事项添加"先询问”。
步骤 4（持续进行）： 每次代理犯错，就添加一条规则。这是每个成功团队遵循的有机增长模式。您的 AGENTS.md 成为经验教训的活记录。
专业提示： 有一个社区维护的提示，让 AI 代理扫描您现有的仓库——包文件、CI/CD 工作流、贡献指南、git 历史——并自动生成一个起始 AGENTS.md。这是现有项目最快的引导方式。
多代理现实
这就是为什么此事现在重要的原因。AI CLI 大战意味着您的团队可能已经在使用多个代理，无论您是否批准。开发者选择最适合手头任务的工具——Cursor 用于交互式编辑，Claude Code 用于复杂重构，Codex 用于后台任务队列。
没有 AGENTS.md，每个开发者独立配置每个代理。约定漂移。质量参差。同样的错误在代码库不同部分被不同代理重复犯下。
有了 AGENTS.md，您一次性定义标准。每个代理、每个开发者、每次会话都从同一基线开始。这就是企业价值主张：不是选择一个代理，而是让所有代理一致地工作。
资源
- 官方 AGENTS.md 规范和示例
- GitHub 博客：如何写好 agents.md — 来自 2,500+ 仓库的经验
- Windsurf AGENTS.md 文档
- agentsmd.net 模板 — 按技术栈分类的 14 个生产就绪模板
让您的多代理策略正确
AGENTS.md 是基础，但它只是更广泛 AI 编码策略的一部分。它如何与您的 CLAUDE.md 文件配合？您的 MCP 服务器基础设施？您的治理要求？您的团队实际工作流？
Big Hat Group 帮助企业团队构建连贯的 AI 代理策略——不仅仅是配置文件，而是完整堆栈：代理配置、技能开发、安全边界，以及让合规团队放心的治理框架。我们已在同时运行 Copilot、Claude Code 和 Codex 的组织中部署这些模式。
如果您的团队正在兼顾多个 AI 编码代理并需要统一方法，联系我们。
Kevin Kaminski 是 Microsoft MVP，也是 Big Hat Group 的负责人，他在那里帮助企业团队部署 AI 代理、Windows 365 和现代管理解决方案。