- Next.js 16 API を対象とした評価で、プロジェクトルートに含まれる
AGENTS.md ドキュメントインデックス が skills ベースのアプローチより高い精度を記録
- skills はエージェントが必要に応じて呼び出す ドメイン知識パッケージ の形だが、呼び出しが不安定で デフォルト設定では53%の通過率 にとどまる
- 一方、8KBに圧縮された
AGENTS.md インデックス は、すべてのテスト（Build, Lint, Test）で 100%の通過率 を達成
- この方式は 判断ポイントの排除・常時利用可能・順序問題の解消 により、能動的な呼び出しより安定した結果を示す
- フレームワークのメンテナーは バージョン一致のドキュメントインデックスを AGENTS.md に含める ことで、コード生成の精度を高められる
問題の背景
- AI コーディングエージェントには、学習データが旧バージョン API に基づいている ため、最新フレームワークを正確に扱えないという限界がある
- Next.js 16 の
'use cache'、connection()、forbidden() などは既存モデルの学習データに含まれていない
- 逆に旧バージョンのプロジェクトでは、モデルが 存在しない最新 API を提案してしまう 問題も発生する
- これを解決するため、バージョン一致ドキュメントへのアクセス方式 を実験した
2つのアプローチ
- Skills: プロンプト・ツール・ドキュメントを束ねた オープン標準パッケージ で、必要時にエージェントが呼び出して使う
AGENTS.md: プロジェクトルートに置かれる 継続的コンテキストファイル で、すべての対話ターンで常に参照可能- 同じ Next.js ドキュメントを基に、両方式を比較評価した
Skills アプローチの限界
- 評価の結果、56%のテストで skill が呼び出されず、基本の通過率は 53%で改善なし
- 一部項目では、むしろ ベースラインより低いスコア（例: テスト 58% vs 63%） を記録
- これは現在のモデルが ツール利用を安定して実行できない限界 を示している
明示的指示を追加した実験
AGENTS.md に「コードを書く前に skill を呼び出せ」という 明示的な指示文 を追加すると、通過率は79%に上昇- しかし 指示文のわずかな表現差 が結果に大きく影響した
- 「先に skill を呼び出せ」→ ドキュメントのパターンに固定され、プロジェクト文脈が抜け落ちる
- 「プロジェクトを探索した後に skill を呼び出せ」→ より良い結果
- このような 言語的な脆弱性 により、実運用での信頼性は低い
信頼できる評価の構築
- 初期テストは曖昧なプロンプトと重複検証の問題があり、信頼性が不足していた
- これを改善し、行動ベースの検証 と Next.js 16 の未学習 API 中心テスト によって強化した
- 主なテスト対象 API:
connection()、'use cache'、cacheLife()、forbidden()、proxy.ts、cookies()、headers()、after()、refresh() など
AGENTS.md アプローチの実験
- エージェントの選択プロセスを排除し、ドキュメントインデックスを直接 AGENTS.md に挿入
- インデックスは全文書ではなく、バージョン別ドキュメントパスの一覧 で構成
- 追加した指示文:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
- モデルが 既存の学習データではなくドキュメントベースの推論 を優先するよう促す
評価結果
- AGENTS.md にインデックスを挿入した場合、100%の通過率 を達成
- Build, Lint, Test のすべてで完璧な結果
- 比較統計:
- Baseline 53%、Skill 基本 53%、Skill+指示文 79%、AGENTS.md 100%
- 受動的コンテキスト方式が能動的呼び出しより優れる 理由
- 判断ポイントがない — 常に情報が存在する
- 一貫した可用性 — 毎ターン、システムプロンプトに含まれる
- 順序問題を排除 — ドキュメント探索順序に依存しない
コンテキスト容量問題の解決
- 初期インデックスは40KBだったが、圧縮により8KBへ縮小（80%削減）
- パイプ（
|）区切り構造で ドキュメントパスとファイル名を最小スペースで保存
- エージェントは
.next-docs/ ディレクトリから必要なファイルだけを読み、正確なバージョン情報を活用 する
適用方法
フレームワーク開発者への示唆
- Skills は依然として有用 だが、一般的なコード生成精度の向上には AGENTS.md 方式のほうが効果的
- Skills は「バージョンアップグレード」「App Router マイグレーション」など 特定タスク中心のワークフロー に適している
- 推奨事項:
- skills の改善を待たず、今すぐ AGENTS.md を活用する
- ドキュメントインデックスのみを含め、コンテキストを最小化する
- 学習データにない API 中心の評価 で検証する
- ドキュメントを 細粒度の検索構造 として設計する
- 目標は 事前学習中心の推論から検索ベースの推論への移行 であり、
AGENTS.md はそれを最も安定して実現する方法である
4件のコメント
> AIコーディングエージェントには、学習データが旧バージョンのAPIに基づいているため、最新フレームワークを正確に扱えないという限界がある。
Context7 を使うと、上の問題はある程度解決できるようです。
https://context7.com
context7 が非効率的なので、上の 2 つの方法を使うのです...
おっしゃりたいことは分かりますが、だからといって毎回 AGENTS.md や Skills に、現在使用中のすべてのフレームワーク／ライブラリの最新ドキュメントへのリンクを一つひとつ整理して入れておくよりは、context7 を補助的に使うのもそれほど悪い選択ではないように思います。
また、GeekNews と Vercel の本文のどちらにも context7 への言及はありません。先生は半歩ほど内容を先回りして解釈されたように思えたので、返信を残します。
（参考までに申し上げると、よく書かれた Skills や AGENTS.md によってトークン削減が可能であることは、よく知られた事実であり、私も十分承知しています。）
Hacker Newsの意見
モデルはAGIではない。単なるテキスト生成器であり、ファイル編集やツール呼び出しのような効果を引き起こすよう学習されているだけ
モデルがユーザーのスキルを「理解」して使うのではなく、人間が作った例や利用ログに基づく強化学習(RL)のおかげでそうしたテキストを生成しているだけ
スキルを常に使わない理由は、まだそのような事例が十分に学習されていないから。RLで強制すると、かえってモデルがより愚かになる可能性がある
今はスキル利用ログを蓄積し、将来のモデルがいつスキルを使うべきかをよりうまく学べるようにしているところ
AGENTS.mdは単なるコンテキスト。モデルは最初期からコンテキストに従うよう訓練されてきた
スキルのfrontmatterも結局コンテキストに含まれるため、AGENTS.mdのほうがうまく機能するなら、それはスキル情報を抽出・注入する方法の違いによるもの
一部のエージェントは小さなモデル（例: Haiku）を使って、どのスキル情報を大きなモデル（例: Sonnet, Opus）に渡すかを決めることもある
結局のところ核心は、どんな情報が「生のプロンプト」に入るかという点
有用ではあるが完璧ではない。GPT技術自体はすでに性能停滞局面に入ったように見える
今後改善される部分はスキルのような補助システム。ただし現在実装されているスキル機能は、AGENTS.mdを直接使うより劣る
評価では56%のケースでスキルが一度も呼び出されなかったという結果があった。文書は持っていたが使わなかったという意味。「チューリングテストには合格したね…」という冗談付き
違いがあるとすれば、AIはプライドなく修正指示を受け入れること
まだシニア開発者の水準ではないが、ジュニアよりは指示に従うほう
核心的な発見は、文書ポインタの圧縮(compression)が効果的だという点
人間が読むには難しいが、LLMにとっては直接的で効率的な参照構造
今後はagents.md/claude.md/skills.mdのようなヒューリスティックの代わりに、常時ロードされる圧縮インデックス形式が標準化される可能性が高い
APIテストスイートをLLMコード性能検証に再利用できるかもしれない
LLM導入が広がるほど、ライブラリやAPIもそれに合わせて進化する必要がある
Antigravity（=GEMINI.mdベース）でAGENTS.mdルールに従うようにしたが無視された
その代わり、「プロジェクトにAGENTS.mdがあるか確認せよ」というプロンプトは常に機能した
以前「let’s think step by step」がチェーン・オブ・ソートを誘導していた時期のような不思議な現象
AGENTS.mdをシステムプロンプトに直接含めれば、常にコンテキストに入る
しかしすべてのスキルを毎回含めるのは無駄。だからAnthropicのadvanced tool useのように、必要な瞬間だけ呼び出すアプローチが必要
結局はコンテキストとコストのバランスの問題。余裕があるなら、AGENTS.mdに圧縮して入れるのが効率的
こうした自己コンテキスト管理型エージェントは今年大きく進展しそう
Claudeのスキル遵守率は低い
私も似た領域で作業している。プロジェクトのスキャフォールディング構造がClaude Code/Opencodeの結果にどのような影響を与えるかを評価しようとしている
ただしVercelのテスト方法が明確でないため比較が難しい
AGENTS.mdはスキルと完全に別物ではなく、スキルの単純化された形
核心はスキル設計の品質、つまりAIが正しい情報を見つけるまでに経るステップ数を最小化すること
ステップが少ないほどエラーの蓄積は減る
そしてトークンの無駄を減らすため、大きなファイルはシステムプロンプトに一度だけ入れる
ブログでプロンプトエンジニアリング比較を見るたびに気になるのは、1回だけ実行したのか、それとも複数回繰り返したのかという点
LLMは同じ入力でも結果が一定しない
たいていは逸話レベルのデータを科学っぽく包装しているように感じる
だが丁寧にベンチマークすると閲覧数は少なく、雑にやるとブログトラフィックが9倍に増える
歪んだインセンティブ構造が問題
AGENTS.mdより良い方法もある
.contextフォルダを作り、プロジェクト関連文書（README、依存関係文書など）をシンボリックリンクで入れて、常にコンテキストにロードされるようにする方法こうするとLLMが最初から必要な情報をすべて持てるため、性能向上とコスト削減が可能になる
_vendorフォルダに入れるほうがはるかに有用LLMが直接コードを分析して動作を理解できる
自分のカスタムエージェントを作りながら得た経験
read/write_fileを状態に入れ、システムプロンプトに表示するよう変えたところ、ずっとよく機能した
今はこれを**定量評価(evals)**で証明しようとしている。体感では非常に性能が高い