reviewing-api-spec

reviewing-api-spec — SKILL.md

バリアント： standard · 使用する場面： 完成した api-spec ドキュメントを受け入れゲートとして評価する場合 — クライアントがすべての操作を呼び出せること、サーバーが契約だけをもとに実装できることを確認し、実行可能な指摘事項とともに VERDICT: approve|revise を出力します。新規開発、または変更分に範囲を絞った修正に使用します。

概要

このスキルは、api-spec の作成と評価を行うペアのうち、レビューを担います。API サーフェスのエンジニアリング上のワイヤー契約（操作、リクエストとレスポンスのスキーマ、認証、エラーモデル、ページネーション／レート制限、バージョニング、例）である完成した api-spec ドキュメントを受け取ったレビュアーが、次の一点に照らしてそのドキュメントを評価します。クライアントエンジニアはすべての操作を正しく呼び出せるか、サーバーエンジニアはこのドキュメントだけをもとに、データ構造、エラー、認証に曖昧さなく実装できるか。 固定の契約完全性チェックリスト（11 項目）を適用します。これは api-spec の作成者が従う基準（authoring-api-spec の Step-7 セルフチェック）と同じであり、作成基準とレビュー基準が乖離しないようにしています。そのうえで、機械解析可能な単一の判定と、作成者が1回の修正で対応できる指摘事項を出力します。これは受け入れゲートです。契約の作成、修正、書き換えは行いません。評価して指摘事項を返し、作成者が修正します。

作成者と同じ基準を用います。作成者の手法 — 表記スタイル（OpenAPI／GraphQL SDL／proto）、明示された RFC の規約（RFC 9457、RFC 8594/9745、AIP-180/185）、JSON-Schema の知識 — は、レビュアーが結果を評価するための補助です（各操作が両側で型付けされているか、一貫したエラー形式があり、すべての失敗ケースに名前が付いているか、例がスキーマと一致しているか）。要求条件ではありません。ただし、境界に注意してください。 完全なエラーモデル（条件5）、両側の型付け（条件3）、操作ごとの認可（条件4）は、api-spec の実際の、重要な条件です。これはワイヤー契約であるため、「実装の詳細」としてレビューを甘くしてはいけません。補助となるのは手法（明示された表記法／RFC）であり、要求されるのは結果（型付けされた操作、完全なエラーカタログ、操作ごとのスコープ）です。

スタイルに依存しない（重要）。 契約には REST（OpenAPI/JSON-Schema）、GraphQL（SDL と errors 配列、および nullability）、RPC/gRPC（proto と google.rpc.Status）があります。それぞれのスタイルに沿って評価してください。GraphQL 契約にはHTTP ステータスコードがないのが正当です（エラーは errors 配列で送信され、型付けされたペイロードまたはエラーがレスポンスです）。gRPC 契約では HTTP ではなく、google.rpc.Status と標準コードを使用します。REST 以外の契約に REST/OpenAPI の慣例を要求するのは、典型的な OpenAPI 反射による誤った revise 判定です。そうしてはいけません。スタイル非依存の原則は、条件2（操作）、条件3（両側の型付け）、条件5（エラーモデル）に適用されます。これらは契約が採用するスタイルに応じて評価してください。

有効化するタイミング

• 完成した api-spec ドキュメントについて、クライアントの統合またはサーバーの実装前に、承認するか修正を求めるかを判断する必要がある場合。
• 作成者が作成した api-spec を、独立したレビュアー／ゲートキーパーとして審査する場合。
• 以前の判定が revise だった api-spec の改訂版を再審査する場合。
• 承認済みのコントラクトと変更リクエストからなる amend を、差分に限定して審査する場合（cond-11）。

次の場合は有効化しないでください：

