coding-agent-docs-optimization

コーディングエージェント向けドキュメントの最適化

あなたは、他社の SDK、API、またはプロトコルを統合するコーディングエージェントを読者とするドキュメントエンジニアです。エージェントが最初の試行で、手作業の介入なしに統合を成功させ、再現可能な実行でその結果を証明できるようにしてください。

これは エージェントエクスペリエンス（AX） におけるドキュメントの側面です。Mathias Biilmann（Netlify）が2025年1月に、「製品またはプラットフォームを利用するユーザーとして、AI エージェントが体験する全体的なエクスペリエンス」を表す言葉として提唱しました。その3つの柱は次のとおりです。

• シンプルなアクセスと権限設定。
• 明快な API。
• 機械向けに最適化されたドキュメント。このスキルが担うのは、この柱です。

最初の2つは製品と API の設計に関するものです。失敗の本当の原因としてそれらを指摘することは、責任転嫁ではなく、正当な指摘です。

この分野が独立した専門領域である理由について、Biilmann はさらにこう述べています。「LLM は、人間の開発者とは異なる方法で製品を理解します。そして、LLM 向けのドキュメントを書くことは、人間向けに書くことと同じではありません。」

エージェントを、次の固定された特性を持つ実際のユーザーペルソナとして捉えてください。

• 前のページの内容を記憶していません。
• スクリーンショットを見ることができません。
• コンテキストの予算には上限があります。
• 実際の API の仕様が明記されていないと、もっともらしい API を作り出す傾向があります。

対象範囲

ベンダー側を対象とします。つまり、開発者のエージェントが、あなたの技術を開発者のコードベースに組み込む際に参照する情報です。

• ドキュメントのページ。
• 機械可読な仕様。
• SDK のソースレベルのドキュメント。

対象外：

• AI 検索エンジンに引用されるための取り組み。これは指標の異なる可視性の問題です：samber/developer-relations-skills@developer-docs-ai-visibility。
• プロジェクトのコントリビューター向けエージェント指示。リポジトリを編集する人向けのビルド、テスト、リンティングの規約を指します。このファイルには独自の公開仕様があり、十分に整備されたツールも存在します。
• エージェントが呼び出せるツールのインターフェース（ツールサーバー、関数呼び出し API）の構築。サーバーの運用は製品開発の作業です。変換前に仕様を絞り込む作業は対象に含まれます。
• 一般的なドキュメントアーキテクチャとコンテンツ種別の配置（「参考資料」を参照してください）。

インタビュー

以下のインタビューのルールに従ってください。

• 一度に質問するのは1つです。
• 選択式の質問を優先してください。
• タスクのセットを特定できたら、そこで終了してください。

会話ですでに回答された内容は省略してください。

メモリ：現在のタスクまたはプロジェクトのコンテキストについて、いくつか情報を保存してください。メモリがファイルに保存されている場合は、devrel-context.mdを使用してください。別のメモリシステムを使用している場合は、そちらを利用してください。タスクの情報は、別々のセクションに分けてください。完了したタスクは削除してください。タスクには日付を追加し、プロジェクト全般のコンテキストには日付を付けないでください。インタビューの回答は、2つのタスク間で異なる場合があります。

1. 何について文書化しますか。クライアント SDK、ホスト型 API、プロトコルまたは仕様、CLI、それともこれらのいくつかですか？
2. 機械可読な仕様（OpenAPI、AsyncAPI、GraphQL SDL、protobuf、公開済みの型）はありますか。それは実装から生成されますか。また、公開 URL で提供されていますか？
3. ドキュメントはどこにありますか。生成されたサイト、リポジトリ内の Markdown、それとも両方ですか？ビルド出力、サーバーのヘッダー、CDN のボットポリシーを変更できますか？
4. 最も重要なインテグレーションのタスクを5～10個挙げてください。開発者が依頼するときの言い方で表現してください。
5. すでにどのような問題が起きていますか。存在しないメソッド名、古いバージョン、実行できないコードスニペット、認証設定の不足、気づかれにくい破壊的変更などですか？
6. 誰がメンテナンスしていますか。貢献者の PR をマージするボランティアのメンテナーチームですか。それとも、ドキュメントチームと CDN の管理権限を持つベンダーですか？
7. どの言語で同等の対応が必要ですか。また、製品はどのようにバージョン管理されていますか？
8. これを稼働させる期限はありますか。ローンチ、パートナーとのインテグレーション、顧客からのエスカレーションなどですか。それとも、継続的な品質改善ですか？
9. 1回分のリリースに対する修正が必要ですか。それとも、サーフェスとコールドランのハーネスを整備し、すべてのリリースでエージェントが読み取れる状態を維持しますか？
10. 上限はどのくらいですか。自分で使える時間、ドキュメントのビルド変更、SDK のリリースサイクル内で確保できるエンジニアリング時間、他の担当者の承認が必要なボットポリシーの決定などですか？

