Working with AI agents

What the agent readsCopy Anchor Link

AGENTS.md at the root of the project is read automatically by Cursor, Codex, GitHub Copilot and most other agents. Claude Code reads it through CLAUDE.md. It contains:

• A map of where everything lives
• The rules that must hold for billing, auth, Next.js 16 caching, the database and the UI
• Step-by-step instructions for common tasks (add a plan, gate a feature, add a page, send an email, write a post)
• The "Make it yours" task

You don't need to paste any of it into your prompt.

Good requestsCopy Anchor Link

Be specific about the outcome:

Add a "Projects" page under /dashboard where signed-in users can create and
rename projects. Only users on the Pro plan can have more than 3 projects.
Store projects in a new table.

The agent should then add a table to src/db/schema.ts, generate a migration, add the page inside <Suspense> with requireUser(), check the plan with getBillingStatus() in both the page and the server action, and run the checks.

More examples:

• "Add a yearly version of the Pro plan at $290."
• "Send a welcome email when someone confirms their email."
• "Write a blog post about how we handle invoice reminders, around 800 words."
• "The pricing section should say prices include tax."

Ask it to check its workCopy Anchor Link

Agents are told to run these before saying they're done. If one didn't, ask:

npm run typecheck && npm run lint && npm test && npm run build

npm run build matters most after changes to pages, routing or caching: some Next.js 16 errors only appear there.

Rules worth knowing yourselfCopy Anchor Link

If an agent's change breaks one of these, point it at the rule in AGENTS.md:

• Only src/lib/billing/dodo.ts talks to Dodo. Pages decide access with getBillingStatus(), never by calling Dodo.
• Pages check the user themselves (requireUser(), requireAdmin()); proxy.ts isn't a security check.
• Session, headers(), cookies() and searchParams are read inside <Suspense>.
• Never edit an applied migration.
• UI components come from src/components/ui and use the render prop, not asChild.

The note at the top of AGENTS.mdCopy Anchor Link

next dev adds a block to the top of AGENTS.md telling agents that this Next.js version differs from their training data, and to read the docs in node_modules/next/dist/docs/. It's re-added each time you run the dev server, so commit it rather than deleting it.