authoring-api-spec

authoring-api-spec — SKILL.md

バリアント： standard · 使用するタイミング： API サーフェスのエンジニアリング上のワイヤーコントラクトを作成するとき。クライアントがコントラクトだけをもとに統合し、サーバーが実装でき、データ構造、エラー、認証に曖昧さがない水準を目指します。

概要

このスキルは、優れたAPI 仕様、つまり API サーフェスのエンジニアリング上のワイヤーコントラクトを作成する方法を説明します。各操作がワイヤー上でどのように見えるかを定めます。具体的には、リクエストとレスポンスのデータ構造（フィールド、型、必須／任意、制約）、認証モデル、エラーモデル、実例です。このスキルが担うのは、作成者の判断力、すなわち調査方法と品質基準であり、セクションの一覧ではありません。セクションの構成を提供するAPI 仕様テンプレートツールと、確立された API 設計の実践に基づくコントラクトの作成を支える詳細調査機能という、2 つの協力者がいることを前提とします。作成者には、API が公開する必要のある動作を定めた上流の feature-specと、存在する場合はサービス境界を示すarchitecture-doc、およびリソースが対応するエンティティを示すdata-modelが渡されます。白紙の状態から始めることはありません。満たすべき基準は、コントラクトが実装可能で、呼び出し可能であることです。クライアントエンジニアはすべての操作を正しく呼び出せ、サーバーエンジニアは作成者に確認することなく実装でき、データ構造、エラー、認証に曖昧さがない必要があります。

使用するタイミング

• API が公開する必要のある動作を定めた、承認済みの feature-spec から API 仕様を作成するとき。
• API サーフェス（REST、GraphQL、RPC/gRPC）の操作、リクエスト／レスポンスのスキーマ、認証、エラーモデル、実例を仕様化するとき。
• 調査に基づき、判断が確定した、完全に型付けされた操作ごとの内容で API 仕様テンプレートを埋めるとき。
• 承認済みの API 仕様を、バージョン管理された差分として改訂するとき（操作の追加／変更、フィールドの追加／削除、パラメーターの必須化、操作の廃止など）。Step 6 を参照してください。

次の場合は使用しないでください：

• 永続化データモデル（保存されるエンティティとその関係）を設計する場合 → これは別の懸案事項であり、ここでは上流にあたります。API 仕様ではワイヤー DTO を記述し、データモデルを参照します。DTO は保存される行ではありません。
• 公開済みの、利用者向け API リファレンス（エンドユーザーが読む文章形式のドキュメントで、多くの場合このコントラクトから生成されます）を作成する場合 → これは対象読者が異なる、別の下流ドキュメントです。
• 実装／アーキテクチャ（エンドポイントの背後にあるサービスの構築方法）を記述する場合 → これは設計レイヤーであり、インターフェースではありません。
• 完成した API 仕様をレビューまたは評価する場合 → reviewing-api-spec を使用してください（専用のゲートで、このスキルの Step-7 の基準と一元管理されています）。このスキルは作成側専用です。
• feature-spec 自体（動作）を作成する場合 → これはここでの上流入力です。

Inputs

プランで渡されたすべてのドキュメント、つまり depends_on セット（このドキュメントに情報を提供するとディスカバリーで特定された上流ドキュメント）を読み、このドキュメントの内容をそれらにたどってください。入力が固定されていると思い込まないでください。このスキルが挙げる典型的な上流ドキュメントは、受け取る入力の上限ではなく、手法の指針です。自己完結させてください。実際に受け取ったコンテキストからドキュメントを作成し、情報源として想定されるドキュメントがない場合は、手元にある情報で作業を進め、その不足を明示的な前提として示してください。埋め合わせのために捏造してはいけません。また、利用可能な場合はリサーチ機能（deep-research）を使い、テンプレートを埋めるだけでなく、包括的かつ網羅的なドキュメントにしてください。

機能コンテキスト（提供される場合）： 呼び出し元から capability_record（capability-map.yaml product_capabilities のレコード）が渡された場合は、Step 1 の前に読み込んでください。これは担当範囲を定めます。owns = 担当するエンティティ、refs = 参照するが担当しないエンティティ、publishes／consumes = 表面化させるイベント、entry_points／exit_points = ユーザーがアクセスする場所と離脱する場所、has_ui／has_api／has_persistence = 該当するインターフェースです。存在する場合は、これを厳守すべき制約として扱い、定義された範囲から逸脱しないでください。

