1. これは何の話？

Article Overview

Next.jsの開発元であるVercelが、コーディングエージェントにフレームワークの最新知識をどう与えるべきかについて、徹底的な比較検証を行った結果の報告です。 彼らは「Skills（必要な時にツールとしてドキュメントを呼ぶ）」と「AGENTS.md（常にコンテキストにドキュメント地図を置いておく）」の2つのアプローチを比較しました。 想定読者は、AIエージェントを開発環境に組み込んでいるエンジニアや、LLMに独自のライブラリ知識を教えたいフレームワーク作者です。 検索ニーズとしては「AIエージェント ドキュメント書き方」「AGENTS.md 効果」「Cursor ルール設定」などが挙げられます。

2. 何がわかったか

驚くべきことに、現在主流の「Skills（ツール利用）」アプローチは、AIがツールを呼ぶ判断自体を放棄するケースが多く、明示的な指示を与えない限りパス率は改善せず、ベースラインと同じ53%にとどまりました（指示を与えても79%止まり）。 一方で、プロジェクトのルートに AGENTS.md を配置し、ドキュメントのインデックス（地図）を常時プロンプトに含める「AGENTS.md」アプローチでは、パス率が100%に跳ね上がりました。 さらに、コンテキストウィンドウの圧迫を防ぐため、このインデックス情報をパイプ区切りなどで圧縮し、約40KBから8KBへと80%削減しても、なお100%の精度を維持できることが確認されました。

3. 他とどう違うのか

従来の「AIエージェント」の設計思想では、トークン節約のために「必要な時だけツールを使って情報を取る（ReActパターンなど）」が良いとされてきました。 しかし今回の検証は、その「使うかどうか判断する（Decision Point）」こと自体がボトルネックであり、エラーの原因になっていることを突き止めました。 「判断させずに、最初から地図だけ渡しておく」というパッシブ（受動的）なアプローチの方が、能動的なツール利用よりも圧倒的に高精度であるという逆説的な結果を示しています。

4. なぜこれが重要か

これは「RAG（検索拡張生成）やAgentic Workflowの設計定石」を覆す可能性がある重要な発見です。 「AIは判断が得意」という前提を疑い、「判断コストをゼロにする」設計の方が、特にコーディングのような複雑なタスクでは有効であることを実証データで示しました。 また、Next.js 16のような最新APIが含まれないモデルでも、この手法を使えば「幻覚（ハルシネーション）」を起こさずに最新のコードを書けることが証明されました。

5. 未来の展開・戦略性

今後、フレームワークやライブラリの作者は、人間用のドキュメント（READMEやDocs）とは別に、エージェント用の「圧縮されたインデックスファイル（AGENTS.md）」を提供することが標準マナーになる可能性があります。 また、IDE（CursorやVS Code）やエージェントツール側も、この AGENTS.md 標準をネイティブサポートし、ユーザーが設定しなくても自動で読み込む流れが加速するでしょう。 Vercelはすでに @next/codemod にこの機能を組み込んでおり、エコシステム全体への普及を狙っています。

6. どう考え、どう動くか

今すぐ私たちのプロジェクトでも、複雑なプロンプト指示（System Instructions）を書くのをやめ、構造化された「地図ファイル」を追加する方式へ切り替えるべきです。

指針：

  • 現在のプロジェクトに AGENTS.md（または .cursorrules 等）を作成し、主要なドキュメントへのパスと概要を記述する。
  • AIに「ツールを使え」と指示するのではなく、情報のありかを「常に視界に入れる」設計に変える。
  • コンテキストが溢れる場合は、全文ではなく「ファイルパス＋1行要約」のリストに圧縮する。

次の一歩：

  • 今日やること：自分のNext.jsプロジェクトで npx @next/codemod@canary agents-md を実行し、生成されるファイルを観察する。
  • 今週やること：CursorやClaudeで開発する際、プロンプトに長々と説明を書く代わりに、ドキュメント構造を記したファイルを1つ読み込ませて精度差を確認する。

7. 限界と未確定

  • コンテキスト長の限界: 検証は成功しましたが、大規模プロジェクトでインデックスだけでも数万トークンになる場合、この手法がどこまで通用するかは不明です。
  • モデル依存性: 今回の結果は特定のモデル（論文中では明記されていませんがClaude Code等の最新モデル想定）での結果であり、推論能力が低いモデルでも同じく「判断」を回避できるかは検証が必要です。
  • 圧縮の限界: どこまで情報を削ぎ落としてもAIが理解できるのか、その「圧縮率の限界点」はまだ明確な公式がありません。次にどう調べるかとしては、異なる圧縮フォーマットでの比較検証が必要です。

8. 用語ミニ解説

  • エージェント用マークダウン（AGENTS.md） プロジェクトのルートに置くことで、AIエージェントが自動的に読み込むコンテキストファイル。人間用ではなくAI用の「地図」として機能します。

9. 出典と日付

Vercel（2026-01-29）：https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals