ハクソク

世界を動かす技術を、日本語で。

AGENTS.mdはエージェント評価においてスキルを上回る

116日前原文(vercel.com)

概要

  • 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

Hackerたちの意見

評価ケースの56%では、そのスキルは一度も使われなかった。エージェントはドキュメントにアクセスできたけど、使わなかったんだ。エージェントはチューリングテストを通過した...

└

AIですらマニュアルを読まないんだね。

いつも思うんだけど、いろんなプロンプトエンジニアリングを比較するブログ記事って、一回だけテストしたのか、それとも何回もやったのか気になるんだよね。LLMは同じタスクに対して一貫性がないからさ。もちろん彼らもそれに気づいてると思うけど、テスト方法についての詳細が全然足りないんだよね。

└

これには本当にイライラする。反証不可能で非決定論的な結果ばかり。これらのことは（せいぜい）逸話や雰囲気が科学やエンジニアリングとして提示されてるだけなんだよ。

└

この理由で、ベンチマークを取るときはいつもたくさんの重複実行をする習慣があるんだ。自分がバカみたいだなと思うのは、リアルな信頼区間で1回ベンチマークを取ってる間に、10回のクソみたいなベンチマークを取ったり、1回のクソみたいなベンチマークと9倍のブログスパムを作れたってこと。歪んだインセンティブが私たちを支配してるね。

何か見落としてる？明らかに、システムプロンプトみたいなものでコンテキストを直接含めれば、100%の確率で文脈に入るよね。エージェントのスキルを全部取り込んで、それをエージェントに渡せば（システムプロンプトとかで）、もっと確実に指示に従うはず。でも、ある時点でスキルを使わなきゃいけないんだ。毎回コンテキストに含めるのは無駄だし、できないこともあるからね。これが、Anthropicが高度なツール使用を進めてる理由でもあるんだ。参照: https://www.anthropic.com/engineering/advanced-tool-use。すべてはコンテキストとコストのトレードオフだよ。明らかに、コンテキストの予算があれば、できるだけ直接含めればいいんだ（この場合、AGENTS.mdに圧縮する）。

└

スキルが登場する前から、約1年間シンボリックエージェントファイルをハッキーなワークアラウンドとして使ってたんだけど、異なるタスクのために追加の「コンテキスト」を読み込むのに役立つかもしれない。正直、これがうまくいってるから、あまり変更する必要を感じてないんだよね。

└

これがRLMメソッドがうまく機能する理由の一つなんだ。全体の環境で必要なだけの情報にアクセスできるけど、現在のタスクに関連するものだけが文脈に入るんだ。それが100%の確率で出てくる。損失のある「メモリ」圧縮や要約技術、確率的エージェントスキルの実装とは違ってね。エージェントが自分のコンテキストを管理するのは、非推論から推論チャットへの飛躍と同じくらい非常に役立つんだ。まだメモリや統合、他のLLMの弱点には問題があるけど、エージェントは今年すごく役立つようになると思うよ。

└

明らかに、システムプロンプトのようなものでコンテキストを直接含めれば、100%の確率で文脈に入るよね。スキルがモデルにどうやって通知されると思う？何らかの形でコンテキストに含まれてるんだ。この部分が面白いのは、AGENTS.mdに情報を（比較的単純に）圧縮するだけで、スキルが実装されるよりも良く機能するように見えることだね。

└

あなたの言ってることは間違ってないよ。両方を少しずつ求めてるんだよね。1. 特定のコンテキストを強制的に入れたい、質問や非決定性はなしで（インデックスやスパークノーツみたいに）。これは条件付きでできるけど、アクセスされるファイルや他の「コンテキスト」に基づいてルールを作る必要がある。2. クリーンに保ち、必要なときだけ有用なコンテキストを提供したい（スキル、検索、MCP; そしてこれら全ての周りに探査/クエリ/圧縮メカニズムが必要。ラルフ・ウィグガムが一例だね）。

└

私の読みでは、ドキュメントの目次をマークダウンでコピーしてリンクを付ける方が、目次へのリンクを渡して読むように指示するよりもかなり効果的だった。これは納得できるよね。そして、それを証明する数字もある。

└

同感だわ。Vercelはスキルとコンテキストの設定を混同してると思う。だから、評価が全然誤解を招くもので、全く異なる2つのユースケースをテストしてるんだよね。要するに、Vercelは両方のファイルを使うべき。agents.mdはスキルと組み合わせて使うものだし、両方の機能には全く違う目的があるんだ。

└

その通り、結果は完全に予想通りだよ。記事でも、圧縮されたインデックスの出力品質がどうなるかわからないって言ってるし、こういう圧縮には常に懸念があるよね。スキルはまた別の、違う種類の圧縮なんだ。圧縮率がかなり高くて、品質に悪影響を与える可能性が低いと思うけど、その代わりにいつも呼び出されるわけじゃないってことがデメリットだね。

└

確かに、Vercelはエージェントのポイントを完全に見逃してるみたいだね。Claude Codeでは、開発者が望むときにエージェントを呼び出せて、ファイルの内容をプロンプトのコンテキストとしてコピーするんだ。

