Yesterday I published our CLAUDE.md guide for enterprise teams. Within hours, three people asked the same question: “What about teams that aren’t all-in on Claude Code?”

Fair point. If your organization uses GitHub Copilot for some teams, Cursor for others, Codex for background tasks, and Claude Code for complex refactors — and that’s increasingly common — you need something that works everywhere.

That’s AGENTS.md.

What AGENTS.md Is (and Isn’t)

AGENTS.md is a vendor-neutral markdown file that tells AI coding agents how to work in your codebase. It sits at the root of your repository (or in subdirectories for scoped rules) and contains the same kind of information you’d give a new developer on day one: build commands, testing protocols, coding conventions, project architecture, and explicit boundaries.

The key difference from README.md: it’s structured for machines, not humans. Where a README might say “we use React with TypeScript,” an AGENTS.md says:

## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4

Exact versions. No narrative. Agents don’t need your origin story.

The format emerged from a practical problem. Before AGENTS.md, every agent had its own config file — Aider used CONVENTIONS.md, Roo Code used .roomodes files, Cline used .clinerules directories, and Claude Code used CLAUDE.md. Teams running multiple agents maintained redundant, divergent configuration. AGENTS.md unifies this into a single source of truth that over 60,000 open-source projects have now adopted.

Why Enterprise Teams Should Care

The numbers tell the story. GitHub analyzed over 2,500 repositories and found that agent success rates jump dramatically with proper guidance:

  • No AGENTS.md — 40-60% task success rate
  • Minimal AGENTS.md — 60-70% success rate
  • Comprehensive AGENTS.md — 85-90% success rate

For an enterprise team queuing five agent tasks a morning (a pattern the WorkOS team pioneered with Codex), that’s the difference between two failures per day and zero. Multiply across your organization and the ROI becomes obvious.

But the real enterprise value isn’t just success rates. It’s standardization across tooling. When your frontend team uses Cursor, your platform team uses Claude Code, and your DevOps team experiments with Codex, a single AGENTS.md ensures they all follow the same conventions. Write it once, every agent reads it.

How Each Major Agent Uses AGENTS.md

Not all agents consume AGENTS.md identically. Understanding the differences helps you write files that work well everywhere.

GitHub Copilot

Copilot auto-discovers AGENTS.md from the workspace root and subdirectories. GitHub’s team analyzed those 2,500+ repos specifically to improve how Copilot interprets the format. Copilot also supports .agent.md files — a separate format with YAML frontmatter for defining custom agent personas with specific tools and roles.

Cursor

Cursor auto-discovers AGENTS.md and feeds it into its instruction system. No configuration needed — drop the file in your repo and Cursor picks it up. Simple and effective.

Windsurf

Windsurf has the most sophisticated integration. It treats AGENTS.md as part of its Rules engine with automatic scoping: a root file becomes an always-on global rule, while subdirectory files auto-apply glob patterns based on their location. Windsurf scans all AGENTS.md files across your entire workspace.

Claude Code

Claude Code supports AGENTS.md alongside its native CLAUDE.md format. The two complement each other — AGENTS.md for universal conventions, CLAUDE.md for Claude-specific features like auto-memory, MCP server declarations, and the three-layer architecture I covered in The Anatomy of a Claude Code Project.

OpenAI Codex

Codex auto-discovers and loads AGENTS.md at startup, referencing commands frequently during task execution. This is where the WorkOS case study shines — their team queues 4-5 maintenance tasks for Codex each morning (TypeScript fixes, webhook updates, auth migrations) and reports 85-90% success rates on well-scoped work.

Aider

Aider already supported convention files via --conventions-file. AGENTS.md became the standard default location, and existing CONVENTIONS.md files still work for backward compatibility.

Others

Roo Code, Google Jules, Factory.ai Droids, and Zed all support AGENTS.md with varying levels of sophistication. Factory.ai uses it as the primary briefing mechanism with comprehensive discovery across directories. The trend is clear: AGENTS.md is becoming table stakes.

The Six Things Every AGENTS.md Needs

GitHub’s analysis of 2,500+ repos identified six core areas that make the biggest difference:

1. Executable Commands

Put these first. Agents reach for them constantly.

## 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 Instructions

Not just how to run tests, but how to write them. What framework, what patterns, where they live.

## 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. Project Architecture

File structure with brief annotations. Agents use this to navigate unfamiliar codebases.

## 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 (with Examples)

Abstract rules don’t land. Concrete examples do.

## 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 Workflows

Commit standards, branch conventions, PR requirements.

## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks

6. Explicit Boundaries

