What is AGENTS.md? How to Write One for Your Next.js Project (2026)

The File That Makes AI Agents Actually Understand Your Codebase

Here's a scenario every developer using AI tools has lived through. You open Claude Code or Cursor, assign it a task "add input validation to the signup form" and it comes back with a perfectly written solution that uses the wrong validation library, breaks three of your naming conventions, and imports from a deprecated module you stopped using six months ago. Technically correct. Completely wrong for your project.

I hit this wall constantly until I started taking AGENTS.md seriously. One file, placed at the root of your repository, that tells every AI coding agent exactly how your project works the commands, the conventions, the boundaries, and the things it should never touch. Projects with a properly written AGENTS.md average 35–55% fewer agent-generated bugs. That number comes from Anthropic's own internal benchmarks, and honestly it matches what I've seen in practice.

This guide covers what AGENTS.md is, why it finally replaced the chaos of tool-specific instruction files, and how to write one for a Next.js project that actually works with real templates you can copy and adapt today.

• What AGENTS.md is and how it differs from .cursorrules and CLAUDE.md

• Which AI tools read it and how they use it

• The exact sections every good AGENTS.md needs

• A complete Next.js App Router template you can use right now

• How to structure it for monorepos with multiple agents running in parallel

• The most common mistakes that make AGENTS.md useless

The Problem It Solves - And Why It Took This Long

Before AGENTS.md became the standard, teams maintained a patchwork of tool-specific instruction files. You had .cursorrules for Cursor, CLAUDE.md for Claude Code, and .github/copilot-instructions.md for GitHub Copilot. Every time you onboarded a new tool or switched between agents, you had to maintain another file with overlapping but slightly different content.

AGENTS.md solves this with one cross-tool standard. One file that every major coding agent reads. Claude Code, Cursor, GitHub Copilot Agent Mode, and OpenAI Codex all support it. The agent reads the file at session start, loads your project context, and adjusts its behaviour accordingly before writing a single line of code.

The timing matters. In 2026, 84% of developers use AI coding tools daily. The question isn't whether to use AI it's whether your AI produces code that fits your project or code that requires a full manual review every time. AGENTS.md is the difference between those two outcomes.

What AGENTS.md Actually Is

It's a plain Markdown file. No special syntax. No YAML frontmatter. No required fields. Just headings and bullet points that a coding agent parses at the start of each session to understand the context it's working in.

The file lives at the root of your repository same level as package.json. In monorepos, you can place additional AGENTS.md files inside subdirectories; the agent reads the nearest file to whatever it's editing, so each subproject can have its own tailored instructions while sharing root-level conventions.

Here's the minimal structure that makes a real difference:

# Project Name

## Stack
Next.js 15 App Router, TypeScript 5.x strict, Tailwind CSS v4, Prisma, PostgreSQL

## Commands
- Dev server: `npm run dev`
- Type check: `npm run typecheck`
- Lint: `npm run lint`
- Tests: `npm run test`
- Build: `npm run build`

## Conventions
- Named exports only — no default exports
- Server components by default, `'use client'` only when necessary
- Zod for all validation — never use manual type guards
- Error boundaries at route segment level

## Boundaries
- Never modify `prisma/schema.prisma` without asking — migrations are tracked
- Never touch `/lib/legacy/` — deprecated, being phased out
- Never import from `@/components/ui/` without checking shadcn docs first

## Testing
- Vitest for unit tests
- Never mock the database — use test transactions that roll back

That's it. Under 150 lines. And it prevents the most common class of AI agent failures: the technically correct solution that's architecturally wrong for your specific project.

Which AI Tools Read AGENTS.md?

This is the question I get most often, so let me be precise about the current state as of June 2026:

• Claude Code: reads AGENTS.md natively. Also still reads CLAUDE.md for backwards compatibility, but AGENTS.md takes priority when both exist.

• GitHub Copilot (Agent Mode): full support since the Agent HQ launch. In GitHub Agent HQ, AGENTS.md is the shared context file all agents in a multi-agent session receive simultaneously.

• Cursor: reads AGENTS.md as a higher-priority alternative to .cursorrules. Both are supported; AGENTS.md wins if both exist.

• OpenAI Codex (via Agent HQ): reads AGENTS.md when running inside GitHub Agent HQ. As a standalone tool, check the current docs as support was added in early 2026.

• Windsurf: partial support. Reads the file but doesn't enforce boundaries as strictly as Claude Code or Copilot.

If you're using the Claude Code vs Cursor vs Copilot comparison as your guide for which tool to pick, AGENTS.md support is now a meaningful criteria all three top tools fully support it, so writing one file covers your entire AI coding setup.

