How to Write a Great AGENTS.md (With a Real Example)

TL;DR

AGENTS.md is a plain-markdown file at the root of your repo that tells AI coding agents — Claude Code, Cursor, Copilot — how to work in your project. A great one is thin (~30–60 lines), specific (real commands and paths, not generic advice), and constraint-first (the "don't do this" rules matter more than the "do this" ones). Below: the anatomy, a real example, the five rules, and the common mistakes. Want to skip the writing? The free AGENTS.md generator builds one from a form.

What AGENTS.md is (in one paragraph)

When an AI coding agent starts work in your repo, it reads AGENTS.md first to learn the ground rules: your stack, your commands, your conventions, and what to avoid. It's the difference between an agent that writes code matching your project and one that writes generic code you have to fix. CLAUDE.md is the same idea with the filename Claude Code reads first; the open AGENTS.md convention is now used by tens of thousands of projects across tools.

Think of it as onboarding docs for a new contributor who is fast, tireless, and has zero context about your specific choices.

Why a good one matters

Without an AGENTS.md, an agent defaults to the most common pattern for whatever you ask. Ask for a payment integration and you get the demo version everyone copies, not your production setup. Ask for a database query and you get the generic ORM call, not the one that respects your project's "no N+1, always whitelist columns" rule.

The agent isn't wrong — it's giving you the average of its training data. AGENTS.md is how you replace "the average" with "our way." This is the same principle as spec-driven AI: the model isn't the bottleneck, telling it what you actually want is.

The anatomy of a great AGENTS.md

A strong file has five sections, in roughly this order. None are mandatory — include what's load-bearing, skip what isn't.

A one-line purpose. What this project is, so the agent has context.
Tech stack. Languages, framework, package manager. The agent needs to know what to import and how.
Commands. Build, test, lint, dev. So the agent can verify its own work instead of guessing.
Conventions (do's). The patterns specific to your project — how you structure things, what you always do.
Anti-patterns (don'ts). The wrong-but-plausible things to prevent. This is the most valuable section and the one most people skip.

A real example

Here's an abbreviated AGENTS.md in the shape I actually use:

# Payments Platform

> Next.js + Postgres app for bootcamp registration with bKash payments.
> Read this before making changes.

## Tech stack

- Languages: TypeScript
- Package manager: pnpm
- Framework: Next.js 16 (App Router), Drizzle ORM, Postgres

## Commands

| Task | Command |
| --- | --- |
| Install | `pnpm install` |
| Dev | `pnpm dev` |
| Build | `pnpm verify` (typecheck + lint + build) |
| Test | `pnpm test` |

## Conventions

- Server Components fetch directly from the DB — don't proxy through
  an API route for same-origin server-rendered pages.
- API responses whitelist fields explicitly. Never spread the whole row.
- Indexes on every WHERE-clause column.

## Anti-patterns — don't

- Don't expose PII (email/phone/internal IDs) in URLs or client bundles.
- Don't trust client-side validation alone — re-validate on the server.
- Don't commit secrets; they live in env vars only.

## Commits

Use Conventional Commits: `<type>(<scope>): <subject>` (≤72 chars),
then a body explaining the *why*. Types: feat, fix, chore, docs,
refactor, test.

That's ~30 lines and it changes the agent's behaviour on the first prompt — no re-explaining your conventions every session.

The five rules of a good AGENTS.md

1. Keep it thin

Aim for 30–60 lines. The goal is the high-signal rules an agent needs, not exhaustive documentation. A 300-line AGENTS.md is a 300-line file the agent skims and partially ignores. If a rule isn't load-bearing, cut it.

2. Be specific, not generic

Write clean code is noise — the agent already tries to. Server Components fetch directly from the DB, never through an API route is signal — it's your choice, and the agent can't guess it. Name real commands, real paths, real conventions.

3. Lead with anti-patterns

The "don't do this" rules prevent more bad output than the "do this" rules generate good output. Don't expose PII in URLs stops a whole class of wrong-but-plausible code. Most people write only the do's and wonder why the agent keeps making the same mistakes — the mistakes were never named.

4. Keep it current

When a convention changes, update AGENTS.md in the same change. A stale rules file is worse than none — it confidently points the agent at the old way. Treat it like code: it drifts if you don't maintain it.

5. Scope it when the repo is big

For a large monorepo, a thin root AGENTS.md plus scoped files in subdirectories (the agent reads the nearest one) beats one giant file. Start with one root file; split only when it gets unwieldy.

Common mistakes

Padding it with generic best practices. "Write tests," "handle errors," "follow SOLID." The agent knows. This dilutes the signal that's actually yours.
Writing only do's, no don'ts. You lose the most valuable section.
Letting it go stale. The fastest way to confuse an agent is a rules file that describes a structure you've since changed.
Making it a novel. If it reads like documentation, it's too long. It's a checklist, not a manual.
Vague commands. Run the tests — how? Give the literal command so the agent can actually run it.

AGENTS.md vs CLAUDE.md — which file?

Same purpose, different filename:

AGENTS.md is the cross-tool convention — Cursor, Copilot, and others read it.
CLAUDE.md is the filename Claude Code reads first.

Many tools support both, and several read CLAUDE.md as a fallback. If you work mostly in Claude Code, use CLAUDE.md; if your team spans tools, use AGENTS.md. You can even keep one as the source and symlink the other.

How to generate one fast

You can write AGENTS.md by hand in ten minutes — the example above is the whole shape. Or use the free, no-login AGENTS.md generator: pick your stack, commands, conventions, and anti-patterns, and it assembles a clean file (in either AGENTS.md or CLAUDE.md format) that you copy or download. It runs entirely in your browser — no AI tokens, nothing sent anywhere.

If you want the whole agent setup — the rules file plus a subagent and a slash command — the AI agent project starter kit generates all three together.

What to do next

Write (or generate) a thin AGENTS.md for a project you're actively working on.
Put your real conventions in the do's, and the mistakes you keep seeing in the don'ts.
Drop it at the repo root and notice how the agent's first-pass output changes.
Update it the next time a convention changes — keep it alive.

The whole point: an agent that already knows your way produces code you keep, not code you rewrite.