AGENTS.md: One File to Steer Every AI Coding Agent

If a README explains your project to humans, AGENTS.md explains it to machines. It is a single Markdown file at the root of your repo that tells AI coding agents how to build, test, and work in your codebase — the conventions they would otherwise guess at (and get wrong).

The idea caught on fast because it solved a real annoyance: every tool was inventing its own config file. .cursorrules, .github/copilot-instructions.md, .windsurfrules, CLAUDE.md — the same information, in five places, all drifting out of sync. AGENTS.md is the convergence point.

Who actually reads it?

This is the part that makes AGENTS.md worth adopting today rather than "someday." It is read natively by a long and growing list of tools — Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed, Jules, Factory, and 20+ others — and is now stewarded by the Linux Foundation's Agentic AI Foundation. As of 2026 it ships in 60,000+ public repositories.

Practically: drop one file in your repo root and most agents your team already uses will pick it up with zero configuration.

What goes in it

There is no required schema — it is just Markdown. That is a feature, not a gap: the same file is readable by a model and by a new teammate. A good AGENTS.md answers the questions an agent asks on its first task:

• How do I run this? Dev server, build, and the canonical test command.
• What are the house rules? Language, formatting, lint, naming conventions.
• What should I not touch? Generated files, vendored code, migrations.
• How is the project laid out? The 30-second tour of the directory structure.

Here is a compact, realistic example:

# AGENTS.md

## Setup
- Install: `npm install`
- Dev server: `npm run dev`
- Run before every PR: `npm run lint && npm run typecheck && npm test`

## Conventions
- TypeScript strict mode. No `any`.
- Use `next/link` for internal navigation, never a raw anchor tag.
- Prettier is the source of truth for formatting — do not hand-format.

## Project layout
- `src/app` — Next.js App Router pages
- `src/components` — UI components
- `src/lib` — utilities and third-party clients

## Guardrails
- Never edit files in `src/data/` by hand; they are synced from another repo.
- Don't commit secrets — use environment variables.

Tips that make a measurable difference

1. Put the test command front and center. The single highest-leverage line in the file is the exact command an agent should run to check its own work. Agents that can self-verify produce dramatically fewer broken changes.

2. Write rules as imperatives, not vibes. "Use async/await, not .then() chains" beats "write clean async code." Agents follow concrete instructions far more reliably than aspirational ones.

3. Keep it short and current. A 40-line file that is true beats a 400-line file that is half-stale. Treat it like code: when a convention changes, update AGENTS.md in the same change.

4. Nest when you need to. Large monorepos can put an AGENTS.md in each package; agents read the closest one to the file they are editing.

AGENTS.md vs. tool-specific rules

You don't have to throw away your .cursorrules overnight. Most teams adopt AGENTS.md as the shared baseline and keep a thin tool-specific file only for genuinely tool-specific behavior. Over time, the shared file tends to absorb the rest.

The bottom line

AGENTS.md is the rare standard that is both trivial to adopt and immediately useful. It costs you ten minutes and one file, and it makes every agent on your team meaningfully better at its job — today, not after some migration. If you maintain an open-source project, it is also a courtesy to the growing share of contributors who show up with an agent in tow.

Browse battle-tested rules and agent configs for every major tool in the AgentDepot directory →