AGENTS.md — One File, Every Agent

The Problem

CLAUDE.md works great — until your team has one engineer on Cursor, another on Codex, a third on Claude Code, and a fourth experimenting with Gemini CLI. Each tool reads its own context file (.cursorrules, .github/copilot-instructions.md, CLAUDE.md, GEMINI.md), so the same project ships with four near-duplicate files that drift out of sync within a sprint. New engineers don't know which one is canonical. Conventions silently diverge by tool.

AGENTS.md collapses that mess into one file every agent reads.

What It Is

A plain markdown file at the repo root. Same idea as CLAUDE.md, same style — but every major agent now reads it natively or via fallback: Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf, Devin, Factory, Aider, Zed, Warp, Jules, Amp, RooCode. If you use more than one agent in a year, AGENTS.md is the file you actually want to maintain.

OpenAI donated AGENTS.md to the Agentic AI Foundation (opens in a new tab) in December 2025, alongside Anthropic's MCP and Block's goose. It's a Linux Foundation-backed open standard, not a vendor format.

What to Include

Same discipline as CLAUDE.md — the cheat sheet for an engineer who already knows how to code. Common sections:

• Setup — install, env vars, ports, anything non-obvious to bootstrap the repo
• Build & test commands — exact commands to type-check, lint, run unit tests, run e2e
• Code style — module system, import aliases, linter rules the agent must respect
• Conventions — branch naming, commit format, PR rules, where new files go
• Anti-patterns — "never use X, always use Y" — the highest-ROI lines you'll write
• Security & secrets — what's in .env.example, what must never be committed

What to Cut

Don't paste in framework docs. Don't write "follow best practices." Don't auto-generate the file with an LLM and call it done — a March 2026 ETH Zurich study (opens in a new tab) found that LLM-generated AGENTS.md files often hurt agent performance more than they help. Write yours by hand, keep it short, and only include what the agent can't infer from the code.

Example

1# Stack
2
3- React Router v7, TypeScript strict, Tailwind CSS
4- Node >= 24.0.0, npm
5- Notion as the data store (no Prisma in production)
6
7# Commands
8
9- `npm run dev` — dev server on :3000
10- `npm run typecheck` — type check only
11- `npm run test` — Vitest
12- `npm run validate` — full check before PR
13
14# Conventions
15
16- ES modules only — no `require`
17- Use the `~/` alias for `app/`, never relative paths
18- Server-only files end in `.server.ts`
19- Form submissions go to Notion via `app/models/Lead.server.ts`
20
21# Anti-patterns
22
23- Never use `React.FC` — typed function components only
24- Never use `any` — fix the type or use `unknown`
25- Never commit `.env` — update `.env.example` instead
26- Never auto-generate this file — keep it hand-written and short
27
28# PRs
29
30- Conventional Commits: `feat(scope): …`
31- Run `npm run validate` before pushing
32- Keep diffs reviewable — split unrelated work into separate PRs

AGENTS.md and CLAUDE.md Together

You don't have to pick one. The pattern most senior teams settle on:

• AGENTS.md holds shared, tool-agnostic context — stack, commands, conventions, anti-patterns. Every agent reads it.
• CLAUDE.md holds Claude-specific instructions only — slash command preferences, plan-mode behavior, Claude Code skills your team uses. Claude Code reads both.
• Other tools fall back to AGENTS.md and ignore the rest.

If you have an existing CLAUDE.md, the migration is one move: rename the universal parts to AGENTS.md, leave a thin Claude-only CLAUDE.md (or delete it).

Why This Matters for Senior Teams

• One source of truth across agents.No more .cursorrules drift versus CLAUDE.md drift. The same conventions apply whether the next PR comes from Claude Code, Cursor, or Codex.
• Onboarding is instant.A new engineer on any agent gets the same project guardrails on day one.
• Standards survive tool churn.When a better agent ships next quarter, your context already works. No rewrite.
• Reviewable in PRs.AGENTS.md changes go through code review like any other artifact. Drift is visible.

Where It Fits in the Stack

• Pairs with Spec Kit.AGENTS.md sets the project-wide rules; /speckit.constitution adds principles per-feature. Together they cover global and local context.
• Pairs with skills.AGENTS.md tells the agent what to do; skills (figma-to-code, webapp-testing, sentry-code-review) tell it how. Reference your installed skills in AGENTS.md so any agent knows to use them.
• Pairs with worktree tooling.Each worktree inherits the same AGENTS.md, so parallel agents stay consistent.

When Not to Use It

If you only use one agent and have no plans to switch, a tool-specific file (CLAUDE.md, .cursorrules) is fine — AGENTS.md adds zero value over what you already have. The standard earns its keep when more than one agent reads the same repo, or when you expect to switch tools within the next year. For most teams in 2026, that's everyone.

Source

• AGENTS.md Open Standardagents.md (opens in a new tab)
• Linux Foundation announcement — Agentic AI Foundationlinuxfoundation.org (opens in a new tab)