Ensure you are on Next.js `v16.2.0-canary.37` or later, then add the following files to the root of your project.
On Next.js 16.3 or later, just run `next dev`. When an AI coding agent is detected in the environment and no managed block is present, Next.js auto-generates `AGENTS.md` and `CLAUDE.md` at the project root. Existing `AGENTS.md` or `CLAUDE.md` files are upserted — content outside the managed block is preserved:
`AGENTS.md` contains the instructions that agents will read:
```md filename="AGENTS.md"
```md filename="AGENTS.md"
<!-- BEGIN:nextjs-agent-rules -->
<!-- BEGIN:nextjs-agent-rules -->
...
@@ -73,24 +71,31 @@ This version has breaking changes — APIs, conventions, and file structure may
...
@@ -73,24 +71,31 @@ This version has breaking changes — APIs, conventions, and file structure may
<!-- END:nextjs-agent-rules -->
<!-- END:nextjs-agent-rules -->
```
```
`CLAUDE.md` uses the `@` import syntax to include `AGENTS.md`, so [Claude Code](https://docs.anthropic.com/en/docs/claude-code) users get the same instructions without duplicating content:
```md filename="CLAUDE.md"
```md filename="CLAUDE.md"
@AGENTS.md
@AGENTS.md
```
```
<details>
### Opting out
<summary>For earlier versions</summary>
On version 16.1 and earlier, use the codemod to generate these files automatically:
We believe leaving auto-generation on is a good default—[benchmark results on nextjs.org/evals](https://nextjs.org/evals) show agents do better when they read the bundled docs. If you really want to opt out, set `agentRules` to `false` in your config:
```bash
```ts filename="next.config.ts"
npx @next/codemod@latest agents-md
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
agentRules: false,
}
export default nextConfig
```
```
The codemod outputs the bundled docs to `.next-docs/` in the project root instead of `node_modules/next/dist/docs/`, and the generated agent files will point to that directory.
### For earlier versions
On version 16.1 and earlier, use the legacy `agents-md` command, which downloads the docs to `.next-docs/` in the project root:
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in \`node_modules/next/dist/docs/\` before writing any code. Heed deprecation notices.