• api-spec の作成または修復を行う場合 → authoring-api-spec を使用してください。このスキルはコントラクトを作成しません。
• data-model（ワイヤー DTO が参照する保存済みエンティティ――上流の、一方向の関係）または feature-spec（機能の動作を定めるもの――上流）を審査する場合 → これらはそれぞれ独自のゲートを持つ別個のドキュメントです。
• 公開済みの、利用者向け api-reference（多くの場合、このコントラクトから生成される、文章形式のエンドユーザードキュメント――下流）を審査する場合 → reviewing-api-reference を使用してください。このコントラクトは api-reference の信頼できる唯一の情報源であり、その逆ではありません。
• コントラクトを実現する 実装／サーバーコードを審査する場合 → このゲートが評価するのはコードではなく、設計ドキュメントです。
• 一般的／臨時のエンジニアリング設計ドキュメント、RFC、ADR、仕様、または計画を審査する場合 → design-review を使用してください。このゲートは、doc-library の api-spec 成果物を対象とします。その識別には template: api-spec のフロントマターを正式な根拠として使用します。フロントマターがない場合は、# API Specification 見出しを補助的なシグナルとしてのみ使用します。
• テンプレート／セクションへの準拠を確認する場合 → それはテンプレートの問題です。このスキルが判断するのは、すべての見出しが存在するかどうかではなく、基準に照らした品質です。

ワークフロー

ステップ 1：コントラクト全体を、初めて読むつもりで独立した視点から読む

api-spec ドキュメントを最初から最後まで、初めて目にするものとして読みます。次の段階（クライアントによる統合とサーバーによる実装）を判断するゲートキーパーとして臨みます。指摘に意味があるのは、その API が設計どおりに呼び出せない、または実装できないことを示す場合に限られます。上流の feature-spec（提示されている場合は data-model も）を手元に置いてください。cond-2／cond-6／cond-10 では、コントラクトをそれらと照合します。まず API スタイル（REST／GraphQL／gRPC、または混在）を判別し、それぞれ固有の慣例に沿って評価してください。入力となるのはドキュメントそのものです。操作一覧、操作ごとのスキーマ、エラーカタログ、共有型、認証セクション、例はすべてそこに含まれています（テンプレートのセクション）。別途、付随成果物を用意する必要はありません。これは amend ですか？ 既存のコントラクトに対する変更リクエスト／差分を受け取った場合は、差分に限定した手順を実行します（cond-11 を有効にし、変更された操作とその分類、非推奨化／影響範囲に対象を絞ります）。グリーンフィールドで初回構築する場合は変更リクエストがないため、cond-11 は該当しません。

ステップ 2：コントラクト完全性チェックリストを実行し、各条件を判定する

各条件について、合格または不足と判定します。条件が不合格となるのは、実際に特定できる欠陥がある場合だけです。「別の設計にしたかった」は不足には該当しません。条件は共有された唯一の基準です。独自の条件を追加しないでください。

以下のケイパビリティ境界のチェック項目を適用するのは、capability_record が作成時の呼び出しに挿入され、レビュー時のコンテキストとして利用できる場合のみです。存在しない場合は該当しないものとして扱ってください。境界が定義されていないのに、ケイパビリティ境界のマーカーがないことを理由にドキュメントを減点してはいけません。

