AGENTS.md

AGENTS.md is a repository-level plain text file that tells AI coding agent how to behave in your codebase — what commands to run, what patterns to follow, what to avoid. It is to AI agents what CONTRIBUTING.md is to human contributors.

What It Is

Drop an AGENTS.md file (or CLAUDE.md, .cursor/rules, .github/copilot-instructions.md — each tool has a variant) into your repository root and AI agent will read it before taking any action. It persists your team's conventions into the agent's context automatically.

OpenAI contributed the AGENTS.md specification to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025. Anthropic's Claude Code uses CLAUDE.md. The Codex cloud agent reads AGENTS.md when reviewing PRs. Cursor uses .cursor/rules. The goal is convergence on a common standard.

Why It Matters

Without it, every developer re-explains the same context to every agent, every session:

• "We use pnpm, not npm"
• "Don't modify generated files in src/generated/"
• "Always run make lint before committing"
• "Our API uses snake_case, not camelCase"
• "Integration tests require a running Postgres — use Docker Compose first"

With an AGENTS.md, agent know all of this automatically. More importantly, it encodes the institutional knowledge your team has built up — making AI tools immediately useful for new joiners and external contributors.

What to Put In It

A well-structured AGENTS.md typically covers:

# AGENTS.md

## Project Overview
TypeScript monorepo using pnpm workspaces. Backend: Node/Express. Frontend: Next.js.

## Setup
Run `make dev` to start all services. Requires Docker Desktop.

## Commands
- `pnpm test` — run unit tests
- `pnpm test:e2e` — run end-to-end tests (requires running services)
- `pnpm lint` — ESLint + Prettier check
- `make build` — production build

## Code Conventions
- Use `pnpm`, never `npm` or `yarn`
- Database migrations in `db/migrations/` — never edit existing migrations
- Generated code in `src/generated/` — never edit directly, re-run `pnpm codegen`
- API routes follow REST conventions; see `docs/api-conventions.md`

## Testing Requirements
- All new features need unit tests
- Bug fixes must include a regression test
- Minimum 80% coverage on changed files

## Do Not Touch
- `package-lock.json` — we use `pnpm-lock.yaml`
- Files in `.generated/` directories
- Environment config in production (use the config service)

## PR Guidelines
- One logical change per PR
- Squash commits before merging
- Link the issue number in the PR description

Where Files Are Read

Most tools read multiple levels — the closest AGENTS.md to the changed file takes precedence:

repo/
├── AGENTS.md          ← read for all tasks
├── backend/
│   └── AGENTS.md      ← read for backend tasks, overrides root for specifics
└── frontend/
    └── AGENTS.md      ← read for frontend tasks

The Ecosystem of Rules Files

Recommended strategy: put your shared, tool-agnostic conventions in AGENTS.md (works everywhere). Add CLAUDE.md for Claude-specific features like @imports and /init. Tool-specific files (.cursor/rules/) are for advanced per-tool behaviour. There's even a CLI tool called rule-porter that converts .cursor/rules/*.mdc to the equivalent AGENTS.md, CLAUDE.md, or Copilot instructions.

Adoption at Scale

As of early 2026, AGENTS.md has been adopted by 60,000+ open-source projects (source: OpenAI AGENTS.md announcement). Anecdotally, teams report that a detailed AGENTS.md reduces agent-generated bugs and cuts new AI session setup time significantly — though rigorous, independently verified data on the magnitude of these improvements is not yet available.

The Linux Foundation AAIF

AGENTS.md, MCP, and goose are the three founding projects of the Linux Foundation's Agentic AI Foundation (AAIF), formed December 2025. The AAIF's Platinum members include:

AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI

Gold members include: Adyen, Docker, IBM, JetBrains, Salesforce, SAP, Shopify, Snowflake, Temporal, Twilio, and more.

Silver members include: Hugging Face, Uber, Zapier, Zed, Pydantic, LanceDB, and more.

This membership list is a strong signal that AGENTS.md is not a niche convention — it has the backing of the companies that define the industry.

Key Characteristics