AGENTS.md explained: the new standard for AI coding agents

If you’ve been watching the AI coding tools space, you’ve probably noticed AGENTS.md showing up in more and more repositories. It’s not a Cursor thing, not a Claude Code thing, not a Copilot thing — it’s an all-of-the-above thing, and it’s quietly becoming the convention that nobody officially standardized but everyone is adopting.

Over 60,000 open-source projects have added it in the past year. Here’s what it is, why it’s gaining traction, and how to start using it today.

What is AGENTS.md?

AGENTS.md is a markdown file that lives in your repository root and provides context to AI coding agents regardless of which tool they’re using. Think of it as the universal config layer — the file you write once and every AI assistant picks up.

It exists to solve a real fragmentation problem. Claude Code reads CLAUDE.md. Cursor reads .cursor/rules. GitHub Copilot reads .github/copilot-instructions.md. Windsurf, Cline, Aider, and others each have their own conventions. If you’re using more than one tool (which most developers now are), you’re either maintaining duplicated configs or watching them slowly drift apart.

AGENTS.md sidesteps this. Many AI tools — including the Claude CLI, Windsurf, Cline, and several agentic coding tools — read AGENTS.md natively or treat it as a fallback when no tool-specific config is present.

Why AGENTS.md is spreading

The adoption curve is steep because the problem it solves is universal. AI tool fragmentation is accelerating, not slowing. New coding assistants ship monthly. Teams use different tools. Developers mix tools across work and personal projects.

The implicit standard emerged from the bottom up: developers got tired of copy-pasting the same conventions into three different config formats, and AGENTS.md became the de facto answer. It works because it’s just markdown — any tool can read it, any developer can edit it.

What goes in AGENTS.md

The content mirrors what you’d put in CLAUDE.md or a thoughtful copilot-instructions.md — because the goal is identical: give an AI assistant the context it needs to be genuinely useful in your specific project.

A solid AGENTS.md covers four things:

Project context

# Project

This is a Next.js 15 SaaS application with Supabase for auth and data,
Stripe for payments, and Resend for transactional email.

Tech stack

# Stack

- Next.js 15 with App Router
- TypeScript (strict mode)
- Tailwind CSS for styling
- Supabase (auth + database)
- Drizzle ORM
- Vitest for unit tests, Playwright for e2e

Conventions

# Conventions

- Server components by default; 'use client' only when interaction requires it
- All server actions go in `app/actions/`
- Use Zod for all API input validation
- Error handling required for every async operation
- Named exports only — no default exports
- Keep functions under 30 lines

Commands

# Commands

- `pnpm dev` — start development server
- `pnpm test` — run Vitest unit tests
- `pnpm test:e2e` — run Playwright end-to-end tests
- `pnpm db:push` — push schema changes to Supabase
- `pnpm lint` — ESLint with auto-fix

# Do not

- Use `any` type — use `unknown` and narrow with type guards
- Create barrel files (index.ts re-exports)
- Query the database directly in components — use server actions
- Commit .env files

AGENTS.md vs the platform-specific configs

These files aren’t mutually exclusive — they serve related but slightly different purposes.

File	Who reads it	Best for
`AGENTS.md`	Claude CLI, Windsurf, Cline, many others	Universal project context
`CLAUDE.md`	Claude Code (IDE extension)	Claude-specific hooks, tool permissions
`.cursor/rules/*.mdc`	Cursor	Glob-targeted, file-specific rules
`.github/copilot-instructions.md`	GitHub Copilot	Copilot workspace instructions

The pattern emerging in well-configured repos: use AGENTS.md as the shared foundation, then layer tool-specific files on top for platform-specific customization.

Your CLAUDE.md might reference AGENTS.md for the core project context, then add Claude-specific configuration (which tools Claude can use, which hooks to run). Your cursor rules might add MDC-format targeting on top of the shared conventions. You’re not replacing the tool-specific files — you’re giving all of them a common base to build from.

How to set up AGENTS.md

Step 1: Create the file

touch AGENTS.md

Step 2: Add your project context

Use the structure above as your starting point. Focus on what makes your project different from every other project — your specific stack, naming conventions, architectural patterns, and common anti-patterns.

Don’t document what the AI already knows (TypeScript syntax, React patterns). Document what it can’t know without you telling it: your folder structure decisions, your preferred error handling style, your state management approach.

Step 3: Commit it

AGENTS.md belongs in version control alongside your code:

git add AGENTS.md
git commit -m "add AGENTS.md for AI agent context"

Now every developer on your team — and every AI tool they use — gets the same project context automatically.

Step 4: Layer platform-specific configs

Add CLAUDE.md for Claude Code-specific behavior (hooks, tool permissions, memory). Add .cursor/rules for Cursor-specific rule targeting. These should extend your AGENTS.md context, not duplicate it.

Keeping AGENTS.md in sync

The hard part isn’t writing one AGENTS.md — it’s keeping it consistent with your tool-specific configs as your project evolves.

This is where spaget helps. Instead of maintaining AGENTS.md, CLAUDE.md, .cursor/rules, and copilot-instructions.md as four separate files that drift apart, you build your agent configuration once in the visual builder and export to all formats simultaneously.

Change a convention in spaget, re-export, and every config file updates. No drift, no copy-paste, no “wait, which one is the source of truth?”

No account required — open the builder and see what a synchronized multi-platform export looks like.

The bottom line

AGENTS.md is the closest thing the AI coding ecosystem has to a universal standard right now. It’s not official, it has no spec committee — but 60,000+ projects have adopted it because it solves an obvious problem elegantly.

Set it up in your next project. Write the context once. Let every AI tool benefit from it.