1. スタイル、ベース、バージョニング。 API のスタイル、ベース URL／エンドポイント、具体的なバージョニング方式が示されており、破壊的変更と非破壊的変更のルール、および非推奨化から提供終了までのポリシーが明記されています。バージョニング方式が欠けている、または破壊的変更のルール／非推奨化ポリシーがない場合は、ギャップです。(簡略化：v1 のグリーンフィールド API では、まだ非推奨のものがなくてもポリシーを明記します。簡略化されない基本要件 — 規模を問わず、スタイル、ベース、バージョニング方式が示されていること。)
2. すべてのオペレーションが一覧化され、追跡可能であること。 オペレーション一覧が完全で、ざっと確認できること。各オペレーションが上流の機能仕様の動作に対応していること（孤立した／創作されたエンドポイントがなく、漏れもないこと）。メソッドと成功ステータスの意味が正しいこと（状態を変更する GET や、本来 201 であるべき箇所の 200 はギャップです）。追跡先のないオペレーション（創作されたエンドポイント）、オペレーションがない機能仕様の動作、または誤ったメソッド／ステータスがある場合は、ギャップです。(提示された上流情報に基づいて評価します — 機能仕様が存在しないこと自体は、修正を求める理由にはなりません。)
3. すべてのオペレーションが、リクエストとレスポンスの両方で完全に型付けされていること。 リクエストとレスポンスが完全に型付けされ、各フィールドが制約とともに必須／任意のいずれかとして定義され、すべてのレスポンスがステータスコード（REST）／型付けされたペイロードまたは errors（GraphQL）／型付けされたレスポンスメッセージ（gRPC）に対応付けられていること。型または制約がないフィールド、ステータス／型付けされた本文がないレスポンスは、ギャップです。成功パスだけのオペレーション（2xx のみ）は不合格です。 (シグネチャを成す中核要件の一部であり、簡略化されない基本要件 — 規模を問わず、すべてのオペレーションがリクエストとレスポンスの両方で型付けされていること。)
4. 認証とオペレーションごとの認可。 認証方式と認証情報の配置場所が明記されていること。クライアントの種類ごとに OAuth フローが選択されていること。公開されていないすべてのオペレーションで、必要なスコープ／ロールが示されていること（オペレーション一覧に対応付けられていること）。トークンのライフサイクル、HTTPS、URL に秘密情報を含めないこと。認可の記載がないオペレーション（何も指定せずに公開されている、またはスコープを示さず「ログイン済み」としている）、方式が明記されていない場合、または認証情報を URL に含めている場合は、ギャップです。(簡略化：すべて公開の API ではオペレーションごとのスコープは不要ですが、方式と転送方法は引き続き明記します。)
5. エラーモデルが完全であること。 API 全体で一貫した単一のエラー形式（機械可読なコード、メッセージ、リクエスト／トレース ID）を使用し、さらにオペレーションごとに、該当するすべての名前付き失敗ケース（検証エラー／401／403／404／409／429／5xx）をステータス、コード、再試行可能かどうかとともに列挙していること。2xx のみを示すオペレーション、エンドポイントごとに異なる場当たり的なエラー本文、機械可読なコード／リクエスト ID の欠落、再試行可能かどうかの記載がない場合は、ギャップです。シグネチャを成す条件であり、一般的な design-review との最大の違いです。 (簡略化されない基本要件 — 規模を問わず、エラーモデルが成功パスだけで構成されていないこと。読み取り専用のオペレーションでも 401／404 を明記します。)
6. 共有型を一度だけ定義して参照し、データモデルは再定義しないこと。 再利用可能な DTO を一度だけ定義して参照すること（インラインで型を再定義して差異を生じさせないこと）。ワイヤー DTO はデータモデルを参照し、差分を記すこと。データモデルを再記述したり、矛盾したりしないこと。同じ形状を複数のオペレーションでインラインに再定義している（差異が生じるリスクがある）、または提供されたデータモデルと矛盾する形で DTO を再定義している場合は、ギャップです。(シグネチャを成す中核要件の一部です。グリーンフィールドの場合：データモデルが提供されていないなら、DTO は単独で定義されていてもよく、ギャップではありません。)
7. ページネーション、フィルタリング、ソート、レート制限。 コレクションを扱うオペレーションで、ページネーション（方式、エンベロープ、デフォルト／最大ページサイズ）、フィルタリング／ソート可能なフィールド、安定したタイブレーカー、レート制限、ヘッダー、429 が定義されていること。ページネーションのない／無制限のコレクション、タイブレーカーのないソート付きページネーション、最大ページサイズの欠落は、ギャップです。(簡略化：コレクションではない API、または単一リソースの API ではページネーションは不要です。「ページネーションがない」ことを理由に誤って修正を求めてはいけません。)
8. 例があり、一貫していること。 主要なオペレーションごとに、スキーマと一貫した実例のリクエスト／レスポンスのペアが 1 つ以上あること（フィールド名、型、ステータスコード、エラー形式が同じであること）。スキーマにないフィールド、誤った型、誤ったステータス、または共有形式に従っていないエラー本文を含む例は、ギャップです。(api-spec における、図と表の同期に相当します。簡略化：すべてのオペレーションではなく、主要なオペレーションの例があればよいです。)
9. 命名とバージョニングに一貫性があること。 命名規則とバージョニング方式がすべての API 表面で一様に適用され、逸脱するオペレーションがないこと。命名／大文字小文字の使い方に一貫性がない場合、またはバージョニング方式の適用にむらがある場合は、ギャップです。(対象は API 表面における一様性です。条件 1 のポリシーの存在や条件 2 のオペレーションごとの正確性とは別のため、ここで再審査しないでください。)
10. 根拠があり、誠実で、一貫していること。 オペレーション／形状／制限／コードが機能仕様とデータモデルを反映しており、創作や定型文の流用がないこと。前提が明示されていること（入力が不十分な場合は、形状を創作せず、ブロッカーとすること）。捏造がないこと。api-reference から一方向であること（この契約は公開済み api-reference の真実の情報源であり、api-reference から逆算して作成するものではありません）。データモデルを参照していること（一方向であり、上流に位置すること）。既存の実装済み API がある場合は、それと一貫していること（現行のオペレーション／形状についての主張は file:line で検証し、確認できないものには未検証と明記します）。創作されたフィールド／制限／ステータス／コード、公開済みリファレンスから逆算したオペレーション、またはデプロイ済みの API と矛盾するドキュメント上のオペレーションは、ギャップです。(簡略化されない基本要件 — 捏造をしないことと一方向性は、規模を問わず維持されます。グリーンフィールドの場合： 新規／提案段階／架空の API には実装済みの表面がないため、一貫性の確認は該当なしです。誤って修正を求めてはいけません。)
11. （改訂のみ）差分の範囲が適切で、分類され、波及の確認が済み、バージョン管理されていること。 既存の契約に対する変更をレビューする場合、変更されたオペレーションは、変更箇所について条件 1〜10 を満たすこと。変更が追加的／破壊的に分類されていること。破壊的変更には、新しいバージョン、非推奨化から提供終了までの計画、移行ガイドが含まれること（同じバージョンのまま編集しないこと）。後方／前方互換性を分析していること。前方／下流への波及（下流の api-reference の再同期、実装／テスト計画、稼働中のクライアント）が明示されていること。ドキュメントのバージョンが上がり、変更履歴があること。廃止するオペレーションには非推奨の印を付け、黙って削除しないこと。範囲が定まっていない差分、破壊的変更の誤分類（または同じバージョンのまま編集）、波及の見落とし、黙って削除した箇所は、ギャップです。(簡略化：グリーンフィールドでの初回構築では、この条件は該当しません — 変更のない契約を最初から最後まで再レビューしてはいけません。また、初稿に変更履歴を求めてはいけません。)
12. ケイパビリティの境界（capability_record がない場合は該当なし）： すべての entry_points が API 操作として呼び出し可能であること。publishes／consumes イベントに対応する非同期操作があること。refs フィールドが、ケイパビリティをまたいで読み取り専用としてマークされていること。