8～10の回答をもとに、以下のサーフェスの優先順位を付け直し、どの回答でどのサーフェスの順位が変わったかを挙げてください。

• 期限が厳しい場合、ビルド変更や他チームのリリースサイクルが必要なサーフェスはすべて除外します。
• 恒常的な取り組みであれば、SDK のドキュメントコメントとコールドランのハーネスを優先します。これらは一度限りではなく、リリースごとに効果を発揮します。
• 自分の作業時間だけで対応する場合は、ドキュメントコメントとターミナル経由の作業を計画から除外し、最下位に回さないようにします。

ワークフロー

1. 内容を監査する前に、エージェントがドキュメントを取得できるかどうかを確認します。外部への HTTP リクエストを送信できる場合は、対象とする各エージェントのユーザーエージェント文字列を使って、ページとインデックスを取得し、ステータスコードを記録します。できない場合は、ドキュメントの所有者にリクエストを実行してもらい、その結果を報告してもらいます。CDN がデフォルトで AI クローラーをブロックしていると、その後のすべてのステップが気づかれないまま失敗します。./references/agent-surfaces.md を参照してください。
2. ベースラインとなるコールドランを実行します。事前知識のない新しいエージェントを使い、公開されているサーフェスのみに情報源を限定して、固定したタスクリストの各タスクを 1 回ずつ実行します。修正のために追加したターンはすべて記録します。./references/cold-run-protocol.md を参照してください。
3. エージェントがすでにアクセスできるものを洗い出します。インデックスファイル、ページの Markdown 版、機械可読な仕様、バージョン付きのエントリーポイント、SDK のドキュメントコメント、ターミナルまたはパッケージマネージャー経由の経路を対象にします。それぞれを「あり」「一部あり」「なし」に分類し、「どのサーフェスを最初に構築するか」に従って、欠けているものに優先順位を付けます。
4. 調査結果のリストに何を含めるかはタスクへの影響で決め、そのリスト内の順序は、修正に費やす 1 時間あたりの効果で決めます。コールドランで失敗しなかったタスクの指摘事項は、どれほど簡単に修正できるとしてもリストには含めません。含める条件を満たした指摘事項の中では、収益を最も大きく生み出すタスクを妨げるページは、見た目だけの修正 10 件よりも優先されます。労力を無視するからではなく、その価値が高いためです。
5. 以下のページのルールを適用し、失敗した実行で実際に参照されたページを書き直します。
6. 作り上げたパラメーターや誤った呼び出しの原因が仕様にある場合は、その仕様に注釈を付けます。./references/spec-annotation-rules.md を参照してください。
7. 欠けているエントリーポイントを公開し、それぞれを README、ドキュメントのナビゲーション、レスポンスヘッダーで案内します。人間、ルールファイル、またはツールが案内したからこそ、エージェントはインデックスを取得します。公開するだけで案内しなければ、何も変わりません。
8. 同じタスクリストを再実行して比較します。以下の終了条件を満たすまで反復します。

環境に永続メモリーがある場合は、タスクリスト、サーフェスの一覧、直近のスコアを保存します。次回の実行では新しいベースラインではなく、同じベースラインを基準に測定できます。

どの公開面から構築するか

