# AGENTS.md template and example: set it up for any coding agent > A copyable AGENTS.md template, a filled-in example for a Next.js and Supabase SaaS, and how Claude Code, Codex, Cursor and Copilot each find the file. Source: https://shipanysaas-demo.vercel.app/blog/agents-md-guide Published: 2026-10-18 ยท Updated: 2026-10-18 AGENTS.md is a plain Markdown file at the root of your repository that tells any coding agent how to build, test and change your code: exact commands, where things live, your rules and your checks. Below is a copyable AGENTS.md template, a filled-in example for a Next.js and Supabase SaaS, and how each major agent finds it. Every session, your agent starts out knowing nothing about your project. It guesses the test command, puts a file in the wrong folder, and you correct it again. The file is where you write those corrections down once. Agents don't all find it the same way, though, so a file that works in one can be invisible to another; the second half of this guide covers that. ## What is an AGENTS.md file? A README for agents, in the words of the [agents.md](https://agents.md) site. Your README explains the project to people; AGENTS.md holds what an agent needs to make a correct change without asking you. There are no required fields or headings: it is ordinary Markdown. It is also an open format rather than one vendor's file. It came out of work by OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and as of October 2026 the Agentic AI Foundation under the Linux Foundation looks after it. That is why one file can serve several agents. | File | Written for | What it holds | | --- | --- | --- | | `README.md` | People | What the project is, quick start, how to contribute | | `AGENTS.md` | Any coding agent | Commands, layout, conventions, boundaries, checks | | `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/` | One tool each | Extras for that tool, or a way back to `AGENTS.md` | ## What should you put in AGENTS.md? Five kinds of line earn their place: - **Commands, exactly as you type them.** Install, dev server, all tests, a single test file, type check, lint. The agents.md site notes that agents try to run the checks you list and fix failures before they finish, so list the ones you want run. - **A map.** Where the source, tests, migrations and generated code live, one line per folder. - **Rules you could check in a code review.** Claude Code's docs note that specific, concise instructions are followed more consistently. "Store money as integer cents" works; "handle money carefully" does not. - **Boundaries.** What the agent must never do, and what it must ask about first. - **A definition of done.** The checks to run before it stops, and what to tell you at the end. Keep it short. Claude Code's docs suggest keeping its instruction file under 200 lines, because longer files use more context and are followed less closely, and Codex stops adding instruction files once they reach 32 KiB combined by default. A procedure the agent needs only now and then, such as cutting a release, belongs in a [skill](https://shipanysaas-demo.vercel.app/blog/agent-skills-explained). ## AGENTS.md template Copy this into the root of your repository and replace everything in angle brackets. Delete any section you have nothing true to say in; an empty heading teaches the agent nothing. ```markdown # AGENTS.md ## Commands - Install: `` - Dev server: `` () - All tests: ``. One file: `` - Type check: `` - Lint and format: `` ## Where things live - `/`: - `/`: - `/`: generated. Do not edit. ## Rules - - - ## Ask first - ## Never - ## Before you finish 1. ``, `` and `` pass. 2. Tell me what changed and anything you could not check. ``` If you'd rather fill in a form, the free [AGENTS.md generator](https://shipanysaas-demo.vercel.app/tools/agents-md-generator) builds the same file in your browser from presets for Next.js, Expo, Django, Rails, Laravel, Go and more, plus the small extra file some agents need. ## AGENTS.md example for a Next.js and Supabase SaaS Here is the template filled in for a typical SaaS: Next.js 16 with the App Router, Supabase for auth and Postgres, Stripe for billing, pnpm. Every command is one the agent can run as written. ```markdown # AGENTS.md Invoicing SaaS for small agencies: Next.js 16 (App Router), Supabase (Auth + Postgres), Stripe subscriptions. Deployed on Vercel. ## Commands - Install: `pnpm install` - Local database: `supabase start` (needs Docker). Reset: `supabase db reset` - Dev server: `pnpm dev` (http://localhost:3000) - Unit tests: `pnpm test`. One file: `pnpm test src/lib/tax.test.ts` - Database tests (pgTAP): `supabase test db` - New migration: `supabase migration new ` - Regenerate types: `supabase gen types typescript --local > src/lib/database.types.ts` - Type check and lint: `pnpm typecheck && pnpm lint` ## Where things live - `src/app/`: routes. Server Components by default. - `src/lib/supabase/`: `client.ts` (browser) and `server.ts` (server) clients - `src/proxy.ts`: refreshes the Supabase session on every request - `supabase/migrations/`: SQL migrations, one file per change - `supabase/tests/`: pgTAP tests, one file per table - `src/lib/database.types.ts`: generated. Do not edit. ## Rules - Every tenant table has an `account_id`, row-level security on, explicit grants, and one policy per command. No `for all` policies. - Server code checks the user with `supabase.auth.getClaims()`. Never trust `getSession()` on the server. - The secret key (`SUPABASE_SECRET_KEY`) is used only in files that start with `import 'server-only'`. Only the publishable key goes in `NEXT_PUBLIC_*`. - Subscriptions change only in the Stripe webhook, after the signature check. - Money is integer cents. Dates are stored in UTC. ## Ask first - Adding a dependency, changing an existing migration, or touching billing. ## Never - Commit `.env*` files or print secret values. - Disable row-level security on a table, even to debug. ## Before you finish 1. `pnpm typecheck && pnpm lint && pnpm test` pass. 2. After any database change: `supabase db reset && supabase test db` pass, including a test that a user from another account cannot read the new rows. 3. Tell me what changed, which checks ran, and anything you could not check. ``` Apart from the summary line, every entry is a command, a location or a rule the agent can follow without interpreting it. What the product is for stays in the README. The rules here are the ones that matter most in a Supabase app; [Supabase RLS explained](https://shipanysaas-demo.vercel.app/blog/supabase-rls-explained) covers why. ## How do Claude Code, Codex, Cursor and Copilot find AGENTS.md? Codex and Cursor read it by themselves. Claude Code reads it only when there is no `CLAUDE.md`, and Copilot depends on where you use it. | Agent | Reads `AGENTS.md` by itself? | What to add | | --- | --- | --- | | OpenAI Codex | Yes | Nothing | | Cursor | Yes, at the root and in subfolders | Nothing. `.cursor/rules` is optional, for rules scoped to certain files | | Claude Code | Yes (v2.1.277+), but only when the repository has no `CLAUDE.md` | If you keep a `CLAUDE.md`, start it with `@AGENTS.md` | | GitHub Copilot | Depends on the surface | A short `.github/copilot-instructions.md` | **Codex** reads `AGENTS.md` before it does any work. It starts with your personal `~/.codex/AGENTS.md`, then walks from the repository root down to the folder you started it in, taking one file per folder. It also honours `AGENTS.override.md` for a temporary override, which only Codex reads. Its `/init` command writes a first draft. Details are in [Codex's AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md). **Cursor** treats `AGENTS.md` as the plain-Markdown alternative to its project rules. Cursor rules live in `.cursor/rules` as `.mdc` files with `description`, `globs` and `alwaysApply` in their frontmatter; a plain `.md` file in that folder is ignored ([Cursor's rules docs](https://cursor.com/docs/rules)). **Claude Code** reads `CLAUDE.md` files, and as of October 2026 also reads `AGENTS.md` when there is no `CLAUDE.md` or `CLAUDE.local.md` in your folder or above it. If both exist, it reads only `CLAUDE.md` by default. The fix in [Claude Code's docs](https://code.claude.com/docs/en/memory#agents-md) is an import at the top of `CLAUDE.md`: ```markdown @AGENTS.md ## Claude Code only - Ask before running a database migration. ``` The import pulls the whole file into context, and it also covers older versions. To have Claude read both files without an import, change Project instructions in `/config`. [CLAUDE.md explained](https://shipanysaas-demo.vercel.app/blog/claude-md) covers the rest of Claude's file. **GitHub Copilot** reads different files on different surfaces. As of October 2026, its cloud agent, code review on GitHub, Copilot CLI and chat in VS Code read `AGENTS.md`. Copilot Chat on github.com, in Visual Studio and in JetBrains IDEs reads `.github/copilot-instructions.md` instead. GitHub keeps the full list in [its support table](https://docs.github.com/en/copilot/reference/custom-instructions-support). Give those surfaces a short instructions file: a line pointing to `AGENTS.md`, plus the two or three rules that must never be missed. For other tools, the agents.md site lists who reads the file and the one setting a few of them need: `read: AGENTS.md` in `.aider.conf.yml` for Aider, and `"context": { "fileName": "AGENTS.md" }` in `.gemini/settings.json` for Gemini CLI. ## How do nested AGENTS.md files work in a monorepo? Put another `AGENTS.md` in each package that has its own commands or rules. The convention from agents.md is that the file closest to the code being edited wins, and an instruction you type in chat overrides every file. ```markdown # packages/api/AGENTS.md - Run this package's tests with `pnpm --filter api test`. - Every route validates its input with a schema from `src/schemas/`. ``` Each agent applies the convention a little differently. Codex joins the files from the root down, so the closer ones come last and take precedence. Cursor combines a nested file with its parents, and the more specific one wins. Copilot gives precedence to the nearest file. Claude Code loads a subfolder's `AGENTS.md` once it opens a file there, but only in a repository without `CLAUDE.md` files; if you keep them, give each package a `CLAUDE.md` with `@AGENTS.md` as well. Keep rules that hold everywhere in the root file, and don't repeat them per package. Two copies drift apart, and Claude Code's docs warn that when two instructions contradict each other, the agent may pick either one. ## How do you keep AGENTS.md up to date? Add a line when you correct the agent for the same thing twice, or when a code review catches something it should have known. Remove a line the day a command or folder changes: an out-of-date command is worse than none, because the agent trusts it. In Claude Code (v2.1.283+), `/doctor prompt-audit` reads your instruction files, `AGENTS.md` included, and reports references to files or commands that don't exist and files that contradict each other. ## See a full setup shipanysaas, the SaaS starter kit this blog belongs to, is built this way. One root `AGENTS.md` holds the rules every agent follows, and sixteen nested ones cover its apps and packages. `CLAUDE.md` is a single `@AGENTS.md` import, seven more agents get short pointer files, and Codex and Grok Build need nothing, so each of the ten agents the kit is set up for reads the same rules. [Building on the kit with a coding agent](https://shipanysaas-demo.vercel.app/blog/building-with-a-coding-agent) walks through it, and [Coding agents](https://shipanysaas-demo.vercel.app/docs/coding-agents/coding-agents) lists every file. ## FAQ ### Is AGENTS.md the same as CLAUDE.md? Same idea, different reader. `CLAUDE.md` is Claude Code's own file and `AGENTS.md` is the shared one. To use both, start `CLAUDE.md` with `@AGENTS.md` and put the Claude-only notes below it. ### Where do I get an AGENTS.md template? Copy the template above, or use the free [AGENTS.md generator](https://shipanysaas-demo.vercel.app/tools/agents-md-generator), which fills in commands for your stack. Codex's `/init` and Claude Code's `/init` (which writes a `CLAUDE.md`) can also draft one from your code; read the draft line by line, because it describes the code that exists, not the rules you care about. ### Do I still need a copilot instructions file? Yes, if anyone on your team uses Copilot Chat on github.com, in Visual Studio or in a JetBrains IDE. Those read `.github/copilot-instructions.md`, not `AGENTS.md`. ### What happens when two files disagree? The file nearest the code being edited wins, and what you type in chat beats any file. Inside a single file there is no such order, so remove contradictions when you find them.