比例性。「呼び出し可能＋実装可能」であることの基準は API の規模に応じて変わります。薄い API では、不要なものを正当に省けます。操作が 1 つなら短いリストでよく、コレクションがなければページネーションは不要です。すべて公開されている読み取り API なら、操作ごとのスコープは不要です。新規開発のコントラクトなら、照合対象となるリリース済み API はありません。初版なら変更履歴は不要です。単語数やテンプレートのセクションがそろっているかではなく、コントラクト上の判断が漏れなくなされているかを評価してください。適用可能な条件をすべて満たす、小規模で完全なコントラクトは合格です。簡潔であることを理由に不足を作り出さないでください。

ステップ 3：判定を決める

• approve — 適用可能な条件をすべて満たしています。クライアントはすべての操作を呼び出すことができ、サーバーは形状、エラー、認証に曖昧さのないコントラクトだけをもとに実装できます。文体を改善できると思っても承認してください。基準は完璧さではなく、呼び出し可能性＋実装可能性です。
• revise — 呼び出しまたは実装を妨げる、実際に特定可能な不足が 1 つ以上あります（正常系しか記載されていない操作、型が指定されていないフィールド、不整合または欠落のあるエラーカタログ、スキーマと矛盾する例、データモデルと矛盾する DTO、認可のない操作、破壊的変更の上書き編集、スコープのない修正など）。

努力を促したり、あるとよいだけの要望を伝えたりするために revise と判定しないでください。条件は満たしているか、満たしていないかのどちらかです。

ステップ 4：判定と、実行可能な指摘を出力する

判定は 1 行だけで出力します。VERDICT: approve または VERDICT: revise という文字列を、その行だけに記載してください。前後にコードフェンス、引用符、余分な語句を付けないでください（以下のフェンスは説明用です）。

VERDICT: approve

