Next.js Agent Rules

A React framework for full-stack web applications.

Overview

Next.js keeps its detailed development guide on the canary branch, with CLAUDE.md linked to AGENTS.md. The file covers iteration, tests, contributor permissions, source context, and skills for runtime and release work.

Scope layering Verification by change type Pointing at the source of truth Context budgeting Router files Contribution etiquette

Documents

├── 
├──  · symlink → AGENTS.md
├── .agents
│   └── skills
│       └──  — Specialized development and release skills
├── .github
│   ├── 
│   ├──  · symlink → AGENTS.md
│   └── 
├── packages
│   └── next
│       └── 
├── turbopack
│   ├── 
│   └──  · symlink → AGENTS.md
└── README.md — README files along the path to the edited directory

Techniques in this file

01 / Scope layering

Distinguish contributor roles before public actions

The pull-request section distinguishes branches owned by Vercel from external forks. It assigns different authorship permissions to those cases and points to the repository’s pull-request template.

304Check and see if you are creating a fork PR or a branch PR.305Branch PRs are PRs where the branch is part of the `vercel/next.js` repository. These PRs are created by Vercel employees.306Fork PRs are external contributions created by pushing commits to any fork repository that is not owned by `vercel` on GitHub.307 308- You cannot write full descriptions for fork PRs where the merge target is `vercel/next.js`.309- You can write descriptions for branch PRs and local commits.310- You can write titles and messages for local commits.311- You can assist the user in translating their descriptions to English.312 313You must inform the user that you are not allowed to write pull request descriptions for external contributions. Refer to the guidelines in `.github/pull_request_template.md`.314While you cannot write the full description for the user, you may offer to help review the description, or provide helpful technical details. You can provide them a link to the GitHub URL to create the PR.

02 / Verification by change type

Match verification to mode and bundler

Four test commands cover development and production under both Turbopack and Webpack. The result must match the runtime combination being changed.

138**Test commands by mode:**139 140- `pnpm test-dev-turbo` - Development mode with Turbopack (default)141- `pnpm test-dev-webpack` - Development mode with Webpack142- `pnpm test-start-turbo` - Production build+start with Turbopack143- `pnpm test-start-webpack` - Production build+start with Webpack

03 / Pointing at the source of truth

Explain false negatives from ad hoc type checks

The type-checking guidance explains why a custom config can miss repository augmentations and pass while CI fails. It illustrates the gap using the required NODE_ENV type on process environment values.

237Type-check with the repo's own commands. `pnpm typescript` runs `tsc --noEmit` against the root `tsconfig.json`, which includes `scripts/**/*.js` and loads this repo's type augmentations. A hand-rolled `tsconfig` pointed at a single file misses those augmentations and will report clean while CI fails. For example `NodeJS.ProcessEnv` is declared in `packages/next/types/global.d.ts` with `NODE_ENV` required, so a plain `Record<string, string>` is not a valid `env` for an `execa` call.

04 / Context budgeting

Bound repeated reading and expensive reruns

The context section directs large-file reads toward targeted ranges and treats generated files as search-only. Build and test logs are captured once and analyzed without rerunning unchanged commands.

446**Reading large files** (>500 lines, e.g. `app-render.tsx`):447 448- Grep first to find relevant line numbers, then read targeted ranges with `offset`/`limit`449- Never re-read the same section of a file without code changes in between450- For generated files (`dist/`, `node_modules/`, `.next/`): search only, don't read451 452**Build & test output:**453 454- Capture to file once, then analyze: e.g. `pnpm build 2>&1 | tee /tmp/build.log`455- Don't re-run the same test command without code changes; re-analyze saved output instead

05 / Router files

Load specialized workflows conditionally

The specialized-skills section assigns deeper workflows to named skills while retaining baseline build, test, and iteration policy in the root guide. This separates everyday rules from occasional procedures.

429Use skills for conditional, deep workflows. Keep baseline iteration/build/test policy in this file.

06 / Contribution etiquette

Explain the trust boundary when adopting fork work

The adoption workflow ties review to an exact head SHA and treats internal-branch CI as a grant of secret access. The guide requires reading the full diff and an interactive confirmation before adoption.

331**Adoption grants the contributor's code access to repository secrets**, because CI trusts branches inside `vercel/next.js`. Anything in the diff that runs during install, build, or test can exfiltrate them. The script requires an interactive confirmation that names the author, shows the exact head SHA, and lists every touched file; never bypass it, and never adopt a PR whose full diff has not been read. The file list is deliberately unranked, since a payload can sit in any fixture or source file and calling some paths risky would imply the rest are safe.