Next.js AGENTS.md Practical Introduction Guide: How to tell an AI coding agent to read version-fixed documents first instead of training data

Publication date: 2026-05-01 | Category: How to use AI

1) One-line problem definition

Key takeaway: The more AI coding agents are used, the more problems they cause first, not productivity, but Outdated document memory and current version mismatch

Next.js 16.2 addresses this issue pretty head-on. According to the official document, the document that matches the currently installed version is placed in the next package, and AGENTS.md in the project root instructs the agent to read that document first. The target audience is developers, team leads, and DevEx personnel who maintain Next.js apps with coding agents such as Claude Code, Codex, Cursor, and Copilot.

The real problem is simple. If the agent only relies on Remembering self-learning data for frequently changing topics such as App Router, Server Actions, Cache Behavior, and MCP Connection, it may suggest code that does not match the current project version. The scope of this article is Next.js How to group AGENTS.md + CLAUDE.md + MCP into operational standards. Conversely, it does not cover coding performance rankings for specific models or general theory of prompts.

2) Conclusion first

Key takeaway: If you are using an AI agent in a Next.js project, it is better to fix the document priority with AGENTS.md rather than writing a long prompt. First.

• Teams that need to do this right now: Teams that use Next.js 16.x or higher, and whose agents often make routing/cache/build rules incorrectly
• Team that is still too much: Small static site with little use of agents or few Next.js changes
• My opinion: AGENTS.md is not a productivity tip, but more of a minimum safeguard to reduce version mismatch incidents

To conclude first, it is usually better to set the order of agent introduction in a Next.js project like this. 1) Prioritize version fixing documents with AGENTS.md → 2) Link team rules with CLAUDE.md or global AGENTS → 3) Link runtime state with MCP. Adding only the MCP from the beginning or, conversely, increasing the long system prompts are both inefficient.

3) Core structure decomposition

Key summary: This structure is not understood as a single document file, but must be divided into static instruction layer, agent-specific connection layer, and real-time runtime layer. It’s easy.

3-1. Static guidance layer: AGENTS.md

Next.js The core of the official documentation is simple. AGENTS.md instructs the agent to first read the version custom document in node_modules/next/dist/docs/. To put it simply, look at the manual installed in the current project rather than searching the Internet or remembering old models.

3-2. Connection layer for each agent: hierarchical AGENTS

Next.js suggests loading @AGENTS.md from CLAUDE.md for Claude Code users. The OpenAI Codex document goes one step further and describes a hierarchy that merges the global ~/.codex/AGENTS.md, the repository root, and then AGENTS.override.md from subdirectories, in that order. That is, even in the same project, common rules and directory-specific exceptions can be separated.

3-3. Real-time runtime layer: MCP

AGENTS.md is a static rule that determines “what to read first,” Next.js MCP is a real-time diagnostic layer that tells “what state the app is in right now.” Based on the official documentation, tools like get_errors, get_routes, get_page_metadata allow the agent to read errors and routes directly from the current development server.

To summarize, AGENTS.md serves as document sorting, CLAUDE.md/Codex layer serves as team rules sorting, and MCP acts as runtime sorting. Operational judgment becomes easier when these three are separated.

4) Explanation of design intent

Key takeaway: The common goal of Next.js and Codex documents is not “smarter prompts,” but Reducing contexts that are most likely to be incorrect first. It is.

Anthropic's Claude Code Best Practices clearly states that context windows fill up quickly, and that performance deteriorates as windows fill up. So, writing long background explanations in each prompt quickly runs into limitations. The direction Next.js took is the opposite. Instead of giving a long description, use and specify the exact document location very briefly

This design gains three and gives up three.

My interpretation is this. Now, the key to operating a coding agent is not “the model will take care of everything,” but structurally correcting information that is prone to error. Next.js pushes the first step to document bundling, Codex to rule layering, and MCP to runtime linking.

5) Evidence and comparison

Key takeaways: The comparison is not the agent brand, but how the document is referenced

• Next.js Basis: 16.2.4 The document is enclosed in node_modules/next/dist/docs/, and create-next-app@canary is enclosed in AGENTS.md. It explains that CLAUDE.md is automatically generated.
• Codex Evidence: The OpenAI documentation combines global AGENTS, project AGENTS, and subdirectory overrides and states that the default maximum size is 32KiB.
• Anthropic Rationale: The Claude Code article emphasizes that context windows fill up quickly, and that verification criteria and clear instructions are the greatest leverage.
• Next.js MCP Basis: The official guide allows the agent to read the real-time development server status through get_errors, get_routes, get_project_metadata, etc.

There are two numbers that are practically important. One is version 16.2.4 / lastUpdated 2026-04-10 from the Next.js document, and the other is project_doc_max_bytes default 32KiB from the Codex document. The former shows why “a document that matches the current version” is important, and the latter shows the reality that “if you write a long rules file, it will eventually break down again.”

6) Actual operation flow / step-by-step execution method

Key takeaway: Introduction is not a task of adding a lot of new tools, but rather an agent organizing what to see first and what to see later It's a task.

Check the
1. Next.js version.
   Based on the official document, the existing project must be v16.2.0-canary.37 or higher for the basic flow to work. That's right.
   

   npm ls next

2. If this is a new project, use the auto-generated flow.
   Based on the document, create-next-app@canary is equivalent to AGENTS.md Automatically generates CLAUDE.md
   

   npx create-next-app@canary

