Next.js and AGENTS.md — How to Make AI Agents Understand Your Web App 100%

Have you ever had an AI coding agent write incorrect code because it didn't fully grasp your project's rules or settings? To solve this, Vercel recently introduced AGENTS.md, a guidebook specification that provides agents with clear project insights. Here is the easiest way to make your Next.js web app AI-agent-friendly and smooth out those frustrating development workflows.

Why AGENTS.md is Necessary: A 'Project Manual' for AI Agents

AGENTS.md is a lightweight Markdown file placed in your project root. Simply put, it acts as a 'manual' that coding agents like Cursor or Claude Code should read first to grasp your project's core rules and conventions.

According to Vercel's evaluations, providing an AGENTS.md file in the project root with about 8KB of document indexing led to a 100% success rate in API tests for agents. Since key information stays in the agent's context rather than needing to search for complex instructions, the likelihood of errors or missed directions drops to zero.

Conversely, dynamic approaches—where the agent is instructed to search for and read external documentation in real-time—had a success rate of only 53%. This is because the agents missed the actual call 56% of the time while trying to figure out which documents to search and how to use the tools. Ultimately, having a single, lightweight, and always-accessible file is a much more robust and reliable method.

From Next.js 16.2, this process has become even easier. AGENTS.md files are now included by default in the template when you create a new project, and official documentation is embedded as Markdown within the library folder. Thanks to this, agents can immediately find and study accurate technical documentation perfectly tailored to your project version without needing complex web searches.

Sharing Real-Time Server Status with AI — next-devtools-mcp

If AGENTS.md is a guidebook for project foundations and rules, next-devtools-mcp is the bridge that delivers real-time status of your running development server to AI agents. This tool operates based on the Model Context Protocol (MCP), an open standard for data exchange between machines and tools.

Setting this up allows coding agents like Cursor or Claude Code to act as the eyes and ears of your dev server. They can directly explore and analyze build errors, terminal logs, route paths, and server action information. Thanks to the stable AI-support architecture in Next.js 16.2 and 16.3, it runs automatically in the background just by having your dev server turned on.

Setup is extremely simple. Just create a .mcp.json file in your project root and add the configuration below.

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

Now, there's no need to manually copy and paste terminal error logs into your AI window. Just ask your agent, "Why is my web app throwing an error right now?" It will automatically invoke the get_errors or get_logs tools to inspect the server state and provide the cause and solution within seconds.

Making Web Services AI-Ready: The llms.txt Standard

Beyond local projects, you also need to consider external AI agents visiting your deployed website. According to the agent-readability specification suggested by Vercel, it is recommended to place llms.txt or sitemap.md files at your website's root to provide the site structure in Markdown format.

llms.txt is a type of 'map for AI' that helps web-browsing agents quickly grasp core text information when they visit your site, instead of having to parse heavy, complex HTML or graphic elements one by one. It is the easiest and most effective way to build a machine-readable web service.

The llms.txt file placed in your actual project root is composed of an intuitive Markdown structure like this.

# 서비스 이름

> 서비스의 핵심 기능과 목적을 한 문장으로 요약합니다.

## 주요 문서 경로
- [가이드 문서](/docs): 개발자 가이드 및 설정 방법 안내
- [API 레퍼런스](/api): 외부 연동을 위한 상세 API 규격
- [요금제 안내](/pricing): 현재 플랜 정책 및 결제 정보

This specification goes beyond just creating a single file. It also includes guidelines for when an AI agent requests a specific page, such as including a Markdown response request in the headers or appending .md to the end of the URL, allowing the site to return pure text stripped of unnecessary layout. This kind of thoughtful design that lowers the communication barrier with machines will become the new standard for web development.

The Easiest Way to Collaborate with AI Agents

While web development until now has focused on creating screens that look good to humans, it is time to think about structures that AI agents can easily understand as well. Without needing to build a massive new system, simply adding a lightweight AGENTS.md file to your project root and connecting an MCP tool will significantly boost your collaborative productivity with agents. Try adding this small file to your current Next.js project and experience a much smoother AI coding flow for yourself!