How to use Claude Code on a Next.js website

A Next.js website is one of the best fits for Claude Code. The whole site is code in a git repository, so Claude can read it, change it, run the build and show you a diff, and a person can review every change before it ships. Next.js has also added tools for coding agents: recent versions ship documentation that matches the installed version, write agent instructions into an AGENTS.md file, and expose the running dev server to agents through MCP.

There is one setup detail most teams miss. Claude Code reads AGENTS.md only when the project has no CLAUDE.md. If you add your own CLAUDE.md, which most website teams should, import AGENTS.md from it, or Claude never sees the Next.js instructions. This guide covers that, the checks that keep Claude honest, upgrades, the SEO limits of static export, and hosting choices, as of October 2026.

Why Next.js suits Claude Code

Claude Code is built to edit files and run commands. On a Next.js site, that covers almost everything: pages, layouts, components, styles, metadata, redirects in config, and content kept as files. There's no database hidden behind an admin screen, as there is on WordPress, unless you add one.

The weak point is version drift. Next.js's own guide for AI coding agents says agents "may rely on training data that predates the Next.js version installed in a project." Next.js changes quickly, so code that was right two versions ago can be wrong now. The fixes below all point Claude at the docs for the version you have installed.

AGENTS.md and CLAUDE.md: get both loaded

When you create a project with create-next-app, the recommended defaults now include an AGENTS.md file. For existing projects on Next.js 16.3 or later, "When next dev detects a coding agent, it creates or updates the managed instructions." The block is headed "This is NOT the Next.js you know" and tells the agent to read the bundled guide before writing code.

Claude Code's memory docs explain what it reads:

Next.js's guide simply says Claude Code reads AGENTS.md at the start of a session; Claude Code's own docs add the condition in the middle row, and say reading AGENTS.md directly needs Claude Code v2.1.277 or later. So the middle row is the trap, and the import works on any version. Your site rules belong in CLAUDE.md: brand facts, the folders that hold content, the build and test commands, and what Claude must never do. Start that file with the import, like this short example:

@AGENTS.md
# Site rules
- Run npm run build before saying a change is done.
- Never edit redirects without showing the full diff.
- Never push to main.

Run /context in Claude Code and check the memory files section to confirm both loaded. Our guide to writing a CLAUDE.md for a website covers what else to include.

Three more details from Next.js's docs:

• The block comes back. "Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean." Next.js edits only the text between its markers and leaves the rest of AGENTS.md alone.
• You can turn it off. Set agentRules: false in next.config. On the next next dev run, Next.js removes its block, and deletes AGENTS.md if nothing else was in it.
• Older versions. Next.js 16.2 has the bundled docs but doesn't write instructions. For 16.1 and earlier, Next.js documents npx @next/codemod@canary agents-md, which downloads matching docs into a .next-docs/ folder.

Give Claude a way to check its work

Anthropic's best-practices advice is to give Claude a check it can run. On a Next.js site you have several.

• The build. next build stops on errors such as code that doesn't compile. Make "the build passes" part of done, in CLAUDE.md.
• The dev server MCP. Per Next.js's MCP guide, Next.js 16 and later expose /_next/mcp from the dev server, giving agents "the running app's view of errors, routes, logs, and compilation issues." You connect it by installing the next-devtools-mcp package, for example as an entry in your project's .mcp.json. Claude Code asks for approval before it uses project-scoped servers from that file in an interactive session.
• Skills. Next.js publishes skills such as next-dev-loop, installed with npx skills add vercel/next.js --skill next-dev-loop, which "verifies changes against a running dev server using the MCP server and browser." The next-bundle-optimizer skill has an audit-only mode that reports without making changes, a good start for the work in our guide to improving page speed with Claude Code.
• Your own checks. A link checker, a script that compares titles and canonical tags before and after, and screenshots of key pages. Our QA routine before every deploy lists what to run.

Next.js's guide cites Vercel research that found a 100% pass rate with bundled documentation, compared with up to 79% for skill-based approaches. That's the vendor's own evaluation, not a promise about your project.

Upgrading Next.js with an agent

Next.js now documents an agent-guided upgrade: next upgrade --agent "checks for an available upgrade, gathers the version-matched migration guides, and hands the task to a coding agent." The docs' example runs npx next@canary upgrade --agent=latest.

Treat this like any other upgrade, because it is one:

1. Create a branch, and make sure the build passes before you start.
2. Run the upgrade and let Claude apply the migration changes.
3. Run the build, the dev server and your page checks.
4. Compare titles, canonicals, structured data and redirects against the live site on a sample of URLs.
5. Review the diff, deploy a preview, and have a person approve the merge.

The bundled docs update with the upgrade, so Claude's instructions stay matched to the new version.

SEO details that depend on how you host

Next.js "can be deployed as a Node.js server, Docker container, static export, or adapted to run on different platforms," and the features you get differ by option. Next.js's deployment page rates feature support as "All" for a Node.js server or Docker, "Limited" for static export and "Varies" for adapters.

Static export matters most for SEO. The static exports guide lists features it doesn't support, including redirects, rewrites, headers, Incremental Static Regeneration, Server Actions, Draft Mode and image optimization with the default loader. If your site is a static export, redirects in next.config won't run. They have to live in your web server or host's configuration. When we rebuilt eseospace.com as a static build, the redirects ended up in one redirects file, 235 rules as of September 2026, and that file needed the same review as code.

If you're moving URLs at all, build and test the map first; our guide to building a redirect map with Claude Code walks through it.

Where to host a Next.js site

If you deploy from git, every push can build a preview and a merge to the main branch can go live. That makes branch rules and reviews the real safety line. Our guide to Claude Code with Vercel and Netlify covers previews, rollbacks and the hosts' MCP servers.

A lesson from our own rebuild

When we rebuilt eseospace.com in June 2026, the first attempt was a clean Next.js rebuild that stripped out the old theme's JavaScript. It was abandoned on day one because it broke animations, accordions, widgets and menus. A person decided that keeping the site faithful mattered more than clean code, and the rebuild kept the theme's own scripts in a static build instead. The full story is in our eseospace.com rebuild case study.

The lesson isn't that Next.js was wrong. It's that choosing a framework, and how faithful the new site must be to the old one, is a human decision that Claude Code can't make for you. Make it before the first prompt. Our guide to rebuilding a website with Claude Code covers those decisions.

A working setup, step by step

1. Clone the repository and create a branch. Never work on main.
2. Check your Next.js version, and confirm AGENTS.md exists on 16.3 or later.
3. Write a short CLAUDE.md that starts with @AGENTS.md, then confirm both files load with /context.
4. Add an ask rule for git push and deny reads of .env files.
5. Connect the dev server MCP, or install the next-dev-loop skill.
6. Use plan mode for any change that touches more than a few files.
7. Run the build and your checks, review the diff, and deploy a preview.
8. A person approves the merge to main.

Conclusion

Next.js gives Claude Code everything it works best with: files in git, a build that fails loudly, version-matched docs and a dev server it can query. Import AGENTS.md into your CLAUDE.md, commit the managed block, make the build part of done, upgrade on a branch, and know which SEO features your hosting option supports before you move URLs. If you'd like a team to build or maintain a Next.js site this way, see our Claude Code development services. More guides are in our Claude Code Guide.

Frequently asked questions