AIエージェントに高度な推論や複雑な「スキル」を習得させるよりも、ルートディレクトリに置かれた1つのテキストファイルの方が遥かに高いパフォーマンスを発揮する。Vercelが公開した最新の検証結果は、過熱するAIエージェント開発のトレンドに冷や水を浴びせると同時に、エンジニアリングの本質的な問いを我々に突きつけている。

AD

最新フレームワークの壁：なぜAIは「壊れたコード」を書くのか

ソフトウェア開発の現場において、AIエージェントはもはや不可欠な存在だ。しかし、開発者が直面する最大の壁は、モデルの学習データが「古くなる」という不可避の宿命である。

例えば、Next.js 16で導入された 'use cache' ディレクティブや、動的レンダリングのための connection() API、あるいは forbidden() や unauthorized() といった新しい関数群は、現在の主要なLLM（大規模言語モデル）の学習データには含まれていない。その結果、エージェントは最新のAPIを知らずに、古いパターンに基づいた動作不良のコードを生成したり、存在しない古いAPIを捏造したりする「ハルシネーション」を引き起こす。

この問題を解決するため、これまで業界が賭けていたのは「スキル（Skills）」というアプローチだった。これはAnthropicが提唱したオープン標準であり、特定のドキュメントやツール、プロンプトをパッケージ化し、AIエージェントが必要に応じて「能動的に」それらを呼び出す仕組みだ。

しかし、VercelによるNext.js 16 APIを用いた厳密な評価の結果、この洗練されたはずの仕組みに重大な欠陥があることが判明した。

成功率100%対53%：スキルシステムが敗北した理由

Vercelが行った検証結果は、驚くべきものだった。ドキュメントを一切与えない「ベースライン」でのテスト合格率が53%だったのに対し、高度なスキルシステムを導入しても、合格率は53%のまま、一切向上しなかったのだ。

なぜこのような事が起こったのか？理由は極めて単純だ。「エージェントがスキルを呼び出さなかったから」に外ならない。

Vercelのデータによれば、検証ケースの56%において、エージェントは利用可能なスキルがあるにもかかわらず、それを一度も使わずにタスクを完了させようとした。モデルは「自分はNext.jsを知っている」という事前学習に基づく過剰な自信を持ち、最新のドキュメントを参照する必要性を認識できなかったのだ。

「必ずスキルを呼び出せ」という明示的な指示をプロンプトに加えることで、合格率は79%まで上昇した。しかし、ここでも新たな問題が浮上した。指示の「言い回し」ひとつで、AIの挙動が劇的に変わってしまう脆弱性である。

  • 「必ずスキルを呼び出せ」と指示した場合： エージェントはドキュメントの読み込みを優先するあまり、プロジェクト全体の文脈（既存のファイル構成など）を見失う傾向があった。
  • 「プロジェクトを探索してからスキルを呼び出せ」と指示した場合： 全体像の把握は進むが、今度はスキルの呼び出しを忘れるケースが増え、結果が不安定になった。

こうした「能動的な判断」をエージェントに委ねるアプローチの限界に対し、Vercelが提示した解決策が、極めて原始的とも言える「AGENTS.md」だった。

AD

「受動的コンテキスト」という逆転の発想

AGENTS.mdとは、プロジェクトのルートディレクトリに配置されるシンプルなMarkdownファイルだ。このファイルの内容は、AIエージェントが動作するたびに、全てのターンのシステムプロンプトに自動的に組み込まれる。

VercelはこのAGENTS.mdに、Next.js 16のドキュメントインデックスを直接埋め込んだ。その結果、テスト合格率は100%に達した。 ビルド、リンターのチェック、テストコードの実行という全てのフェーズにおいて、一分の隙もない完璧なスコアを叩き出したのだ。

この劇的な差を生んだ要因は、主に以下の3点に集約される。

  1. 意思決定ポイントの排除: エージェントは「ドキュメントを見るべきか否か」を判断する必要がない。情報は最初から目の前に置かれている。
  2. 一貫した可用性: スキルが非同期で読み込まれるのに対し、AGENTS.mdの内容は常にコンテキスト内に存在する。
  3. シーケンス問題の解消: 「探索か、読み込みか」といった実行順序に悩む必要がなく、既存のコードと最新の仕様を同時に参照できる。