Workflow

Step 1: テンプレートツールから構成を取得する — アウトラインを独自に考案しない

api-spec テンプレートツール（包括版）からセクション構成を取得してください。ここでセクションの一覧を言い換えたり、再構成したりしないでください。このスキルが提供するのは、各セクションを適切に埋めるための手法です。テンプレートを利用できない場合は、包括的な api-spec の構成を取得する（依頼して作成してもらうか、次の標準構成を使用する：API の概要、操作一覧、操作ごとのリクエストとレスポンス、共通データ型、認証と認可、エラーモデル、ページネーション／フィルタリング／レート制限、例、未解決の質問）うえで、作業を進めてください。

capability_record が存在する場合：entry_points を API 操作として公開し、publishes／consumes イベントに対応する非同期操作を含め、refs のフィールドには読み取り専用の機能横断参照であることを明示してください。

Step 2: まず API スタイルを選び、そのスタイルの記法で同じ厳密さを適用する

プロジェクトが使用する API スタイルは1 つです。スタイルを選び、そのスタイルの記法でコントラクトを記述してください。ただし、厳密さ（型付きスキーマ、完全なエラー、認証、例）は 3 つすべてで同一です。

• REST → OpenAPI／JSON-Schema の規約：エンドポイント一覧（メソッド＋パス）、型付きパラメーターとリクエストボディ、HTTP ステータスごとに定義したレスポンス、再利用可能なスキーマ、宣言されたセキュリティスキーム。
• GraphQL → SDL：型付きのオブジェクト／スカラー／列挙型／入力型、Query／Mutation／Subscription のルートフィールド、トップレベルの errors 配列内のエラー。
• RPC / gRPC → 型付きリクエストおよびレスポンスメッセージとステータスコードを含む proto の service／rpc メソッドシグネチャ。

REST 以外のプロジェクトに OpenAPI を必須としてはいけません。OpenAPI は REST 向けの形式であり、唯一の形式ではありません。このスキルは、プロジェクトが使用するスタイルに関わらず、コントラクトを厳密に定義する方法を扱います。

Step 3: 上流ドキュメントを読み込み、feature-spec を基準に網羅性を確保する

承認済みの feature-spec と、上流のコンテキスト（architecture-doc、data-model）を読み込んでください。これらは入力であり、白紙ではありません。feature-spec の動作を、操作の網羅性を確認するチェックリストとして使用してください。API が公開する必要のある動作はすべて 1 つ以上の操作に対応させ、すべての操作を何らかの動作に結び付けてください（孤立した操作や、独自に作り出したエンドポイントを設けないでください）。各リソースを data-model のエンティティに参照で対応付け、ワイヤー DTO と保存されるエンティティが異なる箇所（計算済み、派生、または省略されたフィールド）を記してください。data-model と重複したり、矛盾したりしないようにしてください。上流ドキュメントの情報が不十分な場合は、黙って形状を作り出すのではなく、未解決の質問または明記された前提としてその不足を示してください。

ステップ 4：契約を裏付けるための調査

この製品のインターフェースに即して、確立された API 設計の実践例を深く調査し、契約の根拠としてください。REST／HTTP のセマンティクスとステータスコード、JSON Schema／OpenAPI の厳密さ、GraphQL SDL、RPC／gRPC、一貫性のある命名、エラーモデリング（REST の RFC 9457 Problem Details など）、バージョニング、認証パターンなどが対象です。「一般的な API 仕様」ではありません。調査機能を利用できない場合は、フィールド名、制限、ステータスコード、エラーコードを捏造しないでください。実装前に検証が必要な仮定として、明示してください。

ステップ 5：セクションごとの手法を適用する

この手法に従って、テンプレートの各セクションを記入してください。薄い API では不要なセクションをまとめ、規模に応じて調整してください。

