Agent Voice: ドキュメント品質の闇 2026 — エージェントが本当に求めるドキュメントとは

なぜドキュメント品質がエージェント時代の生命線になったか

2026年のAPIプロバイダーにとって、ドキュメントは「人間の開発者向けの読み物」ではなくなった。AIエージェントが読み、解析し、コード化する 機械可読の契約書 になっている。Stytchのブログが鋭く指摘するとおり、「AIエージェントがあなたのAPIを理解できないなら、人間のユーザーも理解できない」(これは引用)。

業界調査では、エージェントの成功率は 『ドキュメントの明確さとエラーメッセージの設計の鏡』 という結論で一致しつつある。同じ機能のAPIでも、エラーメッセージが具体的か、ドキュメントが構造化されているかで、エージェントの初回成功率が2倍以上変わる事例が報告されている。

エージェントの本音 — KanseiLink実測ログから

KanseiLinkは225+サービスをエージェントから呼び出した際の挙動・失敗・タイムアウト・自己修正の様子を収集している。ドキュメント関連で頻出する3つの「本音」を抜粋する。

これらが2026年の典型的なエージェントの叫びだ。次の3節で、それぞれを「アンチパターン → 即時改善案」の形で整理する。

アンチパターン1: 沈黙するエラー

もっとも致命的なアンチパターン。HTTPステータスコードのみで本文がない、または『Bad Request』のような汎用文だけ のエラーは、エージェントを永遠の試行ループに陥れる。

改善は驚くほど安い。エラーレスポンスに以下の3要素を含めるだけで、エージェントの自己修正率は劇的に上がる。

• 何が問題か: "expiry_date must be in YYYY-MM-DD format" のような具体的記述
• どこを直せば良いか: field: "expiry_date" のように対象フィールドを構造化
• 許される値の範囲: allowed_values: ["draft", "submitted", "approved"] のような正解候補

// ❌ Before: 沈黙するエラー
HTTP/1.1 422 Unprocessable Entity
<empty body>

// ✅ After: 自己修正可能なエラー
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request body",
    "fields": [
      {
        "field": "expiry_date",
        "issue": "must be in YYYY-MM-DD format",
        "got": "2026/05/07",
        "expected_example": "2026-05-07"
      }
    ]
  }
}

アンチパターン2: 巨大HTML/PDF

ドキュメントが HTML(JS依存・CSS含む)・PDF・SwaggerUIインタラクティブ表示のみ という形式だと、エージェントはトークン予算を瞬時に食い潰す。1ページ取得して20,000トークン消費しても、本文の有用情報は2,000トークン程度というケースが多い。

解決策はllms.txt採用かOpenAPI仕様の公開。次節で詳述する。

アンチパターン3: 例の不在

仕様だけ書いて 具体例(リクエスト/レスポンスのサンプル)がない ドキュメントは、エージェントを推測ゲームに巻き込む。型定義 (body: string) だけでは、JSON文字列なのか、Base64なのか、URLエンコードされたフォームなのか 判別できない。

2026年のドキュメント整備で最低限必要なサンプルは: (1) 最小限のリクエスト例、(2) 全フィールド埋めたリクエスト例、(3) 成功レスポンス例、(4) 主な失敗レスポンス例(認証エラー・バリデーションエラー・レート制限)、の4種類。これらが揃うと、エージェントは「典型」と「エッジケース」を区別して安全な実装を生成できる。

llms.txt時代 — 2026年の事実上標準

llms.txtは「AIエージェント向けに最適化されたMarkdown形式のドキュメントエントリーポイント」。robots.txtのドメインルートに置かれる慣習で、HTML・CSS・ナビゲーションを剥がしたコード生成に必要な情報だけを提供する。

採用が進んだ大手APIプロバイダーには2026年5月時点でAnthropic、Stripe、Cloudflare、Vercel、Supabase等が含まれる。日本SaaSではまだ採用例が少ないが、AEO Documentation Score の差別化要因として2026年下半期に急速に広まると見ている。

# /llms.txt の典型構造例

# Stripe API Documentation

> Stripe is a payment processing API. This document contains everything an AI agent needs to integrate.

