You've been here. You open Claude Code, assign it a task — "add validation to the signup form" — and it comes back with a technically correct solution that uses the wrong validation library, breaks three of your naming conventions, and imports from a module you deprecated six months ago.
The fix isn't a better prompt. It's AGENTS.md.
One file at your repo root. Every AI coding agent reads it at session start. Projects with a properly written one average 35–55% fewer agent-generated bugs — and that number tracks with what I've seen in practice.
Here's everything you need to know, with copy-paste Next.js templates.
What AGENTS.md Actually Is
Plain Markdown. No YAML frontmatter. No special syntax. Just headings and bullet points that tell a coding agent:
- What your stack is (exact versions)
- Which commands to run
- What conventions to follow
- What to never touch
It lives at your repo root — same level as package.json. Every major AI coding tool reads it as of 2026:
| Tool | Support |
|---|---|
| Claude Code | ✅ Native (priority over CLAUDE.md) |
| GitHub Copilot Agent Mode | ✅ Full (Agent HQ shared context) |
| Cursor | ✅ Priority over .cursorrules |
| OpenAI Codex (Agent HQ) | ✅ Full |
| Windsurf | ⚠️ Partial |
Why It Replaced .cursorrules and CLAUDE.md
Before AGENTS.md, you maintained a different file per tool:
.cursorrules ← Cursor
CLAUDE.md ← Claude Code
.github/copilot-instructions.md ← Copilot
GEMINI.md ← Gemini
Every tool switch meant duplicating content. Instructions drifted. New teammates had to hunt for "the real rules."
AGENTS.md is the cross-tool standard — one file, every agent. You can keep your old files for backwards compatibility (tools still read them), but AGENTS.md takes priority when both exist.
The Minimal Structure That Actually Moves the Needle
# Project Name
## Stack
Next.js 15.3 App Router, TypeScript 5.9 strict, Tailwind CSS v4,
Prisma 6.x, PostgreSQL, Zod 3.x, NextAuth v5
## Commands
- Dev: `npm run dev`
- Type check: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm run test`
- Build: `npm run build`
## Conventions
- Named exports only — never default exports
- Server components by default, `'use client'` only when hooks/browser APIs needed
- Zod for all validation — never manual type guards
- `@/` alias for all internal imports
## Boundaries
### Ask before doing
- Changes to `prisma/schema.prisma`
- New npm dependencies
- `next.config.ts` changes
### Never do
- Add TypeScript `any`
- Modify `/lib/legacy/` — deprecated
- Use `localStorage` directly — use `/lib/storage/client.ts` wrapper
Under 60 lines. Prevents the most common class of AI agent failures.
The Five Sections That Matter
1. Stack — Be Specific About Versions
Next.js 15 App Router behaves completely differently from Next.js 14. An agent that doesn't know which 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, Vitest, Playwright,
deployed on Vercel
2. Commands — Exact Executables With Flags
Agents use these to verify their own work. They run your type checker and linter after making changes. If you don't provide exact commands, they guess — and guesses fail on custom setups.
## Commands
- Install: `npm install`
- Dev server: `npm run dev` (port 3000)
- Type check: `npm run typecheck` (tsc --noEmit)
- Lint: `npm run lint` (eslint + prettier check)
- Format: `npm run format`
- Test (unit): `npm run test`
- Test (e2e): `npm run test:e2e`
- Build: `npm run build`
- DB sync (dev only): `npx prisma db push`
- DB migrate: `npx prisma migrate dev --name <description>`
3. Conventions — Specific Rules, Not Generic Advice
"Write clean code" means nothing. "Named exports only" is a rule an agent can follow.
## Conventions
- Named exports only: `export function Foo()`, never `export default`
- Server components by default — add `'use client'` only for hooks/browser APIs
- Server actions in `/app/actions/` — one file per domain (auth.ts, user.ts)
- API routes in `/app/api/` — REST conventions
- Zod schema for every form and API input — no manual `as Type` assertions
- shadcn/ui components from `/components/ui/` only — extend with wrappers,
never modify the source files
- DB queries only in `/lib/db/` — never inline in components or server actions
- Error boundaries at route segment level
4. Boundaries — Three Tiers
## Boundaries
### Ask before doing
- `prisma/schema.prisma` changes — migrations are version-controlled
- New npm dependencies — check if existing package covers the need
- `next.config.ts` changes — affects entire build
- Architectural changes across multiple modules
### Never do
- Add TypeScript `any` — fix the type or ask for help
- Import from `/lib/legacy/` — being phased out, do not touch
- Use `localStorage` or `sessionStorage` directly — use `/lib/storage/client.ts`
- Hardcode env values — validate everything through `/lib/env.ts`
- Modify `/components/ui/` files — these are shadcn sources, use wrappers
5. Testing — Framework + What Not to Mock
## Testing
- Framework: Vitest + @testing-library/react
- Unit: `/tests/unit/` — pure functions only
- Integration: `/tests/integration/` — full server actions, real DB,
transactions roll back after each test
- E2E: Playwright in `/tests/e2e/`
- Never mock Prisma — use test DB with rollback transactions
- Mock external APIs with MSW (Mock Service Worker)
- Coverage: 80% for /lib/, 60% for /app/
- Always run `npm run typecheck && npm run lint && npm run test` before done
Complete Next.js App Router Template (Copy This)
# My Next.js App
## 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
## Project Structure
- `/app/` — Pages, layouts, route handlers
- `/app/actions/` — Server actions (one file per domain)
- `/app/api/` — REST API routes
- `/components/ui/` — shadcn/ui (do not modify)
- `/components/` — Custom components
- `/lib/` — Shared utilities
- `/lib/db/` — All Prisma queries live here only
- `/lib/env.ts` — Zod-validated env variables
- `/tests/` — unit/, integration/, e2e/
## Commands
- Dev: `npm run dev`
- Type check: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm run test`
- Build: `npm run build`
- DB push (dev): `npx prisma db push`
- DB migrate: `npx prisma migrate dev --name <description>`
## Conventions
- Named exports only, never default exports
- Server components by default, `'use client'` only when necessary
- All input validated with Zod before processing
- `@/` alias for all internal imports
- PascalCase for component files, camelCase for utility files
- No inline styles — Tailwind utility classes only
## Boundaries
### Ask before doing
- `prisma/schema.prisma` changes
- New npm dependencies
- `next.config.ts` changes
### Never do
- Add `any` type — fix it properly
- Touch `/lib/legacy/` — deprecated
- Use `localStorage` directly — use `/lib/storage/client.ts`
- Hardcode env values — use `/lib/env.ts`
- Modify `/components/ui/` — wrap instead
## Testing
- Vitest for unit + integration tests
- Playwright for E2E
- Never mock Prisma — use test DB with rollbacks
- MSW for external API mocking
- Run typecheck + lint + test before marking any task done
Monorepo Setup — Running Multiple Agents in Parallel
GitHub Agent HQ lets you run Claude, Codex, and Copilot simultaneously. Without scoped AGENTS.md files, two agents will edit the same file and create conflicts.
project/
├── AGENTS.md # Shared: git conventions, CI commands, global rules
├── apps/
│ ├── web/
│ │ └── AGENTS.md # "Frontend only. Don't touch /api/ or /packages/"
│ └── api/
│ └── AGENTS.md # "API routes only. Don't touch /web/"
└── packages/
└── ui/
└── AGENTS.md # "UI library only. No business logic here."
The agent reads the root file first (shared context), then the nearest scoped file (domain-specific rules). Root-level context + scoped boundaries = no cross-domain conflicts.
AGENTS.md vs CLAUDE.md vs .cursorrules — Migration Guide
If you're already using one of the older formats:
From .cursorrules:
Copy your content into AGENTS.md. Restructure into the five sections above. Delete .cursorrules or leave it — Cursor will ignore it once AGENTS.md exists.
From CLAUDE.md:
Keep CLAUDE.md if you want (Claude Code reads both). But put your main content in AGENTS.md and make CLAUDE.md a one-liner: @AGENTS.md — this tells Claude Code to read the shared file.
From copilot-instructions.md:
Keep it for non-Agent HQ Copilot workflows. Migrate your core content to AGENTS.md. Agent HQ sessions use AGENTS.md as the primary context.
The Biggest Mistakes (And How to Avoid Them)
Writing prose instead of rules
❌ "Follow best practices for error handling"
✅ "Throw typed errors in server actions, catch at the route segment error boundary"
Listing every possible command
Only include commands the agent actually uses during normal work. A 40-command list means the agent has to parse it every session — wasted context tokens.
Not updating it when the stack changes
An AGENTS.md that says "use Prisma 5" when you're on Prisma 6 will make the agent generate deprecated syntax confidently. Treat it like code — update it in the same PR that changes the dependency.
Making it too long
Under 150 lines is the target. If you're writing paragraphs, you've crossed from agent instructions into human documentation. Move that content to README.md.
Verify Your Setup
After writing your AGENTS.md, run this quick check with Claude Code or Cursor:
"Read my AGENTS.md and tell me:
1. What command do you use to run tests?
2. Where do database queries live?
3. What should you never modify without asking?
4. What validation library do you use?"
If the agent answers correctly from the file — you're done. If it gets any wrong — that section needs more clarity.
Tools That Work Well Alongside AGENTS.md
If you're building agentic workflows that go beyond single-file edits, here are two things worth setting up alongside your AGENTS.md:
MCP (Model Context Protocol) — connects Claude Code and other agents to external tools, databases, and APIs. Your AGENTS.md defines the project conventions; MCP gives agents the tools to act on them. The MCP complete guide on WebToolsHub covers setup from scratch.
Claude Code agent workflows — for multi-step autonomous tasks that go beyond what Copilot handles inline. The Claude Code skills guide covers how to structure long-running agent sessions so they stay aligned with your conventions — which is exactly what a good AGENTS.md enables.
For the broader picture of how AGENTS.md fits into a full agentic development workflow — task assignment, parallel agents, review loops — the agentic AI workflows guide on WebToolsHub covers the architecture end to end.
Quick Reference
AGENTS.md checklist:
✅ Stack section with exact versions
✅ Commands section with exact flags (not descriptions)
✅ Conventions: specific rules, not generic advice
✅ Boundaries: Ask / Never do tiers
✅ Testing: framework + what NOT to mock
✅ Under 150 lines total
✅ Committed to version control
✅ Updated in same PR as stack changes
That's the file. One-time 20-minute investment. Every agent that touches your project from now on starts with full project context.
Full guide with FAQ, Claude Fable 5 integration notes, and advanced monorepo patterns on WebToolsHub.
Top comments (0)