• API の概要 — スタイル＋トランスポート、ベース URL／エンドポイント、具体的なバージョニング方式を記載します（URL パスの /v1 が最も曖昧さがなく、一般的です。AIP-185 に従い、メジャーバージョンのみとします。最初からバージョニングを計画してください）。命名規則と日付／時刻の規約はここにまとめて記載します。
• バージョニングポリシー — 変更を分類し、廃止を計画する（初日から明記）。 破壊的変更に該当するものを明記します。追加的変更＝寛容な読み取り側のクライアントが無視する新しい任意フィールド／操作／列挙値（クライアントは未知のレスポンスフィールドを無視する必要があります）。破壊的変更＝削除／名前変更／型の範囲縮小／必須項目の追加／デフォルト値の変更／意味の変更（AIP-180 のソース／ワイヤー／意味に関する定義）。また、削除に伴う非推奨化からサンセットまでのライフサイクルも記載します。Deprecation（RFC 9745。非推奨になった日付）→移行期間→Sunset（RFC 8594。応答を停止する可能性のある日付。Sunset ≥ Deprecation）＋公開済みの移行手順。この場でポリシーを記載し、変更時に特定の操作を非推奨化する作業はステップ 6（修正）で行います。
• リソース／操作一覧 — 操作ごとに 1 行で、メソッド＋パス／ルートフィールド／Service.Method をあらかじめ記載し、各操作の詳細に入る前に API の全体像を把握できるようにします。
• 操作ごとのリクエスト＋レスポンス — 両方を完全に型定義する。 すべてのパラメーター／引数／フィールドに、型、必須／任意の区分、制約（長さ、列挙値、形式、範囲）を持たせます。すべてのレスポンスは、ステータスコード（または gRPC ステータス／GraphQL の data と errors）と本文スキーマを対応づけます。ステータスは意図的に選択してください。作成には 201＋Location、本文のない成功には 204、401（未認証）と 403（権限なし／スコープ不足）を混同せず、競合には 409、バリデーションエラーには 422／400 を使用します。すべてに 200 を使わないでください。成功時の経路しか仕様化されていない操作は未完成です。
• 共通データ型 — 再利用可能な DTO はそれぞれ一度だけ定義し、名前で参照します（$ref／SDL 型／proto メッセージ）。同じ形状を操作ごとにインラインで再定義しないでください。これらはワイヤー型です。DTO が保存済みのエンティティを表す場合は、データモデルを参照し、再記述しないでください。
• 認証＋認可 — スキーム（API キー／OAuth 2.0 と使用するフロー。ユーザー向け／公開クライアントには認可コード＋PKCE、サービス間通信にはクライアントクレデンシャル／JWT／mTLS）と、認証情報の送信先を明記します。また、認可モデルとして、公開されていないすべての操作に必要なスコープ／ロールを記載し、操作一覧の認証スコープ列に対応づけます（操作ごとのスコープを指定せずに「認証済み」とするだけでは仕様が不十分です）。トークンのライフサイクル、HTTPS の使用、URL にシークレットを含めないことも明記します。
• エラーモデル — 成功時の経路だけでなく、エラーの一覧を定義する。 API 全体で一貫したエラー形式を 1 つ定義します（REST では RFC 9457 Problem Details、GraphQL では errors 配列、gRPC では google.rpc.Status など）。形式には、機械可読なコード（クライアントはこれに基づいて分岐します。HTTP ステータスだけでは粒度が粗すぎます）、人間向けメッセージ（ログ用であり、エンドユーザーへの表示には使いません）、リクエスト／トレース IDを含めます。次に、操作ごとに名前の付いたすべての失敗ケース（バリデーション、認証、権限なし、見つからない、競合、レート制限、サーバー）をステータスコードとともに列挙し、再試行可能かどうかも示します（429／5xx は Retry-After に従ってバックオフ後に再試行可能、4xx は不可です。再試行しても解決しません）。これは API 仕様で最も見落とされがちな項目です。意識して丁寧に定義してください。
• ページネーション／フィルタリング／ソート／レート制限 — コレクション操作ではページネーション方式を選びます（大規模／動的／ユーザー向けにはカーソルベース、小規模／静的にはオフセットベース）。リクエストパラメーターとレスポンスのエンベロープ（次のカーソル／has-more／Link ヘッダー）、デフォルトと最大のページサイズを定義します。フィルター可能なフィールドとソート可能なフィールドを、安定したタイブレーカーとともに列挙し、レート制限、ヘッダー、429 の動作を明記します。
• 記述例 — 主要な操作ごとに、スキーマと整合する完全なリクエスト／レスポンスのペアを 1 つ以上示します（フィールド名、型、ステータスコードを一致させます）。スキーマと矛盾する例は欠陥です。