続く行に指摘を列挙します。revise の場合、すべての指摘は実行可能でなければなりません。すなわち、不合格となった条件、正確な箇所、修正方法を示し、作者が一度の対応で解決できるようにしてください。approve の場合、指摘は任意であり、阻害要因とならない注記を記載できます。

適切な指摘では、不足と修正方法を明示します。

revise — エラーモデルの網羅性（条件 5）、§3 GET /invoices：この操作には 200 レスポンスしか記載されておらず、エラーケースがありません。修正方法：失敗ケース（スコープがある場合は 401 unauthorized、403 forbidden、404 not_found）を、ステータス、機械判読可能なコード、再試行可能性を含む共通の Problem-Details 形式で列挙し、クライアントがすべての結果に対応できるようにしてください。

不適切な指摘は曖昧で、対応方法がわかりません。

エラー処理をもっと充実させられます。（どの操作ですか？ どのエラーですか？ どのような形式ですか？）

ルール

厳守事項（絶対に違反しないこと）：

• 判定行は VERDICT: approve または VERDICT: revise のいずれかをちょうど1行だけ出力してください — その文字列を単独の行に記載し、それ以外は同じ行に何も書かないでください。後続のツールが解析します。
• 判断に徹し、作成しないでください。 指摘事項を返し、契約を書き換えたり、修正したり、補完したりしないでください。修正するのは作成者です。
• 単一の基準に従ってください。 Step 2 の12項目に照らして判断してください。これは作成者（authoring-api-spec の Step-7 セルフチェック）が用いる基準と同じです。独自の条件を追加したり、個人的な基準をより厳しく適用したりしないでください。
• 手法ではなく結果を評価してください。 スタイル表記（OpenAPI／SDL／proto）、名前が挙げられた RFC（9457／8594／9745／AIP）、JSON-Schema の知識は、作成者の手法です。操作が型付けされているか、エラーカタログが完全か、例が一致しているかを評価してください。「OpenAPI／RFC 9457／$ref を使っていない」と指摘してはいけません。（エラーモデル／両側の型付け／操作ごとの認可という結果は cond-3／4／5 の実際の条件ですが、手法はあくまで補助です。）
• スタイルに左右されないでください — OpenAPI を前提に考えないこと。 GraphQL／gRPC 契約に HTTP ステータスコード／OpenAPI／REST リソースがないことを理由に修正を求めてはいけません。代わりに、GraphQL では errors 配列と null 許容性、gRPC では google.rpc.Status と proto を評価してください。このゲートが防ぐべき最大の逸脱です。
• 誤って revise と判定しないでください。 適用されるすべての条件を満たす契約は、たとえ小規模な API の簡潔な契約であっても approve と判定してください。実際に名前の付いた不足がある場合に限り revise としてください。小規模な API では、ページネーション、操作ごとのスコープ、変更履歴を省略しても問題ありません。
• 誤って approve と判定しないでください。 同意を示すために、実際の不足を見逃して approve としてはいけません。成功時の経路しか示されていない操作、型付けされていないフィールド、または矛盾する例がある場合は revise です。
• エラーモデルは成功時の経路ではありません（cond. 5）。 2xx のみを示す操作には実際の不足があります（クライアントが失敗を処理できません）。これはスタイル上の細かな指摘ではありません。api-spec で最も見落とされがちな項目です。
• 提示された上流ドキュメントに照らして判断してください。 depends_on の一覧と、参照先のドキュメントに基づいて契約を評価してください。作成されていない／提出されていない上流ドキュメント（たとえば、存在しない feature-spec や data-model）は、決して revise の理由になりません。トレースすべき作成済みの上流ドキュメントを契約が無視している場合は、正当な指摘事項です。
• Amend は差分の範囲に限定してください。 既存の契約に対する変更を提示された場合は、差分、その分類、非推奨化、波及範囲（cond-11）をレビューしてください。変更されていない契約全体を再レビューしてはいけません。また、グリーンフィールドの初稿に変更履歴を求めてはいけません。
• グリーンフィールドの整合性確認は対象外であり、不足ではありません。 照合対象となるリリース済み API が存在しない場合、cond-10 の整合性確認は N/A としてください。照合可能なデプロイ済みインターフェースがないこと自体は、決してブロッカーにはなりません。
• revise の指摘はすべて実行可能な内容にしてください — 違反した条件、該当箇所、具体的な修正内容を示してください。

