AGENTS.md Explained: The File That Makes AI Coding Agents Useful

What AGENTS.md Actually Is

AGENTS.md is a Markdown file that provides AI coding agents with project-specific instructions—build commands, code conventions, testing requirements, and hard boundaries. Think of it as a README for machines: same format, completely different audience.

OpenAI originated the spec in August 2025 for their Codex CLI. The idea was simple: agents need a predictable location to find project context, and developers need a standard way to provide it. Within months, every major AI coding tool adopted the format.

In December 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF), with AGENTS.md as one of three founding projects alongside Anthropic's MCP and Block's goose. Jim Zemlin, the Linux Foundation's Executive Director, put it plainly:

"We are seeing AI enter a new phase, as conversational systems shift to autonomous agents that can work together. Within just one year, MCP, AGENTS.md and goose have become essential tools for developers building this new class of agentic technologies."

The numbers back this up: over 60,000 open-source repositories now include an AGENTS.md file. Platinum members of AAIF include AWS, Anthropic, Google, Microsoft, and OpenAI—the companies building the agents that read this file.

Why Your README Isn't Enough

Your README tells a human developer what your project does. AGENTS.md tells an AI agent how to work in your project. The distinction matters more than you'd think.

When an AI agent opens your repo, it needs answers to very specific questions:

A README optimized for human onboarding buries these details under project descriptions, badges, and setup narratives. An AGENTS.md file leads with them.

I've seen this play out at Particula Tech repeatedly. A client's RAG pipeline had a README that explained the architecture beautifully—for humans. But when agents worked on it, they'd use the wrong Python version, skip the pre-commit hooks, and commit directly to main. Adding an AGENTS.md with 40 lines of explicit instructions eliminated all three problems in a single commit.

What GitHub Learned from 2,500+ Repos

GitHub published a detailed analysis of over 2,500 repositories with AGENTS.md files, and the findings are worth internalizing. The best-performing files share four traits:

## Role
You are a backend API agent for a FastAPI service.
You work exclusively in `src/api/` and `tests/api/`.
You never modify frontend code, infrastructure configs, or database migrations.

## Commands
- `pnpm install` — Install dependencies
- `pnpm dev` — Start dev server (port 3000)
- `pnpm test` — Run test suite
- `pnpm test:e2e` — Run Playwright E2E tests
- `pnpm lint` — Run ESLint + Prettier check
- `pnpm build` — Production build (must pass before PR)

## Code Style

Use functional components with TypeScript. Named exports only.

<!-- GOOD -->
export function UserCard({ name, role }: UserCardProps) {
  const [isExpanded, setIsExpanded] = useState(false);
  return (
    <Card onClick={() => setIsExpanded(!isExpanded)}>
      <h3>{name}</h3>
      {isExpanded && <p>{role}</p>}
    </Card>
  );
}

<!-- BAD — class component, default export, no types -->
export default class UserCard extends Component { ... }

## Boundaries

### Always Do
- Run `pnpm test` before submitting any changes
- Add TypeScript types for all new functions and interfaces
- Follow existing patterns in the file you're editing

### Ask First
- Before changing database schema or migrations
- Before adding new dependencies to package.json
- Before modifying CI/CD pipeline configuration

### Never Do
- Never commit .env files, API keys, or secrets
- Never remove or skip failing tests without explicit approval
- Never push directly to main — always use a feature branch
- Never modify files in `vendor/` or `dist/`

A Production-Ready AGENTS.md Template

Here's the template I use with clients at Particula Tech, refined across dozens of projects. If you want to learn more about making AI agents use tools correctly, this file is your starting point.

# AGENTS.md

## Project Overview
- **Stack:** Next.js 15, TypeScript 5.4, Tailwind CSS 4, PostgreSQL 16
- **Package manager:** pnpm (do NOT use npm or yarn)
- **Node version:** 22.x (see .nvmrc)
- **Monorepo:** No

## Commands
- `pnpm install` — Install all dependencies
- `pnpm dev` — Start development server on port 3000
- `pnpm build` — Production build (must pass before any PR)
- `pnpm test` — Run Vitest unit tests
- `pnpm test:e2e` — Run Playwright end-to-end tests
- `pnpm lint` — ESLint + Prettier (auto-fixable: `pnpm lint:fix`)
- `pnpm db:migrate` — Run pending database migrations
- `pnpm db:seed` — Seed development database

## Code Style
- Functional components only, no class components
- Named exports (never default exports)
- Use `const` exclusively — no `let` unless mutation is required, never `var`
- Colocate types in the same file unless shared across 3+ files
- Prefer server components; add 'use client' only when needed

## Testing
- Every new feature needs at least one test
- Unit tests go in `__tests__/` next to the source file
- E2E tests go in `e2e/`
- Run the full suite before submitting: `pnpm test && pnpm test:e2e`

## Git Workflow
- Branch naming: `feat/description`, `fix/description`, `chore/description`
- Commit messages: conventional commits (feat:, fix:, chore:, docs:)
- Always create a PR — never commit directly to main