Step 6: 承認済みコントラクトの修正（差分のケース）

コントラクトがすでに存在し、変更が求められている場合は、描き直さずに差分を編集します。対象範囲は、変更のあった操作とそのリクエスト／レスポンスのスキーマ、共有型、それらに関するエラーケース（変更が破壊的な場合はバージョニングのセクションも）です。そのうえで、次の手順に従います。

1. 変更を分類します（追加的変更か破壊的変更か）。 追加的変更（新しい任意フィールド、新しい操作、寛容な読み取り側が無視する新しい任意レスポンスフィールド、新しい任意エラーケース）は、同じバージョン内でリリースします。破壊的変更（フィールドや操作の削除／改名、型の範囲の縮小、任意フィールドの必須化、デフォルト値／セマンティクスの変更、列挙値の削除）は、同じバージョンのままインプレースで編集してはいけません。破壊的変更を同じバージョン内のマイナー変更としてリリースすると、稼働中のすべてのクライアントが気づかないうちに壊れます。これが、修正時に最も重大な欠陥です。
2. 破壊的変更は編集ではなく、バージョニングのイベントです。 変更を新しいバージョン（/v2、新しい日付固定版）に振り分け、古いサーフェスには廃止予定の通知から終了までのライフサイクル（Deprecation → 移行期間 → Sunset、Sunset ≥ Deprecation）を適用し、移行ガイド（旧版から新版へのマッピング）を用意します。古い操作を黙って変更したり削除したりしてはいけません。
3. 後方／前方互換性を分析します。 後方互換性：既存バージョンが引き続き動作すること。前方互換性：新しいフィールドは任意またはデフォルト値ありとし、列挙値の追加は許容され、操作の意味が黙って変わることはないこと。
4. 差分のバージョンと変更履歴を記録します。 ドキュメント自体のバージョン（API バージョンとは別の §10 改訂履歴）を上げ、変更履歴の項目（追加的変更／破壊的変更）を追加します。廃止対象の操作には、黙って削除するのではなく、廃止予定のマークを付けます。
5. 下流／上流への波及を明示します。 変更は、下流の api-reference（変更されたコントラクトと廃止予定のマーカーから再同期／再生成）、それを基に構築する実装とテスト計画、稼働中のクライアント（終了までの移行期間を設ける理由）、リリース手順書へと波及します。上流の feature-spec を先に修正します（新しい動作が新しい操作を必要とするため）。波及先を明記し、下流の読者が後から気づく状態にしてはいけません。

グリーンフィールドの最初のコントラクトでは、修正する以前のバージョンがないため、Step 6 は省略します。

ステップ 7：引き継ぐ前に、曖昧さを許容しない基準に照らして自己チェックする

以下のすべてを満たしていることを確認します（これは、実行時レビューゲートである reviewing-api-spec が適用する基準です。作成者とゲートがこの基準を共有することで、認識のずれを防ぎます）。

1. スタイル + 基本情報 + バージョニングが記載されている — API スタイル、ベース URL／エンドポイント、具体的なバージョニング方式が記載されており、破壊的変更と非破壊的変更のルール、および非推奨化からサンセットまでのポリシーが明記されている。
2. すべての操作が列挙され、対応付けられている — 操作の一覧に漏れがなく、各操作が上流の機能仕様の動作に対応している（孤立したエンドポイントや架空のエンドポイントがなく、欠落もない）。
3. すべての操作について、両側の型が完全に定義されている — リクエストとレスポンスの型が完全に定義され、各フィールドが制約とともに必須か任意か明示され、すべてのレスポンスにステータスコードが対応付けられている。正常系のみの操作は不合格です。
4. 認証 + 操作ごとの認可 — 認証方式（クライアントの種類ごとの OAuth フローを含む）が記載されている。非公開の操作すべてについて、必要なスコープ／ロールが明記されている。トークンのライフサイクルと HTTPS も記載され、暗黙的に公開されている操作がない。
5. エラーモデルが完全に定義されている — 一貫したエラー形式（機械可読なコード + メッセージ + リクエスト ID）が定義され、各操作で発生し得るすべてのエラーケースが、再試行可能かどうかとともに列挙されている。2xx レスポンスだけを列挙した仕様は不合格です。
6. 共通型を一度だけ定義し、参照している — 再利用可能な DTO は一度だけ定義され、参照されている。ワイヤー型は、データモデルを再記述したり矛盾したりせず、データモデルを参照している。
7. ページネーション／レート制限が規定されている — コレクション操作でページネーションが定義されている。レート制限とヘッダーも記載されている。
8. 例があり、一貫している — 主要な操作ごとに少なくとも 1 組のリクエスト／レスポンス例があり、スキーマと完全に一致している。
9. 命名とバージョニングに一貫性がある — API 全体で統一して適用されている。
10. 根拠があり、誠実で、一方向性が保たれている — 操作と構造が機能仕様およびデータモデルを反映している（捏造されておらず、情報の不足は創作で補わず、仮定／未解決の質問として明らかにされている）。api-reference に対する一方向性が保たれている（この契約が公開リファレンスの信頼できる唯一の情報源であり、公開リファレンスから逆解析してはなりません）。稼働中の API が存在する場合、現在の操作や構造に関する記述がリリース済みの API の実態と一致している（新規開発の場合：該当なし）。
11. （変更のみ）差分の範囲が適切で、分類・バージョニングされている — 変更依頼の場合、変更した操作は変更箇所について 1〜10 を満たしている。変更が追加的変更か破壊的変更かに分類されている。破壊的変更には、新しいバージョン + 非推奨化からサンセットまでの計画 + 移行ガイドが含まれている。後方／前方互換性が分析され、上流／下流への波及が明示されている。ドキュメントのバージョンが更新され、変更履歴が記載されている。廃止する操作には削除ではなく非推奨のマークが付けられている。新規開発の初回構築の場合は該当なし。

入力が不十分な場合のゲート： API が公開すべき動作について調査できず、契約に含めることを信頼できる形で仮定することもできない場合は、構造を捏造せず、ブロッカー（「操作の定義が不十分 — プロダクト／エンジニアリングの判断が必要」）として明示します。構造、エラー、認証のすべてが推測に基づく api-spec では、呼び出し可能な API を定義できません。

ルール

必ず守るルール（例外なし）：

• すべての操作のリクエスト側とレスポンス側を型定義します。 リクエストとレスポンスを完全に型定義し、各フィールドを制約とともに必須または任意として明示し、すべてのレスポンスをステータスコードに対応付けます。型定義のないフィールドや明示されていないステータスがあってはなりません。
• エラーケースを列挙します。 各操作について、失敗ケース（バリデーション、認証、見つからない場合、競合、レート制限、サーバーエラー）とステータスコードを明記します。正常系だけの操作は不完全です。
• 一貫したエラー形式を使用します。 API 全体で単一のエラーレスポンス形式（機械可読コード＋メッセージ＋リクエスト ID）を共有します。エンドポイントごとに異なるエラー本文を作成してはいけません。
• データモデルを参照し、再定義しません。 ワイヤー DTO は参照によって上流のデータモデルのエンティティに対応付け、差分を記載します。保存済みのスキーマを再記述したり、矛盾させたりしてはいけません。DTO は保存された行ではありません。
• api-reference とは一方向の関係です。 公開されているコンシューマー向けの api-reference は、このコントラクトの下流にある利用者で、多くの場合、このコントラクトから生成されます。このコントラクトが api-reference の信頼できる唯一の情報源です。公開ドキュメントからコントラクトを逆算してはいけません（依存関係が逆転します）。data-model は上流、api-reference は下流です。
• 破壊的変更には新しいバージョンを割り当て、既存のバージョン内で編集しません。 変更時には追加的変更か破壊的変更かを分類します。破壊的変更は、新しいバージョンと、移行パスを伴う Deprecation→Sunset のライフサイクルに進めます。同じバージョンの稼働中の操作を、通知なく変更したり削除したりしてはいけません（ステップ 6）。
• すべての操作を feature-spec の動作に対応付けます。 対応付けのない操作や、仕様にない操作を含めてはいけません。また、動作の抜け漏れも許されません。カバレッジは feature-spec に基づいて確認します。
• 記法にかかわらず厳密さを保ち、OpenAPI のみに限定しません。 プロジェクトで採用している記法（REST なら OpenAPI、GraphQL なら SDL、RPC なら proto）で記述し、どの形式でも同じ厳密さを適用します。REST 以外の API に OpenAPI を強制してはいけません。
• 例をスキーマに一致させます。 すべての例で、スキーマが定める正確なフィールド名、型、ステータスコードを使用します。スキーマと矛盾する例は不具合です。
• 決して捏造しません。 完全に見せるためにフィールド名、制限、ステータスコード、エラーコードを作り出してはいけません。根拠となる情報がない場合は、ビルド前に検証が必要な仮定であることを明示します。
• 重複させず、組み立てます。 セクション構成にはテンプレートツールを使用し、このスキルはその構成を埋める方法として使います。別の構成案を貼り付けてはいけません。
• 実装でも公開リファレンスでもなく、コントラクトを作成します。 サービスの構築方法やエンドユーザー向けの説明文ではなく、インターフェース（ワイヤー形式）を規定します。
• 機能の境界（capability_record が提供されている場合）： ドキュメントの出力範囲を、そのレコードの境界内に限定します。境界外の内容（refs エンティティを自らの管理対象であるかのように扱うことや、exit_point を越えたフローの設計など）を含めるのは、仕様にない内容を捏造するのと同等のスコープ違反です。

推奨事項（上書き可能）：

• 「包括的」とは出力の意欲の高さを意味します。コントラクト（すべての操作の型定義、エラーの列挙、認証の明記）を完全にすることに重点を置き、分量は適切な範囲に保ちます。薄い API なら、不要なセクションはまとめます。
• REST のエラー本文には RFC 9457 Problem Details を優先し、大規模または動的なコレクションにはカーソルベースのページネーションを優先します。
• プロジェクトでヘッダーベースまたは日付ベースの方式が標準化されていない限り、URL パスによるバージョニング（/v1）を優先します。

落とし穴

• 成功パスしか扱わない操作。 200 の本文を指定して終わりにするのは、API 仕様で最もよくある欠陥です。各操作では、ステータスコードとともに 4xx／5xx の失敗ケースをすべて列挙する必要があります。エラーカタログは契約の一部であり、後回しにするものではありません。
• データモデルを DTO として再定義する。 保存されたエンティティをインラインで再定義すると、元のデータモデルから乖離し、矛盾が生じます。データモデルを参照し、ワイヤー上の形式が異なる箇所（計算済み／派生フィールドや省略フィールド）のみを記載してください。
• 契約と公開リファレンスを混同する。 これはビルドが準拠するエンジニアリング契約です。多くの場合、この契約から生成される利用者向けリファレンスは、対象読者の異なる別の下流ドキュメントです。ここにエンドユーザー向けの説明を書かないでください。
• OpenAPI に視野が偏る。 GraphQL API や gRPC API に OpenAPI を使うのは、スタイルに合いません。プロジェクトで採用しているスタイルを選び、その記法（SDL／proto）で記述してください。
• スキーマから乖離した例。 スキーマに定義されていないフィールドや、誤った型／ステータスを含む例は、気づかないうちに契約を壊します。例は宣言済みのデータ形状と一致させてください。
• テンプレートの構成を繰り返す。 内容の中（またはこのスキル内）でセクション一覧を再構成すると、テンプレートツールと重複し、乖離が生じます。判断を加えながら、テンプレートの各セクションを埋めてください。

対比例 — 仕様不足（表面上は準拠）と呼び出し可能な仕様（自己チェックに使用）：