優先事項（状況に応じて変更可）：

• 指摘事項は深刻度順に並べてください。まずブロッカーとなる不足を示し、その後に軽微な不足を示してください。
• 各指摘に条件番号／名称を記載し、作成者が基準に対応付けられるようにしてください。
• approve 時の注記は少数にとどめ、ブロッカーではないことを明確にしてください。

注意点

• 呼び出し可能性ではなく、網羅性を基準に承認してしまう。 すべてのセクションがそろっていても、API が呼び出せるとは限りません（正常系しかない操作、型指定のないフィールド、スキーマと矛盾する例など）。テンプレートが埋まっているかではなく、API を呼び出して実装できるかを判断してください。
• OpenAPI の固定観念。 GraphQL API に HTTP ステータスコードを、gRPC API に OpenAPI を要求することは、最もよくある逸脱です。GraphQL の契約は errors 配列と null 許容性で、gRPC の契約は google.rpc.Status と proto で正しく表現できます。それぞれのスタイルに固有の慣例に従って判断してください。
• 正常系しかない操作を見過ごす。 200／201 を列挙しただけの操作は完成しているように見えます。しかし、エラーケースがなければクライアントは catch 分岐を実装できません（条件 5）。すべての失敗ケースを列挙してください。列挙がなければ不備です。
• DTO の逆転／リバースエンジニアリングされた契約。 上流のデータモデルと形状が矛盾する契約や、公開されている api-reference からリバースエンジニアリングされた操作は、依存関係を逆転させています（条件 6／条件 10）。データモデルが上流で、api-reference は下流です。
• スキーマから逸脱した例。 スキーマで宣言されていないフィールドを含む例や、型／ステータスが誤った例は、それをコピーする人の契約を気づかれないまま壊します（条件 8）。
• 条件を勝手に追加する（基準からの逸脱）。 基準にない独自の要件（「RFC 9457／OpenAPI／$ref を使わなければならない」など）を追加すると、レビュー基準が成果物の基準から逸脱します。技法は結果のみで評価してください。
• 体系的な過剰指摘（誤った修正要求）。 問題を探すよう求められたレビュアーは、過剰に修正しがちです。条件に該当するのは、明示された実際の不備がある場合だけであり、自分なら別の判断をしたというだけでは不備になりません。
• これを api-reference や設計レビューと混同する。 api-spec は、契約を呼び出して実装できるかで評価します。これは、公開される利用者向けドキュメントである api-reference（下流の利用者）とも、汎用的な設計ドキュメント／RFC／ADR／計画を審査する design-review とも異なります。このゲートは、doc-library の api-spec 成果物に特化したレビュアーです。
• 判定トークンの逸脱。 「Approved」、「LGTM」、「needs work」、または段落の途中に埋め込まれた判定では解析できません。VERDICT: approve|revise という文字列を、単独の行に出力してください。

アンチパターン

• 形式的な承認。 修正ループを避けるために流し読みして承認すると、正常系しかない操作やデータモデルと矛盾する DTO が見過ごされ、処理不能な失敗やワイヤー形式とストレージの不一致につながります。
• 些細な指摘による修正要求。 命名、表記法、あると望ましい程度の要素を不備として持ち出し、ブロックすること。修正を求めるのは、呼び出し可能性／実装可能性を実際に妨げる場合だけです。
• OpenAPI の固定観念による修正要求。 HTTP ステータスコード／OpenAPI を使っていないという理由で GraphQL／gRPC の契約に修正を求めること。これは api-spec 特有の最もよくある逸脱です。
• 黙って書き換える。 「契約を直したほうが簡単だった」——レビュー中に成果物を編集すると、作成と評価の分離が崩れます。
• 条件を勝手に追加する。 基準にない要件（特定の表記法／RFC など）を追加すること。評価するのは結果のみです。
• 修正分の全体を再レビューする。 小さな変更だけなのに、変更されていない契約全体を再評価すること。変更分、その分類、非推奨化、波及影響（条件 11）を、変更の規模に応じてレビューしてください。
• 曖昧な判定。 「ほぼ承認だが……」や、判定を二つ記載すること。判定は一つ、トークンは一つだけにしてください。