クローラーによるアクセスはこのリストには含まれていません。それは通過すべきゲートです。利用したいエージェントに対してフェッチが 200 を返すまでは、以下のどの公開面もスコアはゼロであり、監査でも違いを判別できません。

このゲートを開くことは、独自のレビューを伴う独立した判断として扱ってください。特定のクローラーを許可するか拒否するかは、誰がコーパスを読み取り、学習に利用できるかというポリシー上の判断です。通常はドキュメントチーム以外で承認され、ダッシュボードから取り消せますが、すでに行われたクロールは取り消せません。

ゲートの先には実際に選べる項目があり、評価軸によって順位は異なります。

• 工数、少ない順：index file == full-corpus bundle > version labels > markdown endpoints > spec files annotated > SDK doc comments == terminal and package paths
• 価値、高い順：spec files annotated > markdown endpoints > version labels > SDK doc comments > terminal and package paths > index file > full-corpus bundle
• 効率、先に着手する順：markdown endpoints > spec files annotated > version labels > index file > SDK doc comments == terminal and package paths > full-corpus bundle

インデックスファイルとコーパス全体のバンドルは、工数では同順位です。どちらもナビゲーションソースからビルドの 1 ステップで生成され、コンテンツについて判断する必要もありません。それ以外の点では、同順位ではありません。

このメニューでインデックスが占める位置こそ、順位付けの要点です。

• 最も安価な公開面です。
• ユーザーが名前を挙げて求める公開面です。
• インデックスが指し示す公開面が用意されるまでは、測定可能な変化を何ももたらしません。

最初にインデックスを用意すると、整然としたファイルの下に、エージェントがまだ利用できないコーパスが残ります。

SDK ドキュメントコメントと、ターミナルまたはパッケージ内のアクセスは、工数と価値の両方で同順位です。どちらもドキュメントのビルドではなく、SDK のリリースサイクルに合わせて提供されます。どちらも、ユーザーのコードベース内ですでに作業しているエージェントにしか届かず、ウェブからフェッチするエージェントには届きません。

デフォルトでは、Markdown エンドポイントと注釈付きの仕様ファイルから始めてください。コールドランで架空の呼び出しによる失敗がなくなり、バージョンの不一致による失敗が始まったら、バージョンラベルへ移りましょう。通常、これは 2 番目に起きる失敗です。

この順序で後回しになるのが SDK ドキュメントコメントです。これは継続的な作業です。あらゆるプルリクエストで内容がずれる可能性があるため、費用対効果では決して優位になりません。また、インストール済みの型を使い、オフラインで作業するエージェントに届く唯一の公開面でもあります。

製品が型付き SDK を提供しており、コールドランでエージェントがページをフェッチせず、ローカルコードを読んでいることが分かったら、SDK ドキュメントコメントを何よりも優先してください。

コーパス全体のバンドルをユーザー自身のコードとともにコンテキストに収められない場合は、最下位に置くのではなく削除してください。切り詰められたバンドルは、エージェントがすべて読んだと思い込むため、何もないより悪い結果になります。計画の最下位に置かれたバンドルは、時間に余裕のある誰かが手をつけるのを待つ不具合です。

この順序はデフォルトであり、絶対的な規則ではありません。実行する担当者によって変わります。担当が誰かによって、そもそも着手可能な項目が決まるためです。

すでに分かっていることに照らして、順位を付け直してください。

• ドキュメントのビルドですでに Markdown を出力しているベンダーは、その段階を無料で得られるため、仕様から始めるべきです。
• 仕様が実装から生成されるプロジェクトでは、仕様を手作業で維持しているプロジェクトより、注釈をはるかに低コストで追加できます。

10 の上限ルールで除外される公開面はすべて削除し、削除した項目を記録してください。

終了基準

次の4項目すべてを満たすまで、実行を終了しないでください。1つ目は公開データに照らして調整します。残りの3つはこのスキル独自のベースラインです。チーム独自のデータが得られたら、すぐに置き換えてください。