記事ではAGENTS.mdをスキルとは別のものとして提示してるけど、実際には同じ概念の簡略化されたインスタンスなんだ。彼らのAGENTS.mdアプローチは、AIにタスクを実行するための指示がどこにあるかを教えてる。それがスキルだよ。期待してるのは、スキルの設計が良くなることで、AIの初期状態と正しい情報の間のステップや決定を最小限に抑えること。遷移が少ないほど、エラーが重なる可能性も少なくなるからね。

└

うん、今はそれを分けてるよ。1. ルールベースのシステムと「コンテキスト」を使って強制的にシステムプロンプトに入れるもの。2. エージェントに調べさせたり発見させたりするもの。メッセージ部分に入るものも制限して、大きなトークンを消費するものはシステムプロンプトに移動させて、一度だけ表示されるようにしてる。特にread/write_fileが目立つね。

これが広く知られているかはわからないけど、AGENTS.mdよりもずっと良いことができるよ。.contextというフォルダを作って、プロジェクトに関連するものをそこにシンボリックリンクすればいいんだ。例えば、使っている依存関係のREADMEや重要なドキュメントとかね。それからツールを設定して、AGENTS.mdのように常に.contextをコンテキストに読み込むようにすれば、LLMが最初から必要な情報を全部持ってることになる。パフォーマンスがずっと良くなって、コストも安く、ミスも減るよ。

└

でも、目標はコンテキストスペースを膨らませないことだよ。ここで「無駄な」情報を提供することでコンテキストを「浪費」してるんだ。代わりに彼らがやったのは、ドキュメントのインデックスをコンテキストに入れること。そうすればLLMがドキュメントを取得できる。これはスキルと同じアイデアだけど、エージェント的な部分がない方がうまくいくらしい。さらに、ドキュメントを指し示すきれいなインデックスを持つ代わりに、圧縮したんだ。

└

安い？毎回、エージェントが取り組んでいるタスクに関連しているかどうかに関わらず、すべてのドキュメントをコンテキストに読み込むの？どうやって？私はむしろ、Claude.mdやAgents.mdで関連するドキュメントの場所を指摘して、必要なときだけエージェントに読ませる方がいいな。

└

これはかなり悪いアイデアだね。コンテキストのサイズと品質を制御するためには、最適化された1つのファイルを与える必要があるよ。トークンを無駄にしたくないし、大きなファイルは効果が薄れるってClaude Codeのブログでも言われてるしね。

重要な発見は、「ドキュメントポインタの圧縮」が機能するってこと。人間にはほとんど読めないけど、LLMにとっては直接的で効率的に関連してる（直接参照 -> 参照対象、言語の冗長さなしで）。これにより、常にコンテキストに読み込まれる（圧縮された）インデックス形式が、agents.md/claude.md/skills.mdの周りのヒューリスティックを置き換えることになると思う。今年中にインデックスと参照ドキュメント（特に用語の一致）の両方の正規化が進むと賭けるよ。おそらくサイドの問題として、APIがテストスイートを再利用してLLMのコードタスクのパフォーマンスを比較するための検証に使えるかも。LLMは大きな採用波を生み出すから、ライブラリやAPIはそれに乗る方法を学ばないと、人間の使用に制限されちゃうよ。

└

圧縮されてるって言うけど、これって単に「ミニファイ」じゃない？

obra/superpowersのPreSession Hookは、スキルを使うことを正当化するためのロジックを追加しながらこれを注入するんだ。> 「もしスキルがあなたのやってることに1%でも適用される可能性があるなら、絶対にそのスキルを呼び出さなきゃいけない。もしスキルがあなたのタスクに適用されるなら、選択肢はない。必ず使わなきゃいけない。」これでスキルの過剰な起動が起こるかもしれないけど、関連するスキルがあれば、使いたいと思うんだ。私にはうまくいってるよ。

└

いつも「Xをするためにスキルを呼び出して、次にYをするためにスキルを呼び出す」って言ってる。これ、結構うまくいくよ。

まず、Vercelの仕事は素晴らしいね！特にevalsの設定には感心したよ（evalsはどのプロジェクトでも一番過小評価されてる部分だと思う）。それから、結果には驚かないけど、システムプロンプトにインデックス（私の場合はJSON構造の目次）を常に含めるとパフォーマンスが確実に上がるのを見てきたよ。コーディングエージェント以外でも（クラシックなドキュメント検索みたいな）これを適用すると、すごくうまくいくんだ！

あー、これスケールが悪くてコンテキストウィンドウが膨らむね！MCPサーバーを作って、埋め込み検索やエージェント検索をフレームワークのドキュメントにサブエージェントでやらせればいいんじゃない？最後に、AGENT.mdにそのMCPを使って情報を探す指示を追加して。

問題は、Agents.mdが初回読み込み時にしか読まれないことだね。一度コンテキストが大きくなりすぎると、エージェントはmdファイルを再読み込みしないから、Agents.mdの情報を失ったり忘れたりしちゃうんだ。

└

なんで初回のタスクや2つのタスクを超えて同じセッションを再利用しようと避けるの？

└

他のコメントでは、Agents.mdがシステムプロンプトに読み込まれて、コンテキストから出ないって言ってるけど、過剰なコンテキストは避けた方がいいよ。