8KBに凝縮された「知のインデックス」

しかし、膨大なドキュメントをそのままAGENTS.mdに詰め込めば、コンテキストウィンドウが圧迫され、コスト増と精度の低下を招く。ここでVercelが採用したのが、高度な「圧縮」技術だ。

彼らは元々40KBあったドキュメントインデックスを、特定の記法（パイプ区切りのリスト形式など）を用いることで8KBまで圧縮した。これは単なる情報の要約ではなく、エージェントが「どのファイルに何が書かれているか」を把握するための最小限の地図である。

Markdown

[Next.js Docs Index]|root: ./.next-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}

Vercelが使用した圧縮インデックスの例。エージェントはこのインデックスを見て、必要な時だけ .next-docs/ ディレクトリ内の詳細ファイルを読みに行く。

この「地図」を常に持たせることで、エージェントの推論を「事前学習ベース」から「リトリーバル（検索）ベース」へと強制的にシフトさせることに成功したのである。

AGENTS.mdは業界標準へ：AAIFの胎動

Vercelのこの試みは、単一企業の工夫に留まらない。2025年12月、Linux Foundationの下に設立された「Agentic AI Foundation (AAIF)」により、AGENTS.mdは公式な業界標準としての道を歩み始めている。

この基盤には、OpenAI、Anthropic、Google、Microsoft、そしてBlockといった、AI業界の競合他社が異例の結集を果たしている。AAIFが推進する3つの柱は以下の通りだ。

  • Model Context Protocol (MCP): Anthropicが開発した、モデルと外部データを接続するための標準プロトコル。
  • Goose: Block（旧Square）が提供する、エージェントのワークフローを構築するためのフレームワーク。
  • AGENTS.md: プロジェクト固有の指示やコンテキストを記述するための標準フォーマット。

すでに6万件以上のオープンソースプロジェクトがAGENTS.md（あるいはClaude Codeにおける CLAUDE.md）を採用しており、CursorやDevin、GitHub Copilot、Gemini CLIといった主要なエージェントツールがこれをネイティブにサポートしている。

これは、AIコーディングのパラダイムが「モデルの賢さに依存する」段階から、「エージェントが読みやすい形でプロジェクトを構造化する」段階へと移行したことを意味している。

AD

実践：あなたのプロジェクトにAGENTS.mdを導入する

もしあなたがNext.jsを使用しているなら、この恩恵を今すぐ享受できる。Vercelは公式の codemod パッケージを通じて、AGENTS.mdの自動生成コマンドを提供している。

ターミナルで以下のコマンドを実行するだけで良い。

Bash

npx @next/codemod@canary agents-md

このコマンドは以下のプロセスを自動で実行する。

  1. プロジェクトで使用されているNext.jsのバージョンを特定。
  2. そのバージョンに合致した公式ドキュメントを .next-docs/ ディレクトリにダウンロード。
  3. エージェントが最適に参照できる「圧縮インデックス」を生成し、AGENTS.md に注入。

これにより、Next.js 16の新しいAPIである after() や updateTag()、あるいは proxy.ts によるプロキシ設定など、モデルが本来知らないはずの最新仕様についても、AIエージェントは完璧に使いこなすことができるようになる。

AIネイティブ開発の「真の姿」

Vercelの検証結果は、AIエージェントを「魔法の箱」として扱うのではなく、適切な「コンテキストの設計図」を与えることの重要性を証明した。

複雑なツール呼び出しや高コストな再学習に頼る前に、まず「エージェントにとって最もアクセシブルな場所に、最も整理された情報を置く」という、極めてドキュメンテーションに近いアプローチが最強の武器となる。

「スキルの習得」という能動的なプロセスは、将来的にモデルがさらに進化すれば洗練されていくかもしれない。しかし、今この瞬間に最高の結果を求めるのであれば、AGENTS.mdという名のシンプルなテキストファイルこそが、AIエージェントの性能を100%引き出すための鍵となるだろう。

Sources