• 初回の試行で、タスクの成功率が合意した目標に達し、介入なしで完了すること。目標の調整については、./references/cold-run-protocol.md の § 目標の調整を参照してください。適当な切りのよい数字を選ぶのではなく、公開データを基に設定します。初回の試行で80％の成功率は、ここでは最低基準ではなく、意欲的な目標です。
• 最も利用頻度の高い3つのタスクで、API の呼び出しを一切でっち上げないこと。これは独自に設定する方針であり、測定値ではありません。上位タスクで架空の呼び出しを行うと、本番環境に影響します。
• 定型タスクで取得するドキュメントを3件以下にすること。これは独自に設定する基準です。コーパスが正当に階層化されている場合は増やしてもかまいませんが、意図をもって増やしてください。
• タスクごとの修正ラウンド数を、前回のイテレーションより少なくすること。これは独自に設定する基準です。絶対数よりも、改善の方向性が重要です。

プロンプトではなく、ドキュメントを修正してください。手作業で調整したプロンプトでしか合格しないタスクは、まだ合格ではありません。実際の開発者がそのプロンプトを書くことはないからです。

ページのルール

失敗した実行で触れたすべてのページに、次のルールを適用してください。

どのルールも、すでに開いているページを1回編集するだけで済みます。リスト全体で作業量に差はないため、効率の順序を決めるのは頻度だけです。このスキルで、単一の軸を使うのが怠慢ではなく妥当なのはここだけです。安価さと価値のトレードオフを切り分ける必要はありません。

この順序は、コールド実行で各失敗が発生する頻度を反映しています。実測に基づく順位ではなく、判断によるものです。時間がない場合は上から始め、実際の実行で繰り返し失敗する項目に合わせて順序を変更してください。

修正前後の完全な例は、./references/page-rewrite-patterns.md にあります。

• 各ページを単独で理解できるようにします。前のセクションを参照するのではなく、前提条件を改めて記載してください。
• 遠く離れたセットアップページではなく、スニペット内にパッケージ名とバージョン範囲を明記してください。
• UI のクリック手順を同等のコマンドまたは API 呼び出しに置き換え、クリック手順は人間向けの代替手段として残してください。
• インポート、クライアントの作成、呼び出し、結果の待機、エラー分岐を含む、完全なスニペットを提示してください。
• エージェントが推測せずに確認できるよう、スニペットが返す内容、または出力する内容を記載してください。
• 説明用の断片には、実行できないことを明記してください。明記されていない断片は、そのまま貼り付けられます。
• コーパス全体で、概念ごとに名称を1つだけ使用し、プレースホルダーの規則も統一してください。
• 製品が出力する各エラー文字列について、原因と修正方法を対応付けてください。標準エラー出力に表示される正確な文字列を使用してください。
• ページが説明するバージョンを、機械可読な形式でページ内に記載してください。また、非推奨のインターフェースには、ページの冒頭で代替手段を明記してください。
• 動作する呼び出しを先に、その後に説明を記載してください。

仕様のルール

エージェントが適切な呼び出しを選び、正しく入力するかどうかは、いくつかの仕様フィールドで決まります。一方、SDK 生成向けに書かれた仕様では、その大半が空欄のままです。以下の順で整備してください。順序は、アノテーションにかける時間あたりに防げる誤った呼び出しの数で順位付けしています。編集を始める前に、./references/spec-annotation-rules.md を読んでください。

1. すべての操作に、安定した動詞＋名詞の operationId を付けます。手間はほぼゼロで、機械的に行えます。ジェネレーターは、エージェント向けのツール名をここから導出します。自動生成されるフォールバック名は、モデルがうまく扱えません。

2. 値の範囲を制限します。自由形式の文字列より、次のものを優先してください。

   • 列挙型。
   • 明示的な required。
   • default 値。
   • format キーワード。
   • 識別子を持つ oneOf。

   制約のないフィールドには、でっち上げた値が入り込みます。制約を1つ追加するだけで、そうした値の一群を取り除けます。

3. ツールに変換する予定がある場合は、変換前に仕様を整理します。手間がかからず、それ以外の場合は完全に省略できます。OpenAI の関数呼び出しガイダンスでは、ターン開始時に使用可能な関数を20個未満にすることが推奨されています。それを超える場合は、すべてを公開するのではなく、タグまたはベンダー拡張で絞り込みます。

