概要
- Next.js 16 の新APIに対応するため、AIエージェント向けの知識付与方法を検証
- skills （スキル）と AGENTS.md （静的Markdown）の2アプローチを比較
- AGENTS.md への圧縮ドキュメントインデックス埋め込みで100%パス率を達成
- skillsは明示指示があっても最大79%、指示なしでは効果なし
- AGENTS.md 方式の利点と導入方法、フレームワーク開発者への提言
Next.js 16のAPI知識をAIエージェントに教える試み
- AIエージェント の訓練データは古くなりやすい課題
- Next.js 16 の新API（use cache, connection(), forbidden()など）は現行モデルの訓練データに未収録
- エージェントがAPIを知らない場合、誤ったコード生成や古いパターンへ退行
- 逆に古いNext.js利用時に新APIを提案されるリスクも存在
- 解決策： バージョン一致ドキュメント をエージェントに提供する仕組みの検討
知識付与の2アプローチ
- skills ：ドメイン知識をパッケージ化し、必要時にエージェントが呼び出す標準仕様
- プロンプト・ツール・ドキュメントを一体化
- エージェントが必要時に自発的に利用する設計
- AGENTS.md ：プロジェクトルートに配置し、エージェントに 常時文脈 として提供
- 任意の情報を毎ターン参照可能
- Claude CodeではCLAUDE.mdを同様用途で使用
skills方式への期待と現実
- skills での正しいコード生成を期待
- 実際は 56%のケースでskillsが発動せず
- デフォルト設定ではパス率 53%（ベースラインと同じ）
- 一部指標ではskills導入で逆に悪化（例：テストパス率）
- ツール未活用問題 は現行モデルの既知課題
明示指示の効果と危うさ
- AGENTS.md に「skillを使え」と明記で発動率95%以上・パス率79%に向上
- 指示文の微妙な違いで結果が大きく変動
- 「必ずskillを使え」→プロジェクト文脈無視でドキュメントパターンに固執
- 「まずプロジェクトを探索し、その後skillを使え」→文脈理解後にドキュメント参照で良好な結果
- 指示文の脆弱性が運用上の懸念材料
信頼できる評価方法の構築
- 初期テストは曖昧なプロンプトや訓練データに含まれるAPI中心で不適切
- Next.js 16の未学習API をターゲットにした行動ベースの評価に刷新
- connection(), use cache, cacheLife(), forbidden(), proxy.ts, cookies(), headers()などを網羅
- 各設定で複数回評価し、モデルのばらつきを排除
AGENTS.mdインデックス埋め込みの発見
- decision point （意思決定ポイント）を排除し、毎ターン情報を提供
- 圧縮8KBインデックス をAGENTS.mdに埋め込んだだけで 100%パス率
- 重要指示：「Next.jsタスクはpre-trainingよりretrievalを優先」
驚きの結果とその理由
- 4パターン比較で AGENTS.mdインデックス埋め込みが圧倒的
- skills（明示指示あり）でも79%、AGENTS.mdは100%
- 詳細：Build, Lint, Testすべてで100%達成
- 理由：
- 意思決定不要 ：常に情報が提示される
- 一貫した可用性 ：skillsは非同期ロード、AGENTS.mdは毎回プロンプトに含まれる
- 順序問題回避 ：skillsは「先に読む/後で読む」問題が発生、AGENTS.mdは不要
コンテキスト肥大化への対策
- AGENTS.md埋め込みによる コンテキストウィンドウ圧迫 懸念
- 圧縮率80%（40KB→8KB） でパス率維持
- パイプ区切り・最小構造でドキュメントインデックス化
- 例：[Next.js Docs Index]|root: ./.next-docs|...|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
- 全文埋め込み不要、インデックスとファイルパスのみで十分
導入手順
- コマンド一発でセットアップ可能
- npx @next/codemod@canary agents-md
- 実行内容
- Next.jsバージョン検出
- 対応ドキュメントを .next-docs/ にダウンロード
- 圧縮インデックスをAGENTS.mdに自動挿入
- Cursor などAGENTS.md対応エージェントで利用可能
フレームワーク開発者への提言
- skillsは 垂直的・アクション特化型 ワークフロー向き（例：バージョンアップ、App Router移行）
- 一般的なフレームワーク知識提供はAGENTS.md方式が有効
- 推奨事項
- skills改善を待たず、現時点でAGENTS.mdスニペット提供を推奨
- 圧縮重視 ：全文不要、インデックスで十分
- evals活用 ：訓練データ未収録APIで評価
- retrieval設計 ：エージェントが必要なファイルを容易に見つけられる構造を意識
- 目的： pre-training主導からretrieval主導 への転換
- AGENTS.md方式が現状最も信頼できる手法
研究・評価：Jude Gao CLI: npx @next/codemod@canary agents-md