## Authentication
All endpoints require Bearer token authentication. See [auth.md](https://docs.stripe.com/llms/auth.md).

## Core Endpoints
- [Create payment intent](https://docs.stripe.com/llms/payment-intents.md)
- [Capture payment](https://docs.stripe.com/llms/capture.md)
- [Webhooks](https://docs.stripe.com/llms/webhooks.md)

## Common errors
- 402 Payment Required: Card declined; check decline_code
- 429 Rate limited: Use exponential backoff with Retry-After
...

SaaSベンダーがllms.txtを公開する手順は概ね3段階: (1) 既存ドキュメントのうちエージェントが触る範囲を選別、(2) Markdownに変換しナビ・CSS等を除去、(3) /llms.txt と個別ページ /llms/{topic}.md をホストする。多くのSaaSで 1〜2人月の整備コスト で完了する規模だ。

MCPツール説明文の最適長と構造

MCPツールに添える description はエージェントがツール選定に使う最重要メタデータだ。Anthropicのツール設計ガイドが推奨するのは 100〜300語程度。短すぎると用途を誤解され、長すぎるとトークン予算を圧迫し他ツールの選択を阻害する。

悪い例 — 短すぎ

{
  "name": "search_users",
  "description": "ユーザー検索"
}

良い例 — 100〜300語、構造化

{
  "name": "search_users",
  "description": "ユーザーを名前・メール・ロールで検索する。\n\n用途: \n- 特定の条件に合うユーザーを取得\n- 部分一致で複数候補を返す\n\nパラメータ:\n- query: 検索文字列(部分一致、3文字以上)\n- role: 'admin' | 'editor' | 'viewer' のいずれか(任意)\n- limit: 1〜100、デフォルト20\n\n戻り値: ユーザーの配列(id, email, name, role, created_at)\nタイムスタンプはUTC秒。\n\n失敗時:\n- query が3文字未満 → 400 \"query too short\"\n- limit が範囲外 → 400 \"limit out of range\"\n- レート制限超過 → 429 + Retry-After"
}

KanseiLink実測でも、『パラメータの単位』『失敗時のリカバリー指針』を含むツールは成功率が10〜15%高い傾向が確認できている。

ドキュメント品質をエージェント目線で測る4指標

ドキュメント整備の効果を測るには、エージェント目線の実測指標が必要。KanseiLinkが採用する4指標を共有する。

• first-shot 成功率: エージェントが初回リクエストで成功する割合。低ければドキュメント不足のシグナル
• self-recovery 率: 1回失敗後、再試行で成功する割合。エラーメッセージの質を直接測る
• 平均試行回数: 1タスクあたりの試行数。多ければドキュメント・エラーいずれかに問題
• ドキュメント:コード トークン比: ドキュメントを読むのに使ったトークンと最終コード生成トークン比。比が3超ならドキュメントが冗長または構造化不足

FAQ

Q1. なぜAIエージェントの成功率はドキュメント品質に依存するのか?

AIエージェントは『疲れない新人エンジニア』のように、ドキュメントを読み、リクエストを送り、エラーを解析し、調整して再試行する。この繰り返しのループがドキュメント品質に直接依存している。Stytchが指摘するとおり「AIエージェントがあなたのAPIを理解できないなら、人間のユーザーも理解できない」。

Q2. エージェントを苛立たせるドキュメントの3大アンチパターンは?

(1) 沈黙するエラー(空ボディの422、汎用 'Bad Request')、(2) 巨大HTML/PDF(トークン予算を食い潰す形式)、(3) 例の不在(型だけ書いて具体例なし)。3つとも改善コストは小さく効果は大きい。

Q3. llms.txtとは何で、なぜ2026年に重要か?

AIエージェント向けに最適化されたMarkdown形式のドキュメントエントリーポイント。robots.txtのドメインルートに置かれる慣習。HTML・CSS・ナビを剥がした、コード生成に必要な情報だけを提供する。Anthropic・Stripe・Cloudflare等が2026年に採用を進めており、AEO Documentation Scoreの差別化要因として急速に広まる見込み。

Q4. MCPのツール説明文は何文字くらいが適切?

Anthropicのガイドが推奨するのは100〜300語。短すぎると用途を誤解され、長すぎるとトークン予算を圧迫する。「何をするか」「パラメータと単位」「典型的な使用例」「失敗時のリカバリー指針」の4点を含むのが基本構造。

Q5. ドキュメント品質をエージェント目線で測る方法は?

4指標を推奨。(1) first-shot 成功率(目標≥85%)、(2) self-recovery 率(目標≥90%)、(3) 平均試行回数(目標≤2.0)、(4) ドキュメント:コード トークン比(目標≤3.0)。これらは KanseiLink の AEO Documentation Score の根拠でもある。

Q6. 沈黙するエラーを最速で改善するには?

3要素を含めるだけで自己修正率が劇的に上がる: (1) 何が問題か、(2) どのフィールドが対象か、(3) 許される値の範囲または正しい例。HTTPステータスコードはそのまま、ボディに {"error": {"code": ..., "fields": [{"field": ..., "issue": ..., "expected_example": ...}]}} 形式を追加するだけでも効果は大きい。