項目	仕様不足（却下）	呼び出し可能な仕様（リリース可能）
操作の対応関係	「請求書用のエンドポイントがあります。」	「POST /v1/invoices は feature-spec §3.2 請求書の作成 を実装し、Invoice データモデルエンティティを射影します（internalLedgerId は省略）。」
リクエスト	「請求書のフィールドを受け取ります。」	「本文：amount（整数、必須、>0、最小通貨単位）、currency（文字列、必須、ISO-4217）、dueDate（文字列、省略可、RFC-3339）。」
レスポンス	「請求書を返します。」	「201 → Invoice スキーマ（セクション 4）。Location ヘッダーには新しいリソースを設定します。」
エラーモデル	「エラーが返されます。」	「400 validation_error（不正なフィールド）、401 unauthorized、403 forbidden（invoices:write が不足）、409 conflict（冪等性キーの重複） — すべて共通の Problem-Details 形式です。」
認証	「認証が必要です。」	「OAuth 2.0 bearer。スコープ invoices:write が必要です。」
例	「ドキュメントを参照してください。」	「amount: 5000、currency: \"USD\" を使用したリクエスト／レスポンスのペア。201 の本文は Invoice スキーマと完全に一致します。」

記述が左列のように読めるなら（どの API にも当てはまり、型もステータスコードもエラーケースもない）、まだ完成していません。

アンチパターン

• 「成功パスだけ仕様化すれば、エラーは明らかです。」 明らかではありません。失敗ケースをステータスコードとともにそれぞれ明記しなければ、クライアントは対処できません。
• 「エンティティをリクエスト／レスポンスの形式として再定義します。」 データモデルを参照してください。再記述すると乖離し、矛盾が生じます。ワイヤー上の差分のみを記載してください。
• 「OpenAPI が標準なので、すべてに使います。」 OpenAPI は REST の形式です。GraphQL API には SDL、gRPC API には proto が必要です。プロジェクトのスタイルに合わせてください。
• 「これも API リファレンスなので、エンドユーザー向けの説明を書きます。」 契約と公開リファレンスは、対象読者の異なる別のドキュメントです。これはエンジニアリング契約として維持してください。
• 「構成は自分で書きます。」 テンプレートツールと重複します。構成はテンプレートから使用してください。
• 「調査は省略します。REST は分かっています。」 調査によって把握するのは API 理論ではなく、このプロダクトの API サーフェス、命名、エラーモデルです。
• 「小さな変更なので、フィールドをその場で編集します。」 同じバージョンで破壊的変更（名前の変更／削除／型の制限／必須化）を行うと、稼働中のすべてのクライアントを気づかないうちに壊します。変更を分類し、新しいバージョンに移行したうえで、移行ガイドを伴う Deprecation → Sunset のライフサイクルに沿ってください（ステップ 6）。

出力

包括的な API 仕様。Step 7 の曖昧さを排除する基準（スタイル＋ベース＋バージョニング［＋破壊的変更のルール＋非推奨化／サンセットポリシー］を明記すること。すべての操作を列挙し、追跡可能にし、両側の型とステータスコードを完全に指定すること。認証＋操作ごとの認可を明記すること。すべての失敗ケースに名前を付け、再試行の可否を示す完全なエラーモデルを定義すること。共有型は一度だけ定義し、データモデルを参照すること。ページネーション／レート制限を指定すること。一貫性のある例を含めること。命名／バージョニングに一貫性を持たせること。api-reference に基づき、一方向の関係にすること。何も捏造しないこと）を満たし、変更時にはバージョン付き差分として改訂します（Step 6：追加的変更か破壊的変更かを分類し、破壊的変更は新しいバージョンに振り分け、非推奨化→サンセットを設定し、波及範囲を明示します）。成果物はテキスト形式です。エンドポイントの表＋フェンス付きスキーマブロック（JSON／OpenAPI フラグメント／SDL／proto）＋リクエスト／レスポンスの例のペアで構成します。手法と基準は媒体に依存しません。想定する利用者は、契約に基づいて連携するクライアントエンジニア、これを実装するサーバーエンジニア、契約から生成されることの多い下流の公開 api-reference、そして同じ基準を適用する reviewing-api-spec ゲートです。api-spec は入力として feature-spec に依存し、data-model を参照します。構成はテンプレートツールが提供し、このスキルはコンテンツの品質を担います。

関連項目

