AGENTS.md template for Next.js App Router projects (TypeScript)
An AGENTS.md for Next.js App Router codebases that tells any coding agent your commands, server and client component rules, data-fetching and caching conventions, server action safety, and what not to touch.
File in Engineering by AISkillHub Library
What it does
`AGENTS.md` is a plain Markdown file at the repository root that coding agents read for project instructions. This template is written for TypeScript projects using the Next.js App Router, where the most common agent mistakes are adding `"use client"` too high in the tree, fetching on the client what could be fetched on the server, trusting server action input, and assuming caching defaults from an older Next.js version.
**What it covers** - Commands for dev, build, lint, typecheck and tests, with placeholders for your package manager and test runner. - Server Components by default; `"use client"` only on the smallest interactive leaf. - Data fetching on the server, running independent requests in parallel with `Promise.all`. - Caching: an instruction to check the installed Next.js version before relying on caching defaults (fetch caching defaults changed in Next.js 15), and to state caching explicitly. - Server Actions and Route Handlers: validate input, check authorization inside the action, never trust hidden form fields. - Environment variables: only `NEXT_PUBLIC_` variables reach the browser; secrets never get that prefix. - Guardrails: no new dependencies or config changes without asking.
**Variables to fill** - `{{project_name}}`, `{{project_purpose}}`. - `{{pm}}`: `npm`, `pnpm`, `yarn` or `bun`. Replace `{{pm}} run` accordingly. - `{{test_command}}`: for example `{{pm}} test` or `npx vitest run`. - `{{validation_lib}}`: for example `zod`, or delete the mention. - `{{auth_helper}}`: the function your project uses to get the current user, for example `auth()` or `getSession()`.
**Using it with Claude Code** Claude Code reads `CLAUDE.md`. To share one source of truth, create a `CLAUDE.md` containing the line `@AGENTS.md`, which imports this file.
How to use it
1. Copy the file below to `AGENTS.md` at the root of your Next.js repository. 2. Replace every `{{...}}` variable (listed in the description) and delete rules that do not apply. 3. Run each listed command once to confirm it works. 4. For Claude Code, add a `CLAUDE.md` next to it containing `@AGENTS.md` so both tools read the same rules. 5. Commit both files.
Files
Save each file at the path shown, relative to your project root.