Next.jsとAGENTS.md — AIエージェントにWebアプリを100%理解させる方法

Haram

@haram

Next.js와 AGENTS.md — AI 에이전트가 내 웹 앱을 100% 이해하게 만드는 법

Next.jsとAGENTS.md — AIエージェントにWebアプリを100%理解させる方法

AIコーディングエージェントがプロジェクトのルールや設定を把握できず、見当違いなコードを書いた経験はありませんか？Vercelは最近、この課題を解決するためにプロジェクト情報をエージェントに確実に伝えるためのガイドブック規格「AGENTS.md」を提案しました。作成したNext.jsアプリをAIエージェント向けに最適化し、もどかしい開発フローをスムーズにするための最も簡単な方法をご紹介します。

AGENTS.mdが必要な理由：AIエージェントのための「プロジェクト説明書」

AGENTS.mdはプロジェクトのルートディレクトリに配置する軽量なMarkdownファイルです。端的に言えば、CursorやClaude Codeといったコーディングエージェントが、プロジェクトの核心となるルールや規約を把握するために最初に読み込む「説明書」の役割を果たします。

Vercelの評価によれば、プロジェクトのルートに約8KBのドキュメントインデックスを含むAGENTS.mdファイルを常に配置しておくと、エージェントのAPIテスト通過率が100%に達しました。複雑な指示を毎回検索する必要がなく、核心的な情報がエージェントのコンテキストに常に留まるため、指示の漏れやミスがなくなるのです。

一方で、必要なタイミングで外部ドキュメントを自律的に検索・読み込みさせる動的な機能の成功率は53%に留まりました。エージェントがどのドキュメントを探すべきかを判断しツールを実行するプロセスにおいて、56%の確率で呼び出し自体が漏れていたためです。結局のところ、いつでも即座に読み込める軽量なファイルを常に配置しておくことが、より強力で確実な方法といえます。

Next.js 16.2からは、このプロセスがさらに簡単になりました。プロジェクトの新規作成時からAGENTS.mdファイルがデフォルトのテンプレートに含まれるようになり、公式ドキュメントもライブラリフォルダ内にMarkdown形式で内蔵されています。おかげでエージェントは複雑なWeb検索をすることなく、プロジェクトのバージョンに最適な技術ドキュメントを即座に参照して学習できます。

サーバーのリアルタイム状態をAIと共有する — next-devtools-mcp

AGENTS.mdがプロジェクトの骨組みやルールを伝えるガイドブックなら、next-devtools-mcpは、実行中の開発サーバーのリアルタイムな状態をAIエージェントに詳細に伝える架け橋です。このツールは、マシンとツールがデータをやり取りするためのオープン標準であるMCP（Model Context Protocol）に基づいて動作します。

これを設定すれば、CursorやClaude Codeといったコーディングエージェントが開発サーバーの目と耳の代わりになります。現在発生しているビルドエラー、ターミナルのコンソールログ、ルートパス、サーバーアクション情報まで、エージェントが直接探索して分析可能です。Next.js 16.2および16.3から備わった安定したAIサポートアーキテクチャのおかげで、開発サーバーを起動しておくだけでバックグラウンドで自動的に動作します。

設定方法は非常に簡単です。プロジェクトのルートディレクトリに.mcp.jsonファイルを作成し、以下の設定を追加するだけです。

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

これで、ターミナルのエラーログをコピーしてAIのウィンドウに貼り付ける必要はありません。エージェントに「今、Webアプリでなぜエラーが出ているの？」と聞くだけです。エージェントが自らget_errorsやget_logsツールを呼び出して開発サーバーの状態を解析し、原因と解決策をわずか数秒で提示してくれるでしょう。

WebサービスをAI向けに公開する：llms.txt規格

ローカルプロジェクトだけでなく、実際に公開されているWebサイトに訪れる外部のAIエージェントへの配慮も必要です。Vercelが提案するエージェント可読性の仕様によると、Webサイトのルートディレクトリにllms.txtやsitemap.mdファイルを配置し、サイト構造をMarkdown形式で提供することをおすすめします。

llms.txtは、Web検索機能を持つAIエージェントがWebサイトを訪問した際、重く複雑なHTMLドキュメントやグラフィック要素を個別に解釈させるのではなく、核心的なテキスト情報だけを素早く把握できるようにする、いわば「AI用の地図」です。マシンにとって読みやすいWebサービスを作るための、最も簡便で効果的な手段と言えます。

実際のプロジェクトルートに配置するllms.txtファイルは、次のような直感的なMarkdown構造で構成されます。

md
# 서비스 이름

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

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

この仕様は、単にファイルを一つ置いておくだけに留まりません。AIエージェントが特定のページを呼び出す際にヘッダーにMarkdownでのレスポンスを要求したり、URLの最後に.mdを付与してアクセスしたりすることで、不必要なレイアウトをすべて取り除いた純粋なテキスト情報を出力させるガイドラインも含まれています。このようにマシンとのコミュニケーション障壁を下げる細やかな設計が、これからのWeb開発の新たな基準になるはずです。

AIエージェントと協働する最も簡単な方法

これまでのWeb開発が人にとって見やすい画面を作ることに集中していたならば、これからはAIエージェントにとっても理解しやすい構造を共に考えるべき時です。大掛かりなシステムを新規に作る必要はありません。プロジェクトのルートに軽量なAGENTS.mdファイルを一つ追加し、MCPツールを接続するだけで、エージェントとの協働生産性は大きく向上します。現在開発中のNext.jsプロジェクトに、この小さなファイルを一つ加えてみて、よりスムーズになったAIコーディングフローをぜひ体験してみてください！