The Five Sections That Matter Most

You can write whatever you want in AGENTS.md there's no enforced schema but the teams that get the best results consistently include these five sections. I'll walk through each one with the reasoning behind it.

1. Stack (What the Agent Is Working With)

One line per major technology. Framework, language, version, major libraries. Be specific about versions where they matter Next.js 15 App Router behaves very differently from Next.js 14, and an agent that doesn't know which one you're on will generate server action syntax that doesn't compile.

## Stack
Next.js 15.3 App Router, TypeScript 5.9 strict mode, Tailwind CSS v4,
Prisma 6.x with PostgreSQL, Zod 3.x, NextAuth v5, Vercel deployment

2. Commands (Exact Executables With Flags)

This is the most underestimated section. Agents use these commands to verify their own work they run your type checker and linter after making changes to confirm nothing broke. If you don't provide exact commands, the agent guesses, and guesses are often wrong for custom setups.

## Commands
- Install: `npm install`
- Dev: `npm run dev` (runs on port 3000)
- Type check: `npm run typecheck` (tsc --noEmit)
- Lint: `npm run lint` (eslint + prettier check)
- Test: `npm run test` (vitest)
- Test watch: `npm run test:watch`
- Build: `npm run build`
- DB push: `npx prisma db push` (dev only — never in CI)
- DB migrate: `npx prisma migrate dev --name <description>`

3. Conventions (Project-Specific Rules, Not Generic Advice)

This is where most AGENTS.md files fail. Developers write things like "follow best practices" or "write clean code." Those phrases mean nothing to an agent. Write rules that are specific, executable, and different from what a generic TypeScript developer would assume by default.

## Conventions
- Named exports only — `export function Foo()`, never `export default`
- Components: PascalCase filenames, functional with hooks
- Server components by default — add `'use client'` only when hooks or
  browser APIs are needed
- Server actions live in `/app/actions/` — one file per domain (auth.ts,
  user.ts, post.ts)
- API route handlers in `/app/api/` follow REST conventions
- Zod schema for every form and API input — no manual type assertions
- Use `@/` alias for all internal imports — never relative `../../`
- shadcn/ui components only from `/components/ui/` — don't modify them,
  extend with wrapper components
- Database queries only in `/lib/db/` — never inline in components or
  server actions directly

4. Boundaries (What the Agent Should Never Touch)

Three tiers work well here: Always do, Ask first, Never do. The "never do" list is the most important these are the files and patterns where an agent mistake is expensive to reverse.

## Boundaries

### Ask before doing
- Changes to `prisma/schema.prisma` — migrations are version-controlled and
  need manual review
- New dependencies — check if an existing package already covers the need
- Changes to `next.config.ts` — affects the entire build

### Never do
- Modify files in `/lib/legacy/` — deprecated, being migrated, don't touch
- Delete or rename files without explicit instruction
- Add `any` type — fix the type properly or ask for help
- Use `localStorage` or `sessionStorage` directly — we have a
  `/lib/storage/` wrapper that handles SSR safety
- Commit secrets or environment variables — .env.local is gitignored,
  use process.env with Zod validation in `/lib/env.ts`

5. Testing (Framework + Strategy + What Not to Mock)

Agents write tests when you ask them to. Without guidance, they'll mock everything, use the wrong testing framework, or write tests that pass but don't catch real bugs. Tell them exactly how your project tests work.

## Testing
- Framework: Vitest with @testing-library/react for component tests
- Unit tests: `/tests/unit/` — pure functions only
- Integration tests: `/tests/integration/` — test full server actions
  with a real DB connection (transactions roll back after each test)
- E2E: Playwright in `/tests/e2e/` — run with `npm run test:e2e`
- Never mock Prisma — use test database with seed data
- Never mock fetch — use MSW (Mock Service Worker) for API mocking
- Coverage threshold: 80% for /lib/, 60% for /app/

Complete Next.js App Router Template

Here's a full AGENTS.md you can copy, paste into your project root, and adapt in under 10 minutes. Replace the stack details and conventions with your own the structure is what matters.

# My Next.js Project

## Stack
Next.js 15.3 App Router, TypeScript 5.9 (strict), Tailwind CSS v4,
Prisma 6.x, PostgreSQL, NextAuth v5, Zod 3.x, Vitest, Playwright

## Commands
- Dev: `npm run dev`
- Type check: `npm run typecheck`
- Lint: `npm run lint`
- Format: `npm run format`
- Test: `npm run test`
- Build: `npm run build`
- DB sync (dev): `npx prisma db push`
- DB migrate: `npx prisma migrate dev --name <description>`