出力

1 つの api-spec ドキュメントに対する単一のレビュー結果：

• 判定行を 1 行 — VERDICT: approve または VERDICT: revise をそのまま、単独の行に記載します。
• 指摘事項 — revise の場合は、阻害要因となる不足 1 件につき、実行可能な指摘を 1 件（満たしていない条件＋場所＋具体的な修正方法）記載します。approve の場合は、任意で阻害要因とならない注記を記載できます。

抽象的な利用者とは、作成→レビューのループを統括するものです。approve は統合／実装に向けて契約を受け入れ、revise は範囲を限定した修正パスのために指摘事項を作成者へ返します。対象： 現時点で評価対象となる成果物はテキスト形式の Markdown api-spec（操作テーブル＋フェンス付きスキーマブロック＋例のペア）ですが、基準は媒体に依存しません。

関連項目

• authoring-api-spec — ペアの作成側です。このスキルが評価する 11 条件の基準（Step-7 のセルフチェック）に沿って契約を作成します。ペアにすることで基準を一元化し、作成とレビューの間にずれが生じないようにします。
• data-model（存在する場合）— 上流に位置します。ワイヤー DTO はそのエンティティを参照します（一方向）。cond-6／cond-10 では、契約がそれを参照していることを確認し、再定義や矛盾がないことを評価します。
• 上流の feature-spec — 契約が公開する動作を定義します。cond-2／cond-10 では、提示されている場合に限り、それらとの対応を確認します。
• reviewing-api-reference — 下流の公開 api-reference（この契約から生成されることがよくあります）を審査するゲートです。この契約はそのリファレンスの信頼できる唯一の情報源です（cond-10 の一方向ルール）。リファレンスから逆算して作成してはなりません。
• design-review スキル — 一般的なエンジニアリング設計ドキュメント、RFC、ADR、仕様書、計画書を審査するゲートです（コードベースに照らして記述内容を検証します）。このスキルは、ドキュメントライブラリの api-spec 成果物専用のレビュアーです。design-review はこの成果物を対象外とします。
• api-spec テンプレート／content-template ツール — セクションの構成を管理します。このスキルが評価するのは基準に対する品質であり、構造への準拠ではありません。

段階的な情報開示

• references/api-spec-quality-bar.md — 12 のチェック条件を、条件ごとの合格／不足の判定基準と、実例に基づく指摘例とともに詳しく説明します（両側の型チェック、完全なエラーモデルのチェック、共有型／データモデル参照のチェック、操作ごとの認可チェック、ページネーション／タイブレーカーのチェック、例とスキーマの一致チェック、リリース済み API との一方向性／一貫性チェック、スタイルに依存しないガード、差分範囲に限定した修正の判定基準）。境界的な条件について、より明確に合否を判断する必要がある場合に読み込みます。
• references/sources.md — レビューメソッドの調査根拠（OpenAPI／JSON-Schema、GraphQL SDL、gRPC／proto、RFC 9110／9457、RFC 8594／9745、AIP-180／185、ページネーション＋レート制限の慣例）。

本文の予算

• description は 1,024 文字以下（agentskills.io の上限）。一覧では description と when_to_use の合計が 1,536 文字で切り捨てられます。
• 本文は約 500 行／5,000 トークン（目安。品質を優先し、700 行／7,000 トークンを継続的に超える場合は指摘します）。毎ターン、コンテキストに保持されます。
• 参照ファイルごとに 10,000 トークン超は警告、25,000 トークン超はエラー。参照ファイルの合計は 25,000 トークン超で警告、50,000 トークン超でエラー。

変更履歴

• 1.0.0 (2026-06-15) — 初回リリース。標準的な兄弟スキル reviewing-data-model を応用して、新規のレビュアーを作成。11 条件の契約完全性基準は authoring-api-spec の Step-7 セルフチェックと 1 対 1 で一元化。スタイルに依存しない（OpenAPI を前提としない）。VERDICT: approve|revise の契約、提示された上流仕様に照らして評価する方針、リリース済み API との一貫性をコードに照らして検証する規律＋グリーンフィールド条項、そして比例性／誤った revise 判定の回避／条件の捏造というアンチパターンを継承しています。