要約
- Next.js 16の新APIは学習データに含まれないため、エージェントが古いパターンを出したり、存在しないAPIを提案する問題がある。そこで、バージョン一致のドキュメントをエージェントに渡す方法を評価した。
- 比較したのは「スキル（必要時に呼び出すドキュメント束）」と「AGENTS.md（常時コンテキストに置くドキュメント索引）」の2方式。スキルは未呼び出しが多く、明示指示で改善したが文言に強く依存し、運用が脆いことが分かった。
- 評価は曖昧なテストを修正し、学習データにないNext.js 16 APIに焦点を当てた信頼できるスイートで実施。結果、AGENTS.mdの索引方式が最も高い成績（パス率100%）になった。
- 著者の結論は、一般的なフレームワーク知識は「受動的コンテキスト（AGENTS.md）」が「能動的取得（スキル）」より現状優位で、スキルは「ユーザーが明示的にトリガーする縦型の作業」に向くという整理。
評価設計（要点）
- 初期テストの曖昧さやリークを解消し、挙動ベースのアサーションに変更。
- 学習データにないNext.js 16 APIに焦点を当てて評価。
- 代表的な対象APIには
connection()、'use cache'、cacheLife()/cacheTag()、forbidden()/unauthorized()、proxy.ts、cookies()/headers()、after()/updateTag()/refresh() が含まれる。
結果（主要数値）
- ベースライン（ドキュメントなし）: 53%
- スキル（デフォルト）: 53%（改善なし）
- スキル + 明示指示: 79%
- AGENTS.md 索引: 100%（Build/Lint/Testすべて100%）
スキル方式の課題
- 56%のケースでスキルが呼び出されず、改善が出なかった。
- 指示を足すとトリガー率は上がるが、文言が変わるだけで行動が大きくぶれる（「先にスキル」だとプロジェクト文脈を取りこぼす等）。
AGENTS.md 方式が効いた理由（著者の仮説）
- 参照の「意思決定点」が消えるため、使われないリスクがない。
- 常時プロンプトに入るため、アクセスが安定する。
- 参照順（先に探索か、先にドキュメントか）の問題が起きない。
文脈肥大への対策
- ドキュメント索引の注入量は約40KBから8KBへ圧縮（約80%削減）し、成績は維持。
- 圧縮された索引はパイプ区切りの最小形式で、必要なときに
.next-docs/ 内の該当ファイルを読みに行く前提。
導入手順（記事にある方法）
npx @next/codemod@canary agents-md- 実行すると、Next.jsバージョン検出、対応ドキュメントの取得、AGENTS.mdへの索引注入を行う。
フレームワーク作者への示唆（記事の提案）
- 一般知識はAGENTS.md方式が有効。スキルは「アップグレード」「移行」「ベストプラクティス適用」など明示トリガーの作業に向く。
- ドキュメントは「全文投入」より「参照しやすい索引 + 取得可能なファイル」に設計する。
- 学習データにないAPIを含む評価で、手法の実効性を検証する。