## Project Structure
- `/app/` — Next.js App Router pages and layouts
- `/app/actions/` — Server actions, one file per domain
- `/app/api/` — API route handlers
- `/components/ui/` — shadcn/ui components (do not modify)
- `/components/` — Custom components
- `/lib/` — Shared utilities, DB client, env validation
- `/lib/db/` — All Prisma queries live here
- `/lib/env.ts` — Zod-validated environment variables
- `/tests/` — unit/, integration/, e2e/

## Conventions
- Named exports only, never default exports
- Server components by default, `'use client'` only for hooks/browser APIs
- All user input validated with Zod before processing
- `@/` alias for all internal imports
- Error handling: throw typed errors in server actions, catch at route level
- No inline styles — Tailwind utility classes only
- Component files: PascalCase. Utility files: camelCase.

## Boundaries

### Ask before doing
- `prisma/schema.prisma` changes
- New npm dependencies
- `next.config.ts` changes
- Architectural changes affecting multiple modules

### Never do
- Add TypeScript `any` — fix the type properly
- Import from `/lib/legacy/` — deprecated
- Use `localStorage` directly — use `/lib/storage/client.ts` wrapper
- Hardcode environment values — use `/lib/env.ts`
- Modify files in `/components/ui/` — extend with wrappers instead

## Testing
- Vitest for unit and integration tests
- Playwright for E2E tests
- Never mock Prisma — use test DB with rollback transactions
- MSW for mocking external API calls
- Run `npm run typecheck && npm run lint && npm run test` before marking done

AGENTS.md for Monorepos and Multi-Agent Workflows

If you're running multiple agents in parallel which is exactly what GitHub Agent HQ enables a single root AGENTS.md isn't enough. Two agents editing the same files simultaneously is a recipe for conflicts. The solution is scoped AGENTS.md files per directory:

project/
├── AGENTS.md              # Shared: git conventions, CI checks, global rules
├── apps/
│   ├── web/
│   │   └── AGENTS.md      # "You handle frontend only. Don't touch /api/"
│   └── api/
│       └── AGENTS.md      # "You handle API routes only. Don't touch /web/"
└── packages/
    └── ui/
        └── AGENTS.md      # "UI library only. No business logic here."

Each agent reads the root file first for shared conventions, then the nearest scoped file for its domain-specific rules. The scoping prevents agents from touching the same files at the same time which is the most common source of multi-agent merge conflicts.

This pattern is especially important when you're using autonomous agentic workflows where agents run without constant human supervision. Without file scope boundaries, two agents will eventually try to edit the same component and produce a conflict that requires manual resolution.

AGENTS.md vs CLAUDE.md vs .cursorrules - What to Use

If you're already using one of the older formats, here's the migration picture as of mid-2026:

• AGENTS.md: Use this as your primary file going forward. It's the cross-tool standard supported by Claude Code, Copilot, Cursor, and Codex. One file for all agents.

• CLAUDE.md: Still works in Claude Code for backwards compatibility. If you have one, it continues to function. But AGENTS.md takes priority when both exist, so migrate when you have time.

• .cursorrules: Cursor still reads this but treats it as lower priority than AGENTS.md. The .cursorrules complete guide on WebToolsHub covers the legacy format in detail if you're on an older Cursor version.

• .github/copilot-instructions.md: Copilot still reads this for repository-level instructions, but Agent HQ uses AGENTS.md as the shared context for multi-agent sessions. Keep the Copilot file for backwards compatibility, migrate your main content to AGENTS.md.

The migration from any of these formats to AGENTS.md takes about 20 minutes. Copy your existing content, restructure it into the five sections above, and you're done. The format is more structured, which paradoxically makes it shorter you stop writing prose and start writing executable rules.

How to Keep AGENTS.md Accurate Over Time

This is the hardest part. The file is only useful if it's accurate, and codebases change faster than documentation. A few practices that actually work:

• Treat it like code, not a doc. Every PR that changes your stack, adds a dependency, or modifies a major convention should include a corresponding AGENTS.md update. Add it to your PR template as a checkbox.

• Keep it under 150 lines. Longer files drift faster. If you find yourself writing paragraphs of explanation, you've crossed from machine-readable instructions into human documentation. Split them into separate files.

• Non-inferable details have the highest signal. Rules like "use Zod" are useful. Rules like "our custom useFormState hook in /lib/forms/hooks.ts wraps React's useActionState and adds toast notifications always use this instead of useActionState directly" are priceless. Document the things an outsider would never guess from the code.

• Run agents against it periodically. Ask Claude Code or Cursor to audit your AGENTS.md against your actual codebase and flag anything that's outdated. Agents are good at this kind of cross-reference task, and it takes less than five minutes.