The three-tier constraint structure is critical for enterprise teams:

## 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 Patterns

This is where AGENTS.md gets interesting for enterprise teams. The format supports hierarchical nesting — subdirectory files inherit from and override parent files, with the closest file taking precedence.

/AGENTS.md                          ← Global: security rules, commit conventions
/frontend/AGENTS.md                 ← React patterns, CSS conventions, component rules
/frontend/components/AGENTS.md      ← Component library specifics
/backend/AGENTS.md                  ← API patterns, database rules, service conventions
/infra/AGENTS.md                    ← Terraform/Bicep rules, naming conventions

OpenAI maintains roughly 88 nested AGENTS.md files across their repositories. That’s not excessive — it’s precise. Each team owns their subdirectory’s agent guidance, and global rules cascade down from the root.

For enterprise teams, this maps naturally to team ownership. The platform team owns root-level rules. Frontend, backend, and infrastructure teams own their respective subdirectory files. Changes go through pull requests just like code.

AGENTS.md, CLAUDE.md, and SKILL.md — How They Fit Together

If you’re using Claude Code (and if you read our CLAUDE.md guide, you probably are), you might wonder how these files relate. Here’s the mental model:

  • AGENTS.md — “How to work with this codebase.” Vendor-neutral. Read by every agent. Contains commands, architecture, conventions, and boundaries.

  • CLAUDE.md — “How Claude specifically should work here.” Claude Code only. Adds auto-memory, MCP server declarations, hook configuration, and Claude-specific optimizations.

  • SKILL.md — “How to perform this category of task.” Reusable expertise packages — not codebase-specific but task-specific. I covered the skill creation workflow in our piece on Claude Code and Gemini CLI skill tools.

Think of it as a stack:

  • System prompt — model baseline (you don’t control this)
  • AGENTS.md — codebase context (universal)
  • SKILL.md — task expertise (on-demand)
  • CLAUDE.md / .agent.md — agent-specific config (per-tool)
  • MCP servers — external system access (live data)

For multi-agent teams, invest most of your effort in AGENTS.md. It has the broadest reach. Then layer on CLAUDE.md or .agent.md files for agent-specific optimizations.

Enterprise Starter Template

Here’s a copy-paste-ready template for enterprise teams. Customize the specifics, keep the structure:

# 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]

Getting Started in 15 Minutes

You don’t need a perfect AGENTS.md on day one. Start minimal and iterate.

Step 1 (5 minutes): Create AGENTS.md at your repo root. Add your build, test, and lint commands. These have the highest immediate impact.

Step 2 (5 minutes): Add your tech stack with exact versions and a brief architecture section listing your directory structure.

Step 3 (5 minutes): Add a boundaries section. Start with “never do” — the things that would cause real damage if an agent did them. Add “ask first” items for anything that requires human judgment.

Step 4 (ongoing): Every time an agent makes a mistake, add a rule. This is the organic growth pattern that every successful team follows. Your AGENTS.md becomes a living record of lessons learned.

Pro tip: There’s a community-maintained prompt that asks an AI agent to scan your existing repo — package files, CI/CD workflows, contributing guidelines, git history — and auto-generate a starting AGENTS.md. It’s the fastest bootstrap for existing projects.

The Multi-Agent Reality

Here’s why this matters right now. The AI CLI wars mean your teams are probably already using multiple agents whether you’ve sanctioned it or not. Developers pick the tool that works best for the task at hand — Cursor for interactive editing, Claude Code for complex refactors, Codex for background task queues.

Without AGENTS.md, each developer configures each agent independently. Conventions drift. Quality varies. The same mistake gets made by different agents in different parts of the codebase.

With AGENTS.md, you define your standards once. Every agent, every developer, every session starts from the same baseline. That’s the enterprise value proposition: not choosing one agent, but making all of them work consistently.

Resources

Get Your Multi-Agent Strategy Right

AGENTS.md is the foundation, but it’s one piece of a broader AI coding strategy. How does it fit with your CLAUDE.md files? Your MCP server infrastructure? Your governance requirements? Your team’s actual workflow?

Big Hat Group helps enterprise teams build coherent AI agent strategies — not just configuration files, but the full stack: agent configuration, skill development, security boundaries, and the governance frameworks that keep compliance teams comfortable. We’ve deployed these patterns across organizations running Copilot, Claude Code, and Codex simultaneously.

If your team is juggling multiple AI coding agents and needs a unified approach, get in touch.

Kevin Kaminski is a Microsoft MVP and Principal at Big Hat Group, where he helps enterprise teams deploy AI agents, Windows 365, and modern management solutions.