Claude CodeでAPI設計レビューをするためのチェックリスト

API設計は、一度公開すると後から変えにくい「一方通行のドア」になりやすい領域です。本記事は、Claude CodeにAPI設計をレビューさせるためのチェックリストと依頼文テンプレートを整理し、AIレビューと人間レビューの分担までを扱います。

結論：契約を先に固め、観点を指定してレビューさせる

APIのレビューを「このAPIを見て」と丸投げすると、Claude Codeは表面的な指摘しか返しません。API設計のレビューは、観点を明示し、契約（スキーマ）を起点に進めるのが基本です。

要点は3つです。

1. 契約ファースト：実装でなく、OpenAPIなどのスキーマをレビュー対象にする
2. 観点を指定する：エラー・認証・ページング・互換性などを依頼文で列挙する
3. AIは一次フィルタ：最終判断、特に互換性とセキュリティは人間が確定する

API設計は設計判断の一種なので、案出しの段階は「Claude Codeで大規模開発の設計相談をするときの進め方」、レビュー全般の進め方は「Claude Codeをコードレビューに使う方法と人間が見るべきポイント」が土台になります。本記事はAPI設計に特化したチェック観点を扱います。

契約ファーストでレビューする

APIのレビューは、実装コードではなくスキーマ定義（OpenAPIなど）を対象にします。スキーマは「クライアントと交わす契約」であり、ここがぶれると実装をいくら直しても利用者が混乱します。

レビュー依頼の基本形は次のとおりです。

目的: API設計のレビュー（契約ファースト）

対象: @openapi.yaml

依頼:
以下の観点ごとに、問題を Critical / Should / Nit でラベル付けして指摘する
- エラー設計（後述の観点表に沿う）
- 認証・認可
- ページング
- 命名とバージョニング
- ドキュメントの十分さ

各指摘には「該当箇所」「なぜ問題か」「修正案」を書く

禁止事項:
- スキーマやコードを実際に変更すること
- 観点表にない一般論で埋めること

実装を変更させず、指摘だけ出させるのがポイントです。修正は指摘を人間が取捨選択してから別途依頼します。

エラー設計のチェック観点

APIのエラー設計は、利用者が最も困りやすく、後から変えにくい部分です。Claude Codeには次の観点で点検させます。

特に「エラー本文の構造が統一されているか」は見落とされやすい観点です。エンドポイントごとにエラー形式が違うと、クライアント側の実装が複雑になります。

認証・認可とページングの観点

認証・認可は、設計の誤りがそのままセキュリティ事故につながります。レビューでは次を確認させます。

• 認証が必要なエンドポイントに、漏れなく認証がかかっているか
• 認可（権限チェック）が、リソースの所有者単位で正しく効くか
• 他人のIDを指定すると他人のデータが取れてしまわないか（オブジェクトレベルの認可）

セキュリティ観点の横断的な確認は「Claude Codeを使うときのセキュリティチェックリスト」も合わせて使います。

ページングは、データ量が増えてから問題が表面化します。オフセット方式かカーソル方式か、1ページの上限、合計件数を返すかどうかを設計段階で確認します。一覧APIに上限のないページングを許すと、後から性能問題になります。

命名・バージョニング・互換性

APIの命名とバージョニングは、一度公開すると修正コストが跳ね上がります。次を点検させます。

• リソース名・フィールド名が、エンドポイント間で一貫しているか
• バージョニングの方針（URLパス・ヘッダーなど）が決まっているか
• 後方互換を壊す変更（フィールド削除・型変更・必須化）が混ざっていないか

特に「破壊的変更」の検出は重要です。既存のAPIを変更する場合、変更が後方互換かどうかをAIに判定させます。

依頼:
このAPI変更（@openapi.yaml の diff）について、
後方互換を壊す変更がないか判定する
- フィールドの削除・リネーム・型変更
- 必須項目の追加
- エラーコードや列挙値の変更
破壊的変更があれば、該当箇所と影響、回避案を挙げる

完了条件や禁止事項の書き分けは「Claude Codeの成功率を上げる制約条件と受け入れ条件の作り方」の考え方が使えます。

ドキュメントの十分さ

スキーマが整っていても、各フィールドや挙動の説明が足りないと、利用者は実装を推測することになります。レビューでは、各エンドポイント・各フィールドに説明があるか、例（サンプルリクエスト・レスポンス）があるか、エラーケースが文書化されているかを確認させます。

ただし、ドキュメントは増やしすぎても保守できなくなります。「契約として必要な説明」と「過剰なドキュメント」の線引きは「Claude Codeでドキュメントを増やしすぎないための書き方」を参照してください。

AIレビューと人間レビューの分担

Claude CodeによるAPI設計レビューは、あくまで一次フィルタです。次のように分担します。

AIは「統一されていない」「観点が抜けている」は得意ですが、「この破壊的変更を、利用者に告知したうえで実施してよいか」のような判断はできません。互換性とセキュリティの最終確定は必ず人間が行います。

API設計レビューのチェックリスト

• 実装でなくスキーマ（契約）をレビュー対象にした
• エラー設計（コード・本文構造・機械可読性・情報漏えい）を点検した
• 認証・認可、特にオブジェクトレベルの認可を確認した
• ページング方式と一覧APIの上限を確認した
• 命名の一貫性とバージョニング方針を確認した
• 破壊的変更が混ざっていないか判定させた
• ドキュメントの十分さを、過剰にならない範囲で確認した
• 互換性とセキュリティの最終判断は人間が行った

次に読むおすすめ記事：

• 「Claude Codeをコードレビューに使う方法と人間が見るべきポイント」：レビュー全般のAIと人間の分担
• 「Claude Codeで大規模開発の設計相談をするときの進め方」：API設計を決める前の案出しフェーズ
• 「Claude Codeを使うときのセキュリティチェックリスト」：認証・認可を含む横断的なセキュリティ確認