• api-spec テンプレートツール（例：コンテンツ／テンプレートのゲートウェイ）— このスキルが内容を埋めるためのセクション構成を提供します。組み合わせて使用し、アウトラインを再記述しないでください。
• 詳細調査機能 — 確立された API 設計手法（REST／HTTP、OpenAPI／JSON-Schema、GraphQL SDL、gRPC、エラーのモデリング、バージョニング、認証）に基づいて契約を作成します。
• feature-spec-authoring スキル — この契約が公開する動作を記述する上流の feature-spec を作成します。
• architecture-doc と data-model（存在する場合）— 上流のコンテキストです。サービスの境界と、ワイヤー DTO が参照するエンティティを示します。
• reviewing-api-spec — 完成した api-spec 専用のレビューゲートです。同じ曖昧さを排除する基準を適用します（その条件は、このスキルの Step 7 セルフチェックと一対一で同じ情報源から定義されており、作成者とゲートの間にずれが生じません）。汎用の design-review は api-spec 成果物のレビューを、この対となるゲートに委ねます。
• 利用者向け API-reference スキル — 公開される下流のリファレンスを作成します。これは独立した文書であり、この契約から生成されることがよくあります。

段階的な情報開示

• references/contract-method.md — 契約の中核に関する詳細です。スタイルの選択＋操作／メソッドの意味論（RFC 9110）＋ステータスコードの選定＋両側の型指定＋完全なエラーモデル（RFC 9457＋マシンコード＋再試行可否）＋認証／操作ごとの認可＋ページネーション／同順位時の決定規則を扱います。セクションの作成に詳しい手順が必要な場合に読み込んでください。
• references/versioning-and-amend.md — バージョニング＋進化に関する詳細です。方式（URL パス／ヘッダー／日付ベース、AIP-185）、破壊的変更と非破壊的変更の分類（AIP-180）、非推奨化→サンセットのライフサイクル（RFC 9745/8594）、Step 6 の改訂方法＋上流／下流への波及を扱います。バージョニングや改訂を行う場合に読み込んでください。
• references/sources.md — 手法＋品質基準の調査元（OpenAPI、JSON Schema、GraphQL SDL、gRPC/protobuf、RFC 9110/9457、RFC 8594/9745、AIP-180/185、REST 設計＋エラー／ページネーションのガイド）を示します。ガイダンスの出典を監査する場合にのみ読み込んでください。

本文の予算

• description は 1,024 文字以下です（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークンを目安とします（ソフト目標です。品質を優先し、700 行／7,000 トークンを継続的に超える場合は明示してください）。
• 詳細な内容は references/ に置き、必要に応じて読み込みます。

変更履歴

• 1.3.0 (2026-06-21) — capability_record コンテキスト注入：呼び出し側から任意で注入された capability_record をステップ 1 で使用します（entry_points/publishes/consumes/refs に基づくスコープ境界）。capability_boundary ルールを追加し、本文の予算を目標値に変更しました。レコードが注入されない場合は、適切にフォールバックします。
• 1.2.0 (2026-06-15) — 本番環境向けのペア（新たに追加された reviewing-api-spec の双子と単一ソースを共有）に合わせて再構成しました。修正メソッドを追加しました（ステップ 6：追加変更／破壊的変更を分類 → 破壊的変更は新しいバージョンと Deprecation→Sunset のライフサイクルを伴う → 互換性 → バージョンと変更履歴 → api-reference/impl/clients への前方／下方への波及）。バージョニング（破壊的変更と非破壊的変更の分類、および非推奨化から廃止までのポリシー、AIP-180/185 と RFC 8594/9745）、操作ごとの認可（公開されていないすべての操作でスコープを明示し、クライアントの種類ごとに OAuth フローを指定）、エラーモデル（機械可読コード + リクエスト ID + 再試行可能性）、ステータスコードの選択、および api-reference との一方向性ルールを詳述しました。セルフチェックをステップ 7 まで拡張しました（cond-1/4/5/10 を詳述し、新たに cond-11 の修正を追加）。双子の 11 個の条件と 1:1 で単一ソースを共有しています。ゲート参照先を reviewing-api-spec に変更しました。references/contract-method.md と references/versioning-and-amend.md を追加しました。従来のカバレッジは削除していません。
• 1.1.0 (2026-06-04) — 初回レビュー済みリリース。