An AGENTS.md example you can copy

AGENTS.md is a plain markdown file in your repo root that tells AI coding agents how your project works. The official site calls it a README for agents. There is no required format, so people often stare at a blank file. This article gives you a template you can copy, explains what each section is for, and covers how Cursor and Claude Code read the file.

Checked on 27 Oct 2026 against agents.md, Cursor's rules docs and Claude Code's memory docs.

What AGENTS.md is for

A README.md is for people: what the project is, how to contribute. AGENTS.md holds the extra context an agent needs and a human would find noisy: exact build and test commands, code style, things that must never be touched. The agents.md site is explicit that there are no required fields. It is standard markdown, and the agent reads whatever headings you use.

Three behaviours from the project's FAQ are worth knowing:

• If you list test or lint commands, the agent will try to run the relevant ones and fix failures before it finishes.
• In a monorepo you can put another AGENTS.md in each package. The closest file to the one being edited wins.
• If instructions conflict, an explicit prompt in chat overrides the file.

A template you can copy

# AGENTS.md

## Project overview
One paragraph: what this app does and who uses it.
Stack: Next.js (App Router), TypeScript strict, Supabase, Tailwind.

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm test` (single file: `npm test -- path/to/file`)
- Build: `npm run build`

## Code style
- TypeScript strict. No `any`, no `@ts-ignore`.
- Named exports. One component per file in `components/`.
- Server Components by default; `"use client"` only where needed.

## Testing
- Add or update a test for any behaviour you change.
- Run typecheck, lint and tests before you say a task is done.

## Boundaries
- Do not edit `supabase/migrations/` that are already applied.
- Do not read or print `.env*` files.
- Ask before adding a dependency.

## Security
- Validate all input on the server.
- Check auth on every route that touches user data.

## Pull requests
- Small diffs. One task per PR.
- Title format: `[area] short description`.

Replace the stack line and the commands first. Those two edits do most of the work.

What to put in each section

Commands

This is the most valuable section. An agent that can run your tests can check its own work. Use the exact commands you type, including flags. If a command does not exist yet, leave it out rather than guessing.

Code style

Write rules a person could verify. "Use named exports" is checkable. "Write clean code" is not. Do not paste a whole style guide; a linter does that job better.

Boundaries

List folders the agent should not edit, files it must not read, and actions that need your approval. A short list of "never" lines prevents the expensive mistakes.

Project notes

Keep a short section for things the agent keeps getting wrong in your repo. When it repeats a mistake, add one line.

Rules that apply to every project

Beyond the project-specific parts, a few lines belong in almost every AGENTS.md. These come from the core rules in the Vibemast kit:

- Do not invent package names, function names, config keys or CLI flags.
  If you are not sure something exists, look it up and say what you checked.
- If two attempts at the same fix fail, stop. Summarise what you tried
  and ask. Do not keep looping.
- Report honestly: what you ran, what passed, what you did not verify.

The second line is the one that saves the most time. Agents tend to repeat a failed fix with small variations. A rule that tells them to stop and report breaks that loop.

How Cursor and Claude Code read it

Cursor supports AGENTS.md in the project root and in subfolders. A nested file applies automatically when the agent works with files in that folder or its children. Cursor's docs describe it as a simple alternative to .cursor/rules, a plain markdown file without frontmatter or other configuration.

Claude Code reads CLAUDE.md. According to its docs, it also reads AGENTS.md, but only when there is no CLAUDE.md in the working directory or above it, and it needs a recent version (v2.1.277 or later at the time of writing). If you want both, create a CLAUDE.md that imports the shared file:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Claude's docs say to use the import in sessions where it cannot read AGENTS.md directly. If you add a personal CLAUDE.local.md, Claude stops reading AGENTS.md on its own, so keep the import in place or change the Project instructions setting under /config.

Other tools vary. The agents.md site shows Aider reading the file through read: AGENTS.md in .aider.conf.yml and Gemini CLI through context.fileName in .gemini/settings.json. Check your tool's current docs.

Keep it short and keep it current

Claude Code's docs recommend targeting under 200 lines per instruction file, and Cursor recommends keeping rules under 500. Long files cost context on every request and the important lines get buried. If two files contradict each other, the agent may pick either.

The Vibemast Ship-It Kit includes ready-made AGENTS.md files for Next.js with Supabase, Vite with React, FastAPI and Phaser, plus a generator that writes the matching CLAUDE.md, Cursor rules and Copilot instructions from one source. If you want to see the structure first, the free mini pack includes the generator and a Vite and React example. For a comparison of the file types, read Cursor rules vs CLAUDE.md vs AGENTS.md.

Using Claude Code or Cursor as well? See the CLAUDE.md example and the Cursor rules template.

Get a filled-in AGENTS.md for your stack

The template above is a starting point. To get a filled-in version without writing it from scratch:

1. Download the free mini pack and run node scripts/generate.mjs --stack vite-react --out . in your project. You get AGENTS.md plus matching CLAUDE.md and Cursor rules.
2. Fill in the project commands and add one line under the project notes for each mistake your agent repeats.
3. Check that each tool loaded it: /context in Claude Code, the rules list in Cursor settings.

For Next.js with Supabase, FastAPI or Phaser, the Ship-It Kit has ready-to-copy AGENTS.md files for each stack, plus planner, builder and reviewer agent roles.

Who the paid kit is for, and who it is not for

• Worth it if you build on one of its four stacks (Next.js with Supabase, Vite with React, FastAPI, Phaser) and want tested files and prompts today instead of writing and testing your own.
• Not worth it if you only need one rules file for one project. The free guides and the free mini pack are enough, and you can adapt them yourself.

Related guides

• 12 rules for AI coding agents
• When your AI agent keeps breaking your code
• Pre-launch security checklist for vibe-coded apps

FAQ

Is AGENTS.md an official standard?

It is an open format, not a formal specification. The agents.md site says it is stewarded by the Agentic AI Foundation under the Linux Foundation, and there is no schema to follow.

Do I still need a README?

Yes. Keep the README for people and put agent-specific detail in AGENTS.md.

Can I use one file for Cursor, Claude Code and Copilot?

Mostly. Cursor reads AGENTS.md directly. Claude Code reads it directly when no CLAUDE.md exists, or through an import. Copilot has its own .github/copilot-instructions.md, so check what your version supports or generate that file from the same source.

How long should it be?

Under about 200 lines. If one part only matters for one folder, put a nested AGENTS.md there.