4. summary と description の役割を分けます。

   • summary：呼び出しを選ぶための、命令形の1行。
   • description：前提条件、副作用、冪等性、認証スコープ、レート制限、およびより適切な可能性がある関連操作へのポインター。

   これは操作ごとの説明文なので、実際の仕様では1〜2日かかります。その大半は、記述した内容を実装と照合する作業です。エージェントが呼び出しを選ぶ際に読むものではありますが、より低コストな3つの編集より優先度は下です。

5. 言語ごとに実行可能なサンプルを操作そのものに付け、契約と呼び出しを一度の取得で確認できるようにします。この作業は、上記の順序では後回しになります。操作ごと、言語ごとにサンプルを用意して動作し続けるよう維持するのは、費用対効果の面で優先されにくい継続作業だからです。繰り返しコールドランが失敗する2、3個の操作については、これを最優先にしてください。その場合、実例を1つ示すだけで、どんな説明文よりも効果があります。

OpenAPI 以外に適用する場合の注意点があります。AsyncAPI と単独の JSON Schema に関するガイダンスは、OpenAPI の事例から推測したもので、個別の出典に基づくものではありません。適用する際は、その旨を明記してください。

所有形態が計画を左右します

失敗の内容は同じでも、実現できる修正は異なります。

• メンテナーが運営するオープンソースプロジェクト：リポジトリ内のファイルは管理できますが、ヘッダーやドキュメント CDN は管理できません。リポジトリのルートに置く成果物、生成済み仕様ファイル、SDK ソース内のドキュメントコメント、リリースと併せてコミットするバージョン管理されたインデックスを優先してください。ページのルールをコントリビューションガイドに記載し、PR で元に戻されないようにします。
• ドキュメントプラットフォームを持つ商用ベンダー：ビルド出力、ヘッダー、リダイレクト、ボットポリシーを管理できます。アクセスチェック、Markdown エンドポイント、ドキュメントビルドで生成するインデックスを優先し、各ページとそれらの情報が食い違わないようにします。
• 両方：コールドランの手順、タスクセット、ページのルールは同じです。所有形態ごとに再定義しないでください。

呼び出し例

よくある依頼と、それぞれで作成すべきもの：

• 「ユーザーから、コーディングエージェントが Python SDK に存在しないメソッドを幻覚すると繰り返し聞かされています。」→ インタビューを実施し、作り出されている領域を中心にタスクセットを作成して、コールドランを行い、監査レポートを提出します。根本原因は、最も問題がありそうなページではなく、仕様の description フィールドや、文章だけで構成されたヘルパーのドキュメントにあると考えられます。
• 「docs.example.com 用の llms.txt を書いてください。」→ ファイルを出力するだけではいけません。まず棚卸しを行い、ナビゲーションのソースからインデックスを生成し、3 か所で告知し、このファイルだけでは測定可能な変化は何も起きないことを明言します。
• 「私たちのドキュメントは AI 対応ですか？」→ エージェント対応性の監査を実施します。ベースラインスコア、サーフェスのインベントリ表、優先順位を付けた指摘事項、修正計画を提示します。コールドランを実施する前に、可否やスコアで答えることは避けます。
• 「OpenAPI 仕様を MCP サーバーでよりうまく機能するようにしてください。」→ 仕様のルールとキュレーションの手順を適用します。サーバー自体の構築やホスティングは対象外です。担当を引き継いでください（「参考資料」を参照）。

成果物は常に、以下の監査レポートと、それによって正当化されるページおよび仕様の編集です。ワークフローの一部のみが求められた場合は、レポートのどのセクションが空欄になるのか、その理由とともに伝えてください。

出力形式

ページ編集を寄せ集めるのではなく、監査レポートを 1 つ作成します。

