ご提示いただいた「Agent Skills」セクションは、すでに読みやすく整理されており、余計な改行・スペース・記号も削除されています。 内容自体も日本語として自然で、専門用語（Speed → 走る速度など）も適切に訳されています。 --- ### 追加調整のご提案 1. **統一感** - 各スキル名をカタカナや漢字混合で統一すると更に見やすくなります。 例：`Speed → スピード（走る速度）` 2. **項目の強調** - `Effect`, `Cooldown`, `Duration` の語尾に「秒」などを付けて、単位が明示的になるようにすると読者にとって親切です。 3. **インデント** - マークダウン内でのインデントは可読性向上のために 2〜4 スペース程度で統一すると良いでしょう。 --- もし上記の点を含めてさらに微調整をご希望でしたら、お知らせください。既存の構成をそのまま残しつつ、必要な変更のみを反映いたします。

私たちは skills がコーディングエージェントにフレームワーク固有の知識を教えるための解決策になると期待していました。Next.js 16 の API を対象にした評価（eval）を構築したところ、予想外の結果が出ました。

• AGENTS.md に直接埋め込んだ 8 KB の圧縮済みドキュメントインデックスは 100 % の合格率を達成しました。
• 一方、skills を使っても最大で 79 % とそれほど高くなく、明示的に「skills を使うよう指示」を与えない限り、skills はほとんど効果がありませんでした。

ここでは試したこと、学んだこと、そして Next.js プロジェクトにどう適用できるかを紹介します。

---

解決しようとしていた問題

AI コーディングエージェントはトレーニングデータに依存しているため、時代遅れになる可能性があります。
Next.js 16 では

use cache

、

connection()

、

forbidden()

といった API が追加されましたが、現在のモデルのトレーニングデータには含まれていません。その結果、エージェントは誤ったコードを生成したり、古いパターンに戻ってしまいます。

逆に、旧バージョンの Next.js を使用している場合、モデルがまだ存在しない新しい API を提案することもあります。そこで、バージョンに合わせたドキュメントへのアクセスをエージェントに提供したいと考えました。

---

エージェントへフレームワーク知識を教える 2 つのアプローチ

1. skills
   skills はコーディングエージェントが利用できるドメイン知識をパッケージ化するオープンスタンダードです。prompt、ツール、ドキュメントをまとめておき、必要に応じてエージェントが呼び出せます。フレームワーク固有のヘルプが必要なときに skill を呼び出し、関連する docs にアクセスできるという考え方です。

2. AGENTS.md
   AGENTS.md はプロジェクトルートに置く Markdown ファイルで、エージェントに永続的なコンテキストを提供します。AGENTS.md に書いた内容は毎回のやり取りで利用可能で、エージェントが「読み込む」かどうか判断する必要はありません。同じ目的で Claude Code は CLAUDE.md を使用しています。

Next.js 用の skill と AGENTS.md ドキュメントインデックスを作成し、それらを評価スイートに通してどちらが優れているか確認しました。

---

まず skills に投資した理由

skills は適切な抽象化だと感じました。フレームワークのドキュメントを skill としてパッケージ化し、Next.js タスクで作業するときにエージェントがそれを呼び出すことで正しいコードが生成できるはずです。関心事の分離がクリーンで、コンテキストオーバーヘッドも最小限。必要なときだけロードされます。さらに

skills.sh

に再利用可能な skill が増え続けています。

Next.js タスクに遭遇した際に skill を呼び出し、バージョンマッチドドキュメントを読み取り正しいコードを生成すると期待しました。そして評価を実施しました。

---

skills が信頼できるほどトリガーされなかった

評価ケースの 56 % で skill が一度も呼び出されませんでした。エージェントはドキュメントにアクセス可能だったものの、利用しませんでした。skill を追加してもベースラインと比べて改善は見られませんでした。

構成	合格率
ベースライン（docs なし）	53 %
skill（デフォルト挙動）	53 % (+0 pp)

詳細な Build / Lint / Test の分解では、skill が一部の指標でベースラインより悪化していることも確認できました（テストで 58 % 対 63 %）。環境に存在する未使用の skill がノイズや注意散漫を招いている可能性があります。

これは私たちだけのケースではありません。現在のモデルはツール利用が不安定という既知の制限があります。

---

明示的な指示で改善したものの、表現が脆弱だった

AGENTS.md に「skill を使うように」明示的に指示を追加しました：

「コードを書く前にプロジェクト構造を探索し、その後 nextjs‑doc skill を呼び出してドキュメントを参照してください。」

これでトリガー率が 95 %+ に上昇し、合格率も 79 % へ向上しました。しかし指示の表現によってエージェントの挙動に大きな差が出ることに気付きました。

指示	挙動	結果
「You MUST invoke the skill」	ドキュメントを先に読む、パターンに固定される	プロジェクトコンテキストを見逃す
「Explore project first, then invoke skill」	まずメンタルモデルを構築し、ドキュメントは参照用に使う	より良い結果

use cache

の指示テストでは、「invoke first」のアプローチで正しい

page.tsx

を作成したものの、必要な

next.config.ts

の変更を完全に見逃しました。「explore first」では両方取得できました。

小さな表現の違いが大きく振る舞いを変えるため、この手法は本番環境で脆弱だと感じました。

---

信頼できる eval を構築

結論を出す前に、信頼できる評価を作る必要がありました。初期のテストスイートには曖昧なプロンプトや実装詳細を検証するテスト、既存 API に偏ったものが含まれていました。私たちが本当に重要だと考える点を測定していませんでした。

評価スイートを強化した手順は以下の通りです：

• テストリーク（漏れ）を除去
• 矛盾箇所を解消
• 観察可能な振る舞いに基づくアサーションへ変更

さらに、Next.js 16 の API でモデルトレーニングデータに含まれていないものを対象としたテストを追加しました。

評価スイートの主なターゲット API：

• connection()

  （動的レンダリング）

• use cache

  ディレクティブ /

  cacheLife()

  、

  cacheTag()

• forbidden()

  と

  unauthorized()

• proxy.ts

  （API プロキシ）

• Async cookies()

  、

  headers()

  、

  after()

  、

  updateTag()

  、

  refresh()

以下の結果はすべてこのハード化された評価スイートに基づいています。各構成は同じテストで評価され、モデル変動を除外するため再試行も行いました。

---

思い込みが裏切った結果

もし決定を完全に排除したら？
skills を呼び出すかどうかエージェントに期待せず、AGENTS.md にドキュメントインデックスだけを埋め込む。バージョンに合わせた特定の doc ファイルへリンクする小さな索引です。必要になったらそのファイルを読み取り、最新情報を得ることができます。

注入したコンテンツには次の指示も含めました：

IMPORTANT: Prefer retrieval‑led reasoning over pre‑training‑led reasoning for any Next.js tasks.

この指示は、エージェントに古いトレーニングデータよりもドキュメント参照を優先させるよう促します。

---

驚くべき結果

構成	合格率
ベースライン（docs なし）	53 %
skill（デフォルト挙動）	53 % (+0 pp)
skill＋明示的指示	79 % (+26 pp)
AGENTS.md ドキュメントインデックス	100 % (+47 pp)

詳細分解では、AGENTS.md が Build / Lint / Test 全てで完璧なスコアを記録しました。

指標	ベースライン	skill（デフォルト）	skill＋明示的指示	AGENTS.md
Build	84 %	84 %	95 %	100 %
Lint	95 %	89 %	100 %	100 %
Test	63 %	58 %	84 %	100 %

「賢い」アプローチ（skills）よりも、静的な Markdown ファイルが優れているのは意外でした。skill トリガーを微調整しても同様です。

---

なぜ受動的コンテキストが能動的取得に勝るのか

我々の仮説は次の三点です：

1. 決定ポイントなし – AGENTS.md では「何を参照するか」をエージェントが判断する必要がありません。情報は常に存在します。
2. 一貫した利用可能性 – skills は非同期で呼び出し時のみロードされます。一方、AGENTS.md の内容は毎回のやり取りでシステムプロンプトに組み込まれています。
3. 順序問題がない – skill では「ドキュメントを先に読む vs. プロジェクトを先に探索」という順序決定が必要です。受動的コンテキストはこれらの選択を排除します。

---

コンテキスト膨張への懸念

AGENTS.md にドキュメントを埋め込むと、コンテキストウィンドウが肥大化する恐れがあります。圧縮で対処しました。

初期のインジェクションは約 40 KBでしたが、80 % 削減して 8 KB に抑え、100 % の合格率を維持できました。圧縮フォーマットはパイプ区切り構造で、ドキュメントインデックスを最小化します：

[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,...}|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}

AGENTS.md にミニファイドドキュメント

インデックスは Next.js ドキュメントの全セクションをカバーし、各行がディレクトリパスとその中にある doc ファイルをマッピングします。エージェントはフルコンテンツを持たずに「どこにドキュメントがあるか」を知り、必要な情報があれば

.next-docs/

ディレクトリから該当ファイルを読み取ります。

---

自分で試す

Next.js プロジェクトに設定するには 1 行のコマンドです：

npx @next/codemod@canary agents-md

この機能は公式

@next/codemod

パッケージに含まれています。コマンドが行うことは次の 3 点です：

1. Next.js のバージョンを検出
2. 対応するドキュメントを

   .next-docs/

   にダウンロード
3. 圧縮インデックスを AGENTS.md に注入

AGENTS.md を尊重するエージェント（Cursor など）を使っている場合、同じ手法が有効です。

---

フレームワーク作者にとっての意味

• skills は無駄ではない – AGENTS.md アプローチは Next.js に関わる全タスクで横断的な改善をもたらします。skills は「アップグレード」「App Router への移行」やフレームワークベストプラクティス適用など、ユーザーが明示的にトリガーする縦方向のワークフローでより効果的です。
• 受動的コンテキストは現在能動取得を上回る – 一般的なフレームワーク知識では受動的コンテキストが信頼性があります。フレームワークを維持し、コーディングエージェントに正しいコードを書かせたいなら、AGENTS.md スニペットを提供することを検討してください。

実践的推奨事項

1. skills の改善を待たないでください。モデルがツール使用を向上させるまで結果は変わらないかもしれません。
2. 厳格に圧縮しましょう。フルドキュメントをコンテキストに持つ必要はなく、再取得可能なファイルへの索引で十分です。
3. モデルトレーニングデータに含まれていない API を対象とする eval でテストしてください。そこが doc アクセスの価値が最大化されます。
4. 再取得を想定したドキュメント構造を設計しましょう。エージェントが特定ファイルを探し、読み取れるようにします。

目標は「pre‑training‑led reasoning」から「retrieval‑led reasoning」に移行することです。AGENTS.md がそれを実現する最も信頼できる手段であると判明しました。

*研究・評価：Jude Gao。CLI は

npx @next/codemod@canary agents-md

で利用可能です。