The biggest AGENTS.md failure mode isn't writing it wrong it's letting it go stale. A six-month-old AGENTS.md with wrong commands and deprecated paths is worse than no file at all, because it actively misleads agents into making the wrong decisions confidently.

What Happens When You Don't Have One

I want to put a number on this because vague statements about "better AI output" don't drive action. The concrete cost of not having AGENTS.md is this: every AI coding session starts with the agent in a cold state. It knows TypeScript and Next.js in general, but it knows nothing about your specific project. It will use default exports when you need named exports. It will write inline validation when you need Zod. It will modify the legacy folder you've been slowly deleting. It will add a third-party package for something you already handle with a custom hook.

Every one of those mistakes is a code review catch, a correction prompt, or a revert. Over a day of development, that compounds. Over a team of four developers, all running agents without project context, it compounds further.

The 35–55% bug reduction isn't just about code quality it's about the time you spend correcting agents instead of shipping features. AGENTS.md is the cheapest engineering investment in your AI coding workflow.

If you're already thinking about how this fits into a broader agentic architecture — multi-step pipelines, autonomous task runners, MCP server integrations the MCP complete guide for 2026 covers how to connect Claude and other agents to external tools and data sources, and AGENTS.md is the foundation that makes those integrations reliable in production.

Frequently Asked Questions

What is AGENTS.md and which AI tools support it?

AGENTS.md is a plain Markdown file placed at the root of your repository that provides AI coding agents with structured context about your project commands, conventions, architecture, and boundaries. It was standardised in 2025 as the cross-tool replacement for tool-specific instruction files like .cursorrules and CLAUDE.md. As of June 2026, full support exists in Claude Code, GitHub Copilot Agent Mode, GitHub Agent HQ, and Cursor. OpenAI Codex supports it when running inside Agent HQ. The file is read at session start and adjusts agent behaviour before any code is written.

What is the difference between AGENTS.md and CLAUDE.md?

CLAUDE.md is Anthropic's earlier Claude-specific instruction file. AGENTS.md is the newer cross-tool standard that works across Claude Code, Cursor, Copilot, and Codex simultaneously. Claude Code reads both files but gives priority to AGENTS.md when both exist. If you're starting a new project, use AGENTS.md exclusively. If you have an existing CLAUDE.md, it continues to work migrate to AGENTS.md when convenient, but there's no urgent reason to rush the transition.

How long should an AGENTS.md file be?

Keep it under 150 lines. The file is loaded into the agent's context window at session start alongside your actual code and conversation. A bloated AGENTS.md wastes context tokens that could be used for your actual codebase. The goal is maximum signal per line specific rules, exact commands, and non-obvious project-specific conventions. Anything that an experienced TypeScript developer would already know doesn't need to be in the file. Focus on what makes your project different from a generic Next.js app.

Does AGENTS.md work with GitHub Agent HQ's multi-agent setup?

Yes. AGENTS.md is the shared context file for multi-agent sessions in Agent HQ. When you run Claude, Codex, and Copilot simultaneously on the same repository, Agent HQ loads your root AGENTS.md into all three agents' context at session start. For monorepos or projects where you want agents to have scoped responsibilities, place additional AGENTS.md files in subdirectories. The agent reads the nearest file to the code it's editing, so a frontend agent and a backend agent can operate from separate instruction sets while sharing the root-level conventions.

What's the most important section to include in AGENTS.md?

The Boundaries section specifically the "never do" list. Commands and conventions make agents more accurate, but a missing boundary can cause an agent to modify a deprecated file, add a conflicting dependency, or break a carefully maintained migration path. The highest-value entries in your boundaries are the non-obvious ones: files that look safe to edit but aren't, patterns that are technically valid TypeScript but wrong for your project, and directories that have complex interdependencies an agent wouldn't detect from the code alone.

Should I commit AGENTS.md to version control?

Yes, always. AGENTS.md is a project asset, not a personal configuration file. Every developer on your team and every agent working on your repository benefits from it. Commit it at the root level, include it in PR templates as a file to update when stack changes happen, and treat stale AGENTS.md content the same way you'd treat stale documentation a technical debt item that actively causes problems. A version-controlled AGENTS.md also gives you a history of how your agent conventions evolved as your project matured.

How is AGENTS.md different from a README file?

README files are written for human developers: narrative prose, setup guides, project descriptions, contribution guidelines. AGENTS.md is written for AI agents: direct, operational, unambiguous rules. The writing style should be completely different. Where a README says "we prefer functional components," AGENTS.md says "components are functional with hooks, PascalCase filenames, named exports only, server components by default." Specificity and machine readability are the only goals. If a section reads well as prose, it probably belongs in the README, not AGENTS.md.