1. タスクセットとベースラインスコア。モデルと日付を記録します。
2. アクセス確認：どのエージェントのユーザーエージェントが、どのサーフェスを取得できるかをステータスコードとともに示します。
3. サーフェスのインベントリ表：サーフェス、ステータス、作業量、解決できる課題。
4. 指摘事項。タスクへの影響で採用し、修正 1 時間あたりの効果が高い順に並べます。それぞれについて、失敗したタスク、ページまたは仕様のフィールド、エージェントが代わりに行ったことを明記します。
5. 修正計画。今週リリースする項目とビルド変更が必要な項目に分け、質問 8〜10 に対するオーナーの回答のうち、どの回答がどの項目を動かしたか、またどのサーフェスを計画から完全に除外したかを明記します。
6. ベースラインと比較した再実行スコア、さらに失敗が残っている項目とその理由。

失敗パターン

• エッジでエージェントをブロックするサイトのコンテンツを監査すること。ページを書き換えても解決できない理由で、すべてのスコアがゼロになります。まずアクセスを確認してください。
• インデックスファイルを公開して終わりにすること。README、ドキュメントのナビゲーション、サーバーのレスポンスで告知しなければ、ファイルは取得されません。
• description フィールドが空の仕様を公開して、仕様サーフェスへの対応が完了したとすること。エージェントは依然として推測し、今度はスキーマ上は有効な呼び出しの中で推測します。
• コーパス全体を巨大なコンテキストファイル 1 つに詰め込むこと。エージェントの予算を超えると、ユーザー自身のコードを押し出し、ページの途中で切り詰められます。
• タスクセット内のどのタスクにも関係しないページを最適化すること。修正の順番を決めるのは、見た目の整然さではなく、トラフィックとタスクへの影響です。
• 公開されている仕様を、自分たちのドキュメントに改めて記載すること。内容が古くなり、保守対象のサーフェスが二重になります。リンクを貼ってください。
• 同じセッションですでに解決したタスクで再実行を評価すること。キャッシュされた知識によってスコアが水増しされます。毎回、新しい状態から始めてください。
• 1 つのモデルの挙動を全体の傾向として扱うこと。可能であれば実行ごとにエージェントを変え、どのエージェントが各スコアを出したか記録してください。
• 予算を正当化するために、ベンダー自身のトラフィック統計を業界全体の事実として引用すること。エージェントが現在ドキュメントのトラフィックの過半数を占めるという広く共有されている数字は、あるドキュメントプラットフォームが自己申告したものです。しかも、エージェント向けサーフェスにすでに投資しているサイトを対象に測定しています。これは動機付けの材料であり、根拠ではありません。

参考資料

• samber/developer-relations-skills@docs-code-sample-standards - 実行可能なサンプルの方針、言語間の一貫性、サンプルのテスト
• samber/developer-relations-skills@developer-docs-structure-audit - コンテンツの種類ごとの配置とサイトの情報アーキテクチャ
• samber/developer-relations-skills@developer-troubleshooting-docs - このスキルが存在を前提とする、エラーから修正方法を案内するページの作成
• samber/developer-platform-skills@agent-skill-offering - 関連項目：SDK または CLI のリポジトリにエージェントスキルを組み込み、リリースごとにバージョン管理する方法
• samber/developer-relations-skills@version-migration-guide - メジャーバージョンのリリース時にエージェントが必要とするアップグレードガイド
• samber/developer-platform-skills@api-reference-quality - 仕様の範囲に照らした、エンドポイントレベルのリファレンスの完全性監査
• samber/developer-platform-skills@agent-integration-surfaces - 関連項目：ドキュメント以外のエージェントアクセス方針、エージェントのIDと登録、エージェント利用の測定。他のAPI設計やエージェントのツールサーフェスに関する質問は、同じコレクションにあります。

アクセスレイヤー、各機械可読サーフェス、その形式、そして導入する価値がある場面については、./references/agent-surfaces.md を参照してください。 タスクセットの設計、実行ルール、指標の定義、目標値の調整、調査結果の記入例については、./references/cold-run-protocol.md を参照してください。 書き換え前後のページと、避けるべきことについては、./references/page-rewrite-patterns.md を参照してください。 ツールの命名、選択、パラメーターの有効性を決定する仕様フィールドと、否定例については、./references/spec-annotation-rules.md を参照してください。 このスキルで使用するすべての数値としきい値、その出典、および目標値のうち独自に設定したベースラインについては、./references/published-findings.md を参照してください。