How to write an AGENTS.md file so any AI coding agent understands your project

If you have ever watched an AI coding agent run the wrong test command, format code in a style your project bans, or reinvent a helper that already exists, the fix is usually not a smarter model — it is context. AGENTS.md is the standard way to give agents that context, and it works across almost every tool.

What AGENTS.md actually is

AGENTS.md is "a README for agents": a plain Markdown file you drop at the root of your repository to tell AI coding tools how your project works (agents.md). It is not a new config language — there are no required fields and no special syntax. Use any Markdown headings you like.

The format matters because it is genuinely cross-tool. As of mid-2026 it is read natively by OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie, and dozens more — 28+ tools and 60,000+ open-source repositories (agents.md; Codersera). It is now stewarded by the Linux Foundation's Agentic AI Foundation, alongside Anthropic's Model Context Protocol. Claude Code reads AGENTS.md too, though its richer native format remains CLAUDE.md (DeployHQ).

One file, and most of your tools behave consistently.

Why a file beats repeating yourself in chat

When you paste instructions into a chat message, they live for exactly one conversation. The next session — or the next teammate, or a cloud agent running your task overnight — starts from zero. An AGENTS.md is loaded automatically at the start of every run, so your conventions are enforced by default instead of depending on whether you remembered to mention them. That is the whole point: move project knowledge out of your head and out of throwaway chats, and into a file the tools read every time.

What to put in it

Think about what a competent new teammate would need on day one — that is exactly what an agent needs. The most useful sections are:

• Project overview — one paragraph on what this is and the tech stack.
• Setup and build commands — the exact commands to install, run, and build.
• Testing — how to run tests, and the rule that tests must pass before a change is done.
• Code style — formatter, linter, naming conventions, patterns to prefer or avoid.
• Commit and PR guidelines — message format, branch rules, what not to touch.
• Gotchas — anything non-obvious that trips people up.

Be concrete. "Write clean code" tells an agent nothing. "Use pnpm, not npm; run pnpm test before finishing; never edit files in src/generated/" is enforceable.

A concrete example

Here is a compact AGENTS.md for a typical web app:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Hand that to Claude Code, Cursor, or Copilot and each one will pick up the same rules.

Monorepos: use nested files

In a monorepo you can place an AGENTS.md in each package as well as one at the root. When an agent works inside a subdirectory, the closest file wins (agents.md). Keep shared conventions at the root and package-specific commands in the nested files, so an agent editing packages/api/ gets that package's build and test commands automatically.

AGENTS.md vs CLAUDE.md vs Cursor rules

You may already have tool-specific files like CLAUDE.md or .cursor/rules. You do not have to throw them away. In practice, teams put the shared, tool-agnostic conventions in AGENTS.md — the stuff every agent needs — and keep tool-specific extras in the native file for the tool that supports richer features (DeployHQ). Claude Code, for instance, reads both, with CLAUDE.md as its more expressive format. A common pattern is to keep one canonical AGENTS.md and, where a tool needs its own file, point that file at AGENTS.md so there is a single source of truth. Start with AGENTS.md; reach for the tool-specific file only when you need a feature it alone supports.

Keep it short and specific

More is not better. A giant AGENTS.md that restates your entire style guide competes for the model's attention and buries the rules that actually matter. Aim for the handful of things an agent will get wrong without guidance — the non-obvious command, the directory not to touch, the pattern your codebase prefers. If a rule is already obvious from the code, you probably do not need to write it down.

How to keep it useful

An AGENTS.md earns its keep only if it stays true. Treat it like code: when a command or convention changes, update the file in the same commit. And when an agent makes the same mistake twice, do not just correct it in chat — write the rule down. That one habit turns every misstep into a permanent fix, and it is the single highest-leverage thing you can do to make AI agents reliable on your project.