3. If it is an existing project, at least place AGENTS.md in the root.
   The key is not to write a long text, but to read the version fix document first.
   

   <!-- BEGIN:nextjs-agent-rules -->
   # Next.js: ALWAYS read docs before coding
   Before any Next.js work, find and read the relevant doc in node_modules/next/dist/docs/.
   Your training data is outdated — the docs are the source of truth.
   <!-- END:nextjs-agent-rules -->

4. When using Claude Code, CLAUDE.md is not duplicated.
   

   @AGENTS.md

5. Codex or multi-team repositories layer rules.
   Common rules down to root, specific directory exceptions down to AGENTS.override.md. Separate long documents into reference files to avoid exceeding the 32KiB default limit.
6. MCP is only attached to projects with high debugging value.
   The official guide says to add next-devtools-mcp to the root .mcp.json. Please guide us.
   

   {
     "mcpServers": {
       "next-devtools": {
         "command": "npx",
         "args": ["-y", "next-devtools-mcp@latest"]
       }
     }
   }

7. The completion criterion is whether the agent can verify it on its own.
   As advised in the Anthropic document, testing, screenshots, and error checking standards must be provided together to improve quality. It should be verifiable, for example, “After modifying get_errors, check if the result is 0.”

I think number 5 is especially important in this flow. Instead of growing AGENTS.md into an all-purpose rule file, common rules should be kept short, and exceptions should be moved to a nearby directory. will last longer.

7) Mistakes/Pitfalls

Key takeaway: Failure is usually not due to a bad model, but rather because you write an instruction file like a README or look at the MCP as a silver bullet.

• Mistake 1: Copy the entire team wiki to AGENTS.md
  Prevention: Root AGENTS leaves only priority rules and essential commands, detailed policies in separate document Separate.
  Repair: Reduce the file to a table of contents-style instructions of around 100 lines and move the details to a link/reference file.
• Mistake 2: Duplicating the same content in CLAUDE.md and AGENTS.md
  Prevention: Prioritize @AGENTS.md single-line connection as in the Next.js official example. Write
  Recovery: Remove duplicate files and consolidate them into a single source
• Mistake 3: Since MCP was attached, I thought there was no need to refer to the document
  Prevention: MCP only shows the current status and does not explain API meaning and version differences. Separate.
  Recovery: Solving runtime errors is divided into MCP, and design and API semantics checking are divided into version documents.
• Mistake 4: Just instructing “Fix it” without verification criteria
  Prevention: Self-verification criteria such as testing, expected output, screenshots, and 0 errors as recommended by Anthropic. Paste.
  Recovery: Re-do the same task, but specify completion conditions.
• Mistake 5: Putting all directory exception rules in the root
  Prevention: Separate areas with different characteristics such as payment, administrator, and experiment folders into sub-overrides.
  Recovery: By folder Introduce AGENTS.override.md to reduce rule conflicts

8) Strengths and limitations

Key takeaways: This pattern increases accuracy and reproducibility, but does not eliminate quality issues with the agent itself.

• Strengths: Reduced version inconsistency, reduced prompt length, agent common conventions, team rule layering, quick identification of runtime errors
• Strengths: Document reference possible even in offline or limited network environments
• Limitations: If dependencies are not installed, there is no document path, MCP requires the development server to be alive, and the agent does not always follow instructions perfectly
• Counterexample: If it is a very simple static site or one-time migration, there is no need to attach MCP

In other words, this structure is not a “way to make an agent a genius”, but closer to a way to lower the probability of an agent becoming stupid. I think it's worth it in that respect.

9) Points to study more deeply

Key takeaway: Rather than adding the file itself, the next step is to determine which knowledge to provide statically and which knowledge to read at runtime.

• What to write in root AGENTS.md and what to lower to lower level overrides
• Next.js How to divide problems that can be solved just by referring to the document and those that require MCP
• How to design priorities when Codex's global AGENTS and repository AGENTS conflict
• How to divide the role boundaries of CLAUDE.md, AGENTS.md, README, and CONTRIBUTING
• Test·Screenshot·0 errors How to template the same verification criteria for each task type

As a novice developer, you can understand it like this. Document file is the operation manual, MCP is the current status check window. The two are not substitutes but combination goods.

10) Execution Checklist + Author’s Perspective

Key summary: Recommended target is “Teams where agents often make mistakes”, Not recommended target is “Teams that rarely use agents”.

• There is AGENTS.md in the root, and did you read the Next.js version document first?
Was
• CLAUDE.md connected to @AGENTS.md without duplication?
• If it is a Codex or multi-team repository, have you designed a sub-AGENTS.override.md?
• Have you kept your AGENTS files short to avoid approaching the 32KiB limit?
• Have you added MCP to .mcp.json only for projects with high debugging value?
• Are self-verification standards such as testing, screenshots, and error checking provided for each agent task?

Definition of Done: When an agent starts working on Next.js, he or she first reads the version customization document, modifies it, tests it, or performs verification steps such as get_errors on his/her own, thereby establishing the primary operating standard.

My recommendation: For teams that routinely use agents in Next.js 16.x projects, it is better to immediately introduce AGENTS.md. And if error correction/routing diagnosis has a high proportion, add MCP after it. Conversely, if the site uses agents less frequently and rarely changes, it is sufficient to leave AGENTS.md alone and review the MCP later. Rather than attaching all the features at once from the beginning, the order Document prioritization → Rule layering → Runtime linking is much more stable.

Reference material

• Next.js Docs - How to set up your Next.js project for AI coding agents (2026-04-10)
• Next.js Docs - Enabling Next.js MCP Server for Coding Agents (2026-04-10)
• OpenAI Developers - Custom instructions with AGENTS.md (Confirmation date: 2026-05-01)
• Anthropic Claude Code Docs - Best Practices (Confirmation date: 2026-05-01)