## Boundaries

### Always Do
- Run tests before submitting
- Add types for all new exports
- Match the patterns in existing code

### Ask First
- Before adding dependencies
- Before changing database schema
- Before modifying authentication logic

### Never Do
- Never commit secrets, .env files, or API keys
- Never delete failing tests without approval
- Never modify generated files in `dist/` or `.next/`

Tech stack specificity matters. "React with TypeScript" is useless. "Next.js 15 with TypeScript 5.4, Tailwind CSS 4, and pnpm" tells the agent exactly which APIs, patterns, and commands to use.

AGENTS.md vs CLAUDE.md vs .cursorrules: When to Use Each

If you're using multiple AI coding tools—and most teams are—you're probably wondering whether you need separate configuration files for each one. Here's the practical breakdown:

The 90% rule applies here: 90% of what you'd put in any of these files is identical—commands, conventions, boundaries. The remaining 10% is tool-specific features.

My recommendation for teams using multiple tools:

For more context on how these tools compare in practice, see our Cursor AI development best practices guide and the Cursor vs Claude Code comparison.

If you're only using one tool, you can start with just that tool's config file. But the moment you—or anyone on your team—tries a second tool, you'll wish you'd started with AGENTS.md.

The 25+ Tools That Read AGENTS.md

The adoption curve here has been remarkable. As of March 2026, these tools natively parse AGENTS.md:

IDE-integrated agents: GitHub Copilot, Cursor, Windsurf, Zed, Warp, VS Code (via extensions), JetBrains Junie

Standalone agents: OpenAI Codex CLI, Google Jules, Gemini CLI, Amp, Devin, Aider, goose (Block), Kilo Code, Builder.io, RooCode, Augment Code

Enterprise platforms: Factory, UiPath

Notable exception: Claude Code uses its own CLAUDE.md format. There's an open issue with 3,000+ upvotes requesting AGENTS.md support, but Anthropic hasn't committed to it. If you use Claude Code, maintain both files—or reference AGENTS.md from your CLAUDE.md.

The Linux Foundation governance makes this list likely to keep growing. With AWS, Google, Microsoft, and OpenAI as platinum members of the Agentic AI Foundation, new tools face strong incentive to support the standard rather than invent their own format.

Directory Hierarchy: Monorepo Support

AGENTS.md supports a cascading directory structure that works naturally with monorepos:

my-monorepo/
├── AGENTS.md              ← Global conventions (TypeScript, git workflow)
├── packages/
│   ├── api/
│   │   └── AGENTS.md      ← API-specific (FastAPI, pytest, DB rules)
│   ├── web/
│   │   └── AGENTS.md      ← Frontend-specific (React, Playwright)
│   └── shared/
│       └── AGENTS.md      ← Library rules (no side effects, 100% test coverage)

The rules are simple:

Real-World Impact: What Changes After Adding AGENTS.md

I've now helped over a dozen teams add AGENTS.md to their repositories. The changes are consistent and immediate:

Fewer correction cycles. Before AGENTS.md, teams averaged 3–4 rounds of "no, use pnpm not npm" or "we use named exports here" per agent session. After: typically zero. The agent gets it right on the first pass because the instructions are unambiguous.

Safer agent operations. The boundary tier system catches the dangerous actions before they happen. One client's agent was routinely running database migrations without approval—a single "ask first" rule in AGENTS.md stopped it permanently.

Consistent output across tools. Teams using both Copilot and Cursor got different results from each because they had different config files with subtly different instructions. A shared AGENTS.md eliminated the drift.

Faster onboarding for new agents. When a team evaluates a new AI coding tool, the AGENTS.md file means it immediately understands the project. No separate configuration, no learning curve. This matters as the tool landscape keeps evolving—and for teams exploring which AI coding tools to use, it removes a real barrier to switching.

Getting Started: Three Steps

If you want to add AGENTS.md to your project today:

Step 1: Start with commands. List every command a developer (human or AI) needs to build, test, lint, and deploy. Be exact—include flags, environment variables, and prerequisites.

Step 2: Add one code example per convention. Don't describe your code style. Show it. One good example and one bad example per major pattern.

Step 3: Write your "never do" list. Think about the mistakes that would cause real damage: committing secrets, deleting tests, modifying production configs, running destructive database operations. These are your hard boundaries.

That's it. Three sections. You can expand later, but these three will handle 80% of the value immediately.

For teams working with AI agents more broadly, this file pairs well with llms.txt for AI discovery—AGENTS.md tells agents how to work in your code, while llms.txt tells AI systems what your project is about.

What's Next for AGENTS.md

The Agentic AI Foundation's first major event—MCP Dev Summit North America—is scheduled for April 2–3, 2026 in New York City. Expect governance updates and potentially new features for the spec.

The trajectory is clear: AGENTS.md is becoming the .gitignore of AI-assisted development—a file so universally expected that its absence is the exception. With 60,000+ repos already using it and every major platform supporting it, the question isn't whether to add one. It's how much time you'll waste before you do.