AGENTS.mdでAIエージェントの精度を劇的に上げる——Vercelが実証した「パッシブコンテキスト」戦略

はじめに

「AIコーディングエージェントに指示を出したのに、フレームワークの古いAPIを使ったコードが生成された」

Claude CodeやGitHub Copilotを使っていて、こんな経験はありませんか？LLMは学習データに含まれる古い情報をもとにコードを生成するため、最新のAPIや推奨パターンに追従できないことがあります。

この問題に対して、Vercelが衝撃的な検証結果を公開しました。プロジェクトルートに AGENTS.md というファイルを1つ置くだけで、エージェントのタスク成功率が 53%から100% に跳ね上がったのです。

本記事では、Vercelの検証データを読み解きながら、AGENTS.mdの書き方と「パッシブコンテキスト」という考え方を実践的に解説します。

この記事を読み終わったら、以下ができるようになります。

• AGENTS.mdとCLAUDE.mdの違いを理解し、使い分けられる
• パッシブコンテキストの概念を説明できる
• 自分のNext.jsプロジェクトにAGENTS.mdを導入できる

Vercelの検証結果——なぜAGENTS.mdが圧勝したのか

4つの構成を比較テスト

Vercelは、Next.js 16のAPIを対象に4つの構成をテストしました。ポイントは、トレーニングデータに含まれていない最新API（connection()、'use cache'ディレクティブ、cacheLife()など）をターゲットにしたことです。

さらに、Build / Lint / Test の内訳を見ると差が際立ちます。

Agent Skillsが伸び悩んだ理由

Agent Skills は「エージェントが必要に応じて読み込む」オンデマンド型のドキュメント提供方式です。しかし、Vercelの検証では 56%のケースでスキルが呼び出されませんでした。

つまり、エージェントが「自分はこのフレームワークを知っている」と判断してしまうと、スキルを参照せずに古い知識で実装してしまうのです。

パッシブコンテキストとは何か

「読むかどうか」の判断を排除する

Vercelはこの問題の本質を 「パッシブコンテキスト vs アクティブコンテキスト」 というフレームで整理しました。

パッシブコンテキストの3つの強みは以下の通りです。

• 判断ポイントがない: 「これを参照すべきか？」という分岐自体が存在しない
• 一貫した利用可能性: 毎ターン確実に情報が存在する
• 順序問題の回避: 「先にドキュメントを読むか、先にコードを探索するか」という判断が不要

CLAUDE.mdとAGENTS.mdの違い

どちらもパッシブコンテキストですが、対象エージェントが異なります。

実際のプロジェクトでは両方置くのが効果的です。CLAUDE.mdにはプロジェクト固有のルール（コーディング規約、ディレクトリ構成など）を、AGENTS.mdにはフレームワークの最新ドキュメントインデックスを配置します。

ハンズオン 1: Next.jsプロジェクトにAGENTS.mdを導入する

Vercel公式のセットアップコマンド

Vercelが提供するcodemodで、Next.jsのAGENTS.mdを自動生成できます。

npx @next/codemod@canary agents-md

このコマンドを実行すると、プロジェクトルートに AGENTS.md が生成されます。中身は、プロジェクトが使用しているNext.jsバージョンに対応したドキュメントインデックスです。

生成されるAGENTS.mdの構造

Vercelの検証で使われたAGENTS.mdは、40KBのドキュメントを 80%圧縮して8KB にしたものです。パイプ区切りの独自フォーマットを使っています。

[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-layouts-and-templates.mdx,...}

ここで重要なのが以下の1行です。

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning

「事前学習の知識より、検索ベースの推論を優先せよ」という指示です。これにより、エージェントが古い知識に頼らず、インデックスからドキュメントを読みに行くようになります。

ハンズオン 2: カスタムAGENTS.mdを書く

codemod以外のフレームワークや、自社独自のルールを盛り込みたい場合は、手動でAGENTS.mdを作成します。

基本構成

# AGENTS.md

## Project Overview
- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- Database: Firestore
- Styling: Tailwind CSS

## Important: Use retrieval-led reasoning
When implementing features, always check the referenced documentation
before relying on pre-trained knowledge. APIs change frequently.

## Documentation Index
| Topic | Reference File |
|-------|---------------|
| Routing | ./docs/routing.md |
| Data Fetching | ./docs/data-fetching.md |
| Server Actions | ./docs/server-actions.md |
| Authentication | ./docs/auth.md |

## Code Conventions
- Components: PascalCase (e.g., PaymentTable.tsx)
- Utilities: camelCase (e.g., calculateTax.ts)
- Server Actions: actions.ts in each page directory

## Directory Structure
- src/app/ - Next.js App Router pages
- src/components/ - Shared components
- src/lib/ - Utilities and business logic
- src/types/ - TypeScript type definitions

架空プロジェクト「TaskFlow」での実践例

架空のタスク管理SaaS「TaskFlow」（Next.js + Firestore + TypeScript）を例に、AGENTS.mdとCLAUDE.mdの使い分けを見てみましょう。

AGENTS.md（フレームワーク知識）:

# AGENTS.md

## Next.js App Router Patterns

### Server Components (default)
- All components in `src/app/` are Server Components by default
- Use `async/await` directly in components for data fetching
- Do NOT use `useEffect` or `useState` in Server Components

### Client Components
- Add `"use client"` directive at the top
- Required for: event handlers, hooks, browser APIs

### Server Actions
- Define in `actions.ts` with `"use server"` directive
- Use for form submissions and data mutations
- Always revalidate paths after mutations

### Firestore Patterns
- Use `getDoc` / `getDocs` for reads in Server Components
- Use Server Actions for writes (addDoc, updateDoc, deleteDoc)
- Collection references: `collection(db, "collectionName")`

CLAUDE.md（プロジェクト固有ルール）:

# CLAUDE.md

## TaskFlow Project Rules

### Firestore Collections
- tasks: タスクデータ（title, status, assignee, dueDate）
- projects: プロジェクト（name, members, createdAt）
- users: ユーザー情報（displayName, email, role）

### Coding Standards
- TypeScript strict mode: `any` 型は禁止
- Tailwind CSS でスタイリング（CSS modules 不使用）
- コンポーネントは src/components/ に配置

ハンズオン 3: 効果を検証する——AGENTS.mdあり/なしの比較

実際にAGENTS.mdの効果を体感するために、簡単な検証を行ってみましょう。

検証シナリオ

Next.js App Routerの cookies() 関数は、Next.js 15以降で非同期APIに変更されました。AGENTS.mdがない場合、エージェントは古い同期的な使い方で実装する可能性があります。

テストプロンプト:

src/app/dashboard/page.tsx を作成して。
cookiesからセッショントークンを取得し、
ユーザー情報を表示するServer Componentを実装して。

AGENTS.mdなしの場合（古い知識で実装）

// ❌ Next.js 14以前の書き方（同期的）
import { cookies } from "next/headers";

export default function DashboardPage() {
  const cookieStore = cookies(); // 同期呼び出し
  const token = cookieStore.get("session-token");
  // ...
}

AGENTS.mdありの場合（最新APIで実装）

// ✅ Next.js 15以降の書き方（非同期）
import { cookies } from "next/headers";

export default async function DashboardPage() {
  const cookieStore = await cookies(); // 非同期呼び出し
  const token = cookieStore.get("session-token");
  // ...
}

たった1つの await の有無ですが、これがビルドエラーやランタイムエラーの原因になります。AGENTS.mdに「cookies() は非同期APIである」という情報が含まれていれば、エージェントは確実に正しい書き方を選択します。

AGENTS.mdの最適化テクニック

Vercelの検証から得られた最適化のポイントを整理します。

テクニック1: 圧縮してトークンを節約する

AGENTS.mdはエージェントのコンテキストウィンドウを消費します。不必要に長いと、他の情報が入る余地が減ります。

ポイント: AGENTS.mdにはインデックス（目次）だけ置き、詳細は個別ファイルとして配置する。エージェントはインデックスを見て必要なファイルだけ読みに行く。

テクニック2: 「検索ベースの推論を優先せよ」と明記する

Vercelの検証で最も効果的だった指示の一つがこれです。

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
When you need to use a framework API, check the docs index above first.

LLMは自信を持って間違ったコードを書くことがあります。この指示により、「まずドキュメントを確認する」という行動パターンが強制されます。

テクニック3: 500行以内に収める

Vercel Agent Skillsのドキュメントでは、SKILL.mdを500行以内に収めることが推奨されています。AGENTS.mdも同様に、コンパクトに保つことが重要です。

<!-- ❌ 冗長な書き方 -->
## Server Actions について

Server Actions は Next.js の機能で、サーバーサイドで実行される関数です。
フォームの送信やデータの変更に使用します。
Server Actions を使用するには、関数の先頭に "use server" ディレクティブを追加します。
Server Actions は非同期関数である必要があります。
...（長い説明が続く）

<!-- ✅ 簡潔な書き方 -->
## Server Actions
- Define with `"use server"` directive in `actions.ts`
- Always `async` functions
- Revalidate after mutations: `revalidatePath("/path")`
- Ref: ./docs/server-actions.md

CLAUDE.md・AGENTS.md・Agent Skillsの使い分けガイド

3つのアプローチをいつ使うか、判断フローを整理します。

実際のプロジェクトでは、以下のような組み合わせが効果的です。

project-root/
├── CLAUDE.md          # プロジェクトルール（Claude Code向け）
├── AGENTS.md          # フレームワーク知識（全エージェント共通）
├── .claude/
│   └── skills/        # タスク固有のスキル
│       ├── deploy/
│       │   └── SKILL.md
│       └── write-blog/
│           └── SKILL.md
└── .next-docs/        # AGENTS.mdから参照されるドキュメント
    ├── routing.md
    ├── data-fetching.md
    └── server-actions.md

まとめ

Vercelの検証が示した結論は明快です。AIコーディングエージェントには「読むかどうか判断させる」のではなく「常に目に入る場所に情報を置く」のが最も効果的です。

まずは npx @next/codemod@canary agents-md を実行して、Next.jsプロジェクトにAGENTS.mdを導入してみてください。CLAUDE.mdと組み合わせることで、エージェントの出力精度が体感できるレベルで向上するはずです。

---

参考リンク：

• AGENTS.md outperforms skills in our agent evals（Vercel Blog）
• Agent Skills explained: An FAQ（Vercel Blog）
• Agent Client Protocol