結論：Claude CodeでSDK・APIクライアントを自動生成するなら、OpenAPIやGraphQL schemaを直接「それっぽく実装させる」のではなく、仕様差分の確認、既存ジェネレータの実行、型・テスト・ドキュメントの追従までを1つの開発ワークフローとして任せるのが実務的です。
- 要点1：Claude Codeは公式ドキュメント上、コードベースを読み、ファイルを編集し、コマンドを実行し、開発ツールと連携できるエージェント型コーディングツールです。SDK生成では「仕様を読む」「生成コマンドを走らせる」「差分をレビューする」という流れに向いています。
- 要点2：Agent SDKはPythonとTypeScriptからClaude Codeのエージェントループを扱えます。CI、社内ポータル、開発者向けCLIにSDK生成フローを組み込む場合は、対話型CLIだけでなくAgent SDKや
claude -pの非対話実行も選択肢になります。 - 要点3：事故を防ぐ鍵は、
settings.json、権限ルール、Hooks、CLAUDE.md、MCPを使って「どの仕様を正とするか」「どのコマンドだけ許可するか」「生成後に何を必ず検証するか」を固定することです。
対象読者：OpenAPI、GraphQL、REST API、社内APIからTypeScript/Python/Java/Kotlinなどのクライアントを作っている開発者、テックリード、PM。
今日やること：まずは自分のリポジトリにapi-spec/、generated/、tests/contract/の責務を書いたCLAUDE.mdを置き、この記事の「仕様監査プロンプト」だけを1回実行してください。
本記事は事例区分：実装パターン解説です。特定企業の実測成果ではなく、Claude Code公式ドキュメントで確認できる機能を前提に、APIクライアントとSDK生成を現場で安全に回すための設計・手順・プロンプトをまとめています。
APIクライアント生成で一番こわいのは、コードが出ることではありません。むしろ、コードは出ます。こわいのは「出たコードが、どの仕様に対して正しいのか誰も説明できない」状態です。
私がClaude Codeの生成物をレビューするとき、最初に見るのは実装の美しさではなく、入力仕様、生成コマンド、差分、テストのつながりです。ここがつながっていれば、多少コードが荒くても直せます。逆に、仕様ファイルの出どころが曖昧なままSDKだけ増えているリポジトリは、後からほぼ必ず苦しくなります。
この記事では、Claude Codeを「APIクライアントを一発で書く魔法」として扱いません。OpenAPIやGraphQL schemaを起点に、生成、型補完、認証、エラー型、テスト、CI、ドキュメント更新までをClaude Codeに伴走させる方法として整理します。
Claude Codeに任せる範囲を最初に分ける
SDK・APIクライアント生成には、少なくとも3つの作業が混ざっています。
- 仕様の読解：OpenAPI、GraphQL schema、Protocol Buffers、既存README、サンプルcurl、認証方式を読む。
- 生成の実行：既存ジェネレータ、社内スクリプト、パッケージマネージャ、フォーマッタ、型チェックを実行する。
- 統合の判断：既存アプリのHTTP層、エラー処理、リトライ、ログ、テスト、リリース手順に合わせる。
Claude Codeに向いているのは、この3つを横断して「リポジトリの文脈込みで作業する」部分です。公式ドキュメントでも、Claude Codeはコードベースを読み、ファイルを編集し、コマンドを実行し、開発ツールと連携するツールとして説明されています。単体のコード生成モデルではなく、ターミナルやIDEに近い開発作業の文脈で使うのが自然なんです。
一方で、Claude Codeに任せないほうがよい領域もあります。公開APIの互換性判断、法務的な利用規約判断、外部顧客に約束するSLA、セキュリティ審査の最終承認は、人間と組織の責任範囲です。AIは補助ツールであり、最終判断者ではありません。
API-first設計から入りたい場合は、関連する実装観点をClaude CodeでOpenAPI仕様駆動のAPI-first開発を進めるガイドでも整理しています。この記事では、その後段にある「クライアント生成とSDK運用」に寄せて解説します。
生成前に固定する5つの入力
Claude Codeを開く前に、最低限この5つを決めておくと失敗がかなり減ります。
| 入力 | 確認すること | Claude Codeに渡す形 |
|---|---|---|
| API仕様 | OpenAPI YAML/JSON、GraphQL schema、protoなどの正本 | api-spec/openapi.yamlのように固定パスへ配置 |
| 生成対象言語 | TypeScript、Python、Java、Kotlin、Goなど | CLAUDE.mdに優先順位を書く |
| HTTP基盤 | fetch、axios、httpx、requests、社内ラッパーなど | 既存コードの参照先を明示 |
| 認証方式 | Bearer token、OAuth、API key、署名付きリクエストなど | 秘密情報は渡さず、環境変数名だけ渡す |
| 検証方法 | 型チェック、単体テスト、契約テスト、サンプル呼び出し | 実行してよいコマンドを限定する |
ここで大事なのは、Claude Codeに「SDKを作って」と頼む前に「正しいSDKの条件」を渡すことです。正しい条件がないまま出てきたコードは、動いたとしても将来の変更に弱くなります。
私が最初に置くなら、CLAUDE.mdにはこの程度を書きます。長すぎるルールより、毎回効いてほしいルールだけを短く置くほうが扱いやすいです。Claude Codeの公式ドキュメントでも、CLAUDE.mdはセッション開始時に読み込まれる永続的なプロジェクト指示として説明されています。
# API client generation rules
- Source of truth: api-spec/openapi.yaml
- Generated TypeScript client: packages/api-client/src/generated/
- Generated Python client: python/acme_client/generated/
- Do not edit generated files by hand unless explicitly requested.
- Prefer existing generator scripts in package.json or pyproject.toml.
- Before editing, inspect current scripts and tests.
- After generation, run typecheck and the smallest relevant test suite.
- Never print secrets. Use environment variable names only.
- If required information is missing, ask first before making assumptions.
- If you make an assumption, label it as an assumption in the final summary.最小ワークフロー：まず仕様監査だけをやらせる
最初から生成まで頼むより、1ターン目は仕様監査だけにします。これだけで、仕様ファイルの古さ、既存スクリプトの有無、生成物の置き場所、認証の扱いが見えてきます。
あなたはAPIクライアント生成のレビュー担当です。
このリポジトリを読み、SDK・APIクライアント生成に必要な情報だけを調査してください。
確認してほしいこと:
1. API仕様ファイルの場所と形式
2. 既存の生成スクリプト、package.json、Makefile、pyproject.toml、CI設定
3. 既存HTTPクライアント層、認証処理、エラー処理の実装
4. 生成物を置くべきディレクトリ
5. 生成後に実行すべき最小テスト
まだファイルは編集しないでください。
不足している情報があれば、最初に質問してから作業を開始してください。
仮定した点は必ず「仮定」と明記してください。このプロンプトの狙いは、Claude Codeを「作業者」ではなく「調査者」として走らせることです。Claude Codeはコードベースを横断して読めるので、既存の生成方針がある場合はそれを見つけてくれます。逆に、既存方針がない場合も、どこが未決定かを明確にできます。
ここで得られる出力は、SDK生成の設計メモとしてそのままPull Requestの説明にも使えます。正直、この調査を飛ばして生成に入ると、後で「なんでこのHTTPライブラリを選んだんだっけ？」という会話になりがちです。
TypeScriptクライアントを生成する手順
TypeScriptでは、型、ランタイムHTTP呼び出し、React QueryやSWR向けの薄いラッパー、モック生成など、プロジェクトによって期待値が違います。Claude Codeには「このプロジェクトの既存流儀に合わせる」ことを最優先で指示します。
1. 既存の生成コマンドを探す
まずはClaude Codeに、package.json、pnpm-workspace.yaml、turbo.json、Makefile、CI設定を読ませます。生成ツール名をこちらが決め打ちする前に、リポジトリの現実を見てもらうわけです。
TypeScript APIクライアントの生成方法を調べてください。
制約:
- まず既存のpackage.json、Makefile、CI設定を読んでください。
- 既存の生成ツールがある場合は、それを優先してください。
- 新しい依存を追加する前に、理由と代替案を提示してください。
- 生成物を手で編集しない方針にしてください。
- 実行してよいコマンドは、調査後に提案してからにしてください。
出力:
- 現在の生成フロー
- 不足している設定
- 推奨する最小変更
- 実行予定コマンド
数字と固有名詞は、根拠（ファイルパス/行/公式URL）を添えてください。2. 生成スクリプトを固定する
既存スクリプトがない場合でも、Claude Codeにいきなり複雑なCLIを発明させないほうがいいです。まずはnpm run generate:apiのような単一入口を作り、CIでもローカルでも同じコマンドを使える形にします。
{
"scripts": {
"generate:api": "node scripts/generate-api-client.mjs",
"check:api-client": "npm run generate:api && npm run typecheck && npm test -- api-client"
}
}この例では、実際のジェネレータ名を記事内で固定していません。理由は単純で、現場では既存の制約が強いからです。すでに社内標準があるなら、それを使うべきです。Claude Codeに頼むべきなのは「ジェネレータ選定の勝手な発明」ではなく、「既存標準に合わせた配線」です。
3. 型境界を薄く保つ
生成SDKでやりがちな失敗は、生成物の中に認証、リトライ、ログ、UI向け整形まで入れてしまうことです。生成物はAPI仕様に近い低レイヤーに寄せ、アプリ固有の処理は薄いラッパーに逃がすほうが保守しやすいです。
TypeScript APIクライアントを生成し、既存アプリに組み込んでください。
方針:
- api-spec/openapi.yamlを正本にしてください。
- generated/以下は生成物として扱い、手編集を避けてください。
- 認証ヘッダー付与、リトライ、ログ、UI向け整形はgenerated外の薄いラッパーに置いてください。
- 既存のHTTPクライアント層があれば必ずそれに合わせてください。
- 破壊的変更がある場合は、変更点を一覧化してから実装してください。
完了条件:
- 生成コマンドが1つにまとまっている
- TypeScriptの型チェックが通る
- 代表的なGET/POSTの単体テストが追加されている
- READMEに再生成手順がある
不足している情報があれば、最初に質問してから作業を開始してください。Python SDKを生成する手順
Python SDKでは、同期/非同期、型ヒント、例外設計、パッケージング、認証トークンの注入方法が論点になります。TypeScriptよりも「利用者がどうimportするか」を明示しておくと、生成後のAPIが安定します。
たとえば、社内向けPython SDKなら、以下のような利用イメージを先に置きます。
from acme_client import AcmeClient
client = AcmeClient.from_env()
customer = client.customers.get_customer("cus_123")
print(customer.email)この利用イメージを先に渡すと、Claude Codeは「生成したクライアントをそのまま公開APIにする」のではなく、使いやすい表層APIを設計しやすくなります。
Python向けAPIクライアントSDKを作成してください。
前提:
- 仕様ファイルはapi-spec/openapi.yamlです。
- generated/以下は仕様からの生成物として扱います。
- 公開APIはacme_client/配下の薄いラッパーに置きます。
- 利用者は `from acme_client import AcmeClient` で使える形にしてください。
- 秘密情報は環境変数名のみを扱い、値は出力しないでください。
確認してほしいこと:
1. pyproject.tomlの既存設定
2. ruff、mypy、pytestなど既存の検証コマンド
3. 同期/非同期の既存方針
4. 例外クラスとエラー型の置き場所
完了条件:
- 生成スクリプトが再実行可能
- 型ヒントが付く
- 代表的な正常系とエラー系のテストがある
- READMEにインストール例と最小サンプルがある
仮定した点は必ず「仮定」と明記してください。私なら、ここで「使いやすいSDK名」「例外名」「環境変数名」を人間が先に決めます。Claude Codeに名前を任せると、リポジトリ内の既存命名と微妙にずれることがあります。ここは小さいようで、利用者体験に効くんです。
生成コードを既存アプリに組み込む
SDK生成の本番は、生成そのものではなく統合です。生成された関数が100個あっても、アプリ側が安全に呼べなければ意味がありません。
統合時は、生成物とアプリ固有の責務を分けます。
| 層 | 置くもの | 避けるもの |
|---|---|---|
| generated | 仕様由来の型、低レベルAPI呼び出し | 手書きのビジネスロジック |
| client wrapper | 認証、base URL、共通ヘッダー、例外変換 | UI表示文言 |
| service layer | ユースケース別の組み合わせ、リトライ方針 | 仕様ファイルと重複する型定義 |
| tests | 契約テスト、スナップショット、エラー系 | 外部本番APIへの無制限アクセス |
Claude Codeには、この境界を守らせるプロンプトを渡します。
生成済みAPIクライアントを既存アプリへ統合してください。
守る境界:
- generated/以下は生成物として扱い、直接ビジネスロジックを書かない
- 認証、base URL、リトライ、ログ、例外変換はclient wrapper層に置く
- UI向け整形はservice layerまたはUI層に置く
- 既存の命名規則とディレクトリ構造を優先する
作業手順:
1. 既存のAPI呼び出し箇所をGrepで洗い出す
2. 1つの代表ユースケースだけを移行する
3. テストを追加する
4. 型チェックと最小テストを実行する
5. 残りの移行候補をリスト化する
一度に全面移行しないでください。
不足している情報があれば、最初に質問してから作業を開始してください。「一度に全面移行しない」と明記するのがポイントです。SDK生成は差分が大きくなりやすいので、代表ユースケース1つから入ったほうがレビューできます。Claude Codeは複数ファイルをまたいで作業できますが、人間のレビュー限界を超える差分を作らせない設計が必要です。
Headless実行とAgent SDKで自動化する
Claude Codeは対話型だけでなく、CLIの-pまたは--printで非対話実行できます。公式ドキュメントでは、claude -pに--allowedToolsや--output-formatなどのCLIオプションを組み合わせられること、出力形式としてtext、json、stream-jsonを選べることが説明されています。
SDK生成をCIの前段や社内CLIに組み込みたい場合は、この非対話実行が便利です。
claude -p "api-spec/openapi.yamlの差分を読み、SDK再生成が必要か判定してください。ファイルは編集しないでください。" \
--allowedTools "Read,Grep,Glob" \
--output-format jsonさらに、Claude Agent SDKを使うと、PythonまたはTypeScriptからClaude Codeのエージェントループを扱えます。公式ドキュメントでは、Agent SDKはClaude Codeをライブラリとして使い、ファイル読取、コマンド実行、コード編集などの組み込みツールを持つエージェントを構築できると説明されています。
たとえば、社内の「API仕様更新ボタン」からSDK生成を起動したい場合は、TypeScript側でこういう形にできます。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: [
"api-spec/openapi.yamlを正本としてSDK生成の影響を調査してください。",
"既存の生成スクリプトを優先し、必要な変更だけ提案してください。",
"編集前に実行予定コマンドを説明してください。"
].join("\n"),
options: {
allowedTools: ["Read", "Grep", "Glob"],
maxTurns: 3
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}Pythonならclaude-agent-sdkを使います。公式リファレンスではpip install claude-agent-sdkで導入し、query()またはClaudeSDKClientを使う構成が示されています。単発の生成・レビューならquery()、会話を継続してユーザー承認を挟むUIならClaudeSDKClientが合います。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob"],
cwd="/repo",
)
async for message in query(
prompt="SDK生成前にOpenAPI差分と既存生成スクリプトを調査してください。編集はしないでください。",
options=options,
):
print(message)
asyncio.run(main())既存のヘッドレス活用は、Claude CodeのHeadless自動化とSDK活用ガイドにも関連します。この記事のSDK生成フローは、その中でも「仕様ファイルを入力にした生成・検証タスク」に特化した使い方です。
構造化出力で「生成してよいか」を判定する
実務では、Claude Codeにいきなり編集させるより、「再生成が必要か」「破壊的変更があるか」「人間承認が必要か」をJSONで返してもらうほうが扱いやすいです。
Claude Codeの非対話CLIでは--output-format jsonや--json-schemaを使えます。またAgent SDKには、JSON Schemaで欲しい出力形を定義し、結果をstructured_outputとして受け取るStructured Outputsがあります。公式ドキュメントでは、型安全にするためにTypeScriptではZod、PythonではPydanticも使えると説明されています。
claude -p "OpenAPI差分を調べ、SDK再生成の要否を判定してください。" \
--allowedTools "Read,Grep,Glob" \
--output-format json \
--json-schema '{
"type": "object",
"properties": {
"needs_regeneration": {"type": "boolean"},
"breaking_changes": {"type": "array", "items": {"type": "string"}},
"safe_commands": {"type": "array", "items": {"type": "string"}},
"requires_human_approval": {"type": "boolean"}
},
"required": ["needs_regeneration", "breaking_changes", "safe_commands", "requires_human_approval"]
}'この判定をCIに入れると、「仕様ファイルだけ変わったのにSDKが未更新」「SDKだけ変わって仕様が変わっていない」「破壊的変更なのにREADMEが更新されていない」といったレビュー漏れを見つけやすくなります。
私のおすすめは、まず判定だけを自動化し、編集は人間が確認してからです。生成系の自動化は気持ちよく動きますが、API互換性の判断まで自動承認すると危ない場面があります。
Hooks・権限・settingsで事故を防ぐ
SDK生成で起きる事故は、たいてい「想定外のコマンド実行」「生成物の過剰な差分」「秘密情報の混入」「本番APIへの誤アクセス」です。Claude Codeには、設定ファイル、権限、Hooksを使って挙動を制御する仕組みがあります。
公式ドキュメントでは、settings.jsonが階層的な設定機構として説明されています。ユーザー設定は~/.claude/settings.json、プロジェクト共有設定は.claude/settings.json、個人ローカル設定は.claude/settings.local.jsonに置けます。チームでSDK生成を回すなら、プロジェクト共有設定とローカル設定の分離が重要です。
また、HooksはClaude Codeのライフサイクル上の特定タイミングで動くシェルコマンド、HTTP endpoint、LLMプロンプトとして説明されています。たとえばPreToolUseで危険なBashを止めたり、PostToolUseで生成後のフォーマットを促したりできます。
{
"permissions": {
"allow": [
"Read",
"Grep",
"Glob",
"Bash(npm run generate:api)",
"Bash(npm run typecheck)",
"Bash(npm test -- api-client)"
],
"deny": [
"Bash(curl *api.prod*)",
"Bash(rm -rf *)",
"Bash(printenv*)"
]
}
}この例は考え方を示すものです。実際の設定は、公式ドキュメントと自社のセキュリティルールを確認して調整してください。特にAPIトークン、顧客データ、本番エンドポイントを扱う場合は、所属組織の規程・コンプライアンスに従ってください。
権限設計の詳細はClaude Codeの権限設計をチームで運用するガイド、設定ファイルの全体像はClaude Code settings.json設定ガイドも参考になります。
MCP・CLAUDE.md・Skillsでチーム運用にする
SDK生成は、1人が手元で便利に使うだけなら簡単です。難しいのは、チーム全員が同じ生成ルールで回せるようにすることです。
Claude Code公式ドキュメントでは、MCPを使うとClaude Codeが組み込み以外のツールやデータソース、たとえばIssue tracker、データベース、ブラウザ制御などを使えると説明されています。Agent SDK側でも、MCPサーバーをコードや.mcp.jsonから構成し、外部APIや社内ツールに接続できます。
SDK生成でMCPを使うなら、次のような用途が現実的です。
- API仕様の正本が置かれた社内ドキュメントを検索する
- Issue trackerから「このAPI変更に紐づくチケット」を読む
- リリースノート生成に必要な変更履歴を取得する
- 社内の互換性チェックツールを呼び出す
ただし、MCPは便利なぶん、接続先の権限設計が重要です。公式ドキュメントにも、組織管理者がMCPサーバーを制限するためのallowlist、denylist、managed MCPの説明があります。SDK生成に使うMCPは「読取中心」「変更系は明示承認」に寄せるのが無難です。
チーム運用では、CLAUDE.mdとSkillsも効きます。Claude Code公式ドキュメントでは、CLAUDE.mdや.claude/rules/*.mdがプロジェクトのコーディング規約やビルドコマンド、アーキテクチャ判断を伝える仕組みとして説明されています。Skillsは必要になったときに読み込まれる専門知識・ワークフローです。
MCPの実装観点はClaude Code MCP実践ガイドでも扱っています。SDK生成では、MCPを「仕様の正本へアクセスする道具」として使い、生成判断そのものはPull Request上で確認する運用が扱いやすいです。
APIクライアント生成のレビュー観点
生成後のレビューでは、通常のコードレビューとは少し違う観点が必要です。コードの見た目よりも、「仕様との同期」と「利用者が壊れないこと」を見ます。
| 観点 | レビュー質問 | 確認方法 |
|---|---|---|
| 仕様同期 | 生成元の仕様ファイルは今回の変更と対応しているか | OpenAPI/GraphQL schemaの差分を見る |
| 破壊的変更 | 既存メソッド名、型、必須パラメータが変わっていないか | 型チェック、API diff、サンプルコードのコンパイル |
| 認証 | 秘密情報を生成物やログに含めていないか | 環境変数名のみを使っているか確認 |
| エラー処理 | HTTPエラー、バリデーションエラー、ネットワーク失敗を区別できるか | エラー系テストを読む |
| 再生成性 | 誰が実行しても同じ生成結果になるか | 生成コマンド、lockfile、CIを確認 |
| ドキュメント | 利用者が最小サンプルだけで使い始められるか | READMEのimport例と認証例を読む |
Claude Codeには、このレビューだけを頼むこともできます。実装者とレビュアーの役割を分けると、生成コードの見落としが減ります。
あなたはSDK生成差分のレビュアーです。
今回の差分を読み、実装は変更せずにレビューだけしてください。
重点確認:
- 生成元のAPI仕様と生成物が対応しているか
- 破壊的変更がREADMEや移行メモに反映されているか
- 認証情報や本番URLがハードコードされていないか
- generated/以下を手編集していないか
- 型チェックと最小テストで検証できるか
- 利用者向けサンプルが最新か
出力形式:
- ブロッカー
- 要修正
- 任意改善
- 人間が確認すべき判断
数字と固有名詞は、根拠（ファイルパス/行/公式URL）を添えてください。【要注意】よくある失敗パターンと回避策
失敗1：仕様ファイルではなく既存コードから逆算してしまう
❌「今のフロントのAPI呼び出しを見て、SDKを作って」
⭕「api-spec/openapi.yamlを正本として、既存フロントのAPI呼び出しとの差分を洗い出してからSDKを作って」
なぜ重要か：既存コードはすでに仕様からずれている可能性があります。SDK生成では、どのファイルを正本とするかを最初に固定しないと、古い実装をきれいに再生産してしまいます。
失敗2：生成物にビジネスロジックを混ぜる
❌「generated/以下に認証、リトライ、UI向け整形も全部入れる」
⭕「generated/は仕様由来の低レイヤーに限定し、認証・リトライ・ログ・UI整形はラッパー層に分ける」
なぜ重要か：生成物は再生成で上書きされます。そこに手書きロジックを入れると、次回の仕様更新で壊れます。
失敗3：Claude Codeに許可するコマンドが広すぎる
❌「Bashを広く許可して、生成からテストまで全部自由に実行させる」
⭕「npm run generate:api、npm run typecheck、対象テストなど、実行してよいコマンドを明示する」
なぜ重要か：Claude Codeはコマンドを実行できるからこそ、権限設計が必要です。公式ドキュメントでも、権限、deny/askルール、Hooksでツール利用を制御する考え方が示されています。
失敗4：SDK生成を1回きりの作業にしてしまう
❌「初回だけClaude Codeで作り、再生成手順を残さない」
⭕「生成コマンド、入力仕様、検証コマンド、README、CIチェックをセットにする」
なぜ重要か：API仕様は変わります。SDK生成は初回より2回目以降が大事です。再生成できないSDKは、数週間後には手編集の塊になりやすいです。
30-60-90日の導入ロードマップ
SDK生成をチームに入れるなら、いきなり全APIを対象にしないほうがいいです。段階導入にします。
最初の30日：1つのAPIと1つの言語だけ
最初は、社内利用者が多いが影響範囲を限定できるAPIを選びます。TypeScriptかPythonのどちらか1つに絞り、生成コマンド、型チェック、代表テスト、README更新までをPull Requestにします。
この段階では、Claude Codeには「調査」「生成」「レビュー」の3役を分けて使います。1つの長いプロンプトで全部やらせるより、区切ったほうが差分を理解できます。
60日：破壊的変更の検出を入れる
次に、仕様差分から破壊的変更を検出するレビュー手順を入れます。完全自動判定にする必要はありません。まずはClaude Codeに「破壊的変更の候補」を出させ、人間が確認するだけでも十分です。
前回リリース時点のAPI仕様と現在のapi-spec/openapi.yamlを比較し、
SDK利用者に影響する破壊的変更の候補を抽出してください。
見る観点:
- 削除されたendpoint
- 必須化されたrequest field
- response typeの互換性がない変更
- error responseの変更
- 認証方式やscopeの変更
実装は変更しないでください。
判断が必要なものは「人間確認」として分類してください。90日：CIと社内ポータルに組み込む
最後に、claude -pやAgent SDKで、SDK生成チェックをCIや社内ポータルに組み込みます。公式ドキュメント上、非対話CLIではJSON出力やJSON Schemaを使えるため、CIが読みやすい形にできます。
ただし、編集まで完全自動にするかは慎重に判断してください。おすすめは「判定は自動、編集はPull Request、人間承認後にマージ」です。特に顧客向けSDKでは、破壊的変更の説明責任が残ります。
FAQ
Q1. Claude CodeだけでSDKをゼロから作れますか？
作れますが、実務では既存ジェネレータや社内標準スクリプトを優先するほうが安全です。Claude Codeには、仕様の読解、生成コマンドの配線、既存コードへの統合、テスト追加、README更新を任せるのが現実的です。
Q2. OpenAPIがない場合でもAPIクライアントを生成できますか？
既存コードやcurl例から下書きは作れます。ただし、正本となる仕様がないままSDKを公開すると保守が難しくなります。まずはClaude Codeで既存呼び出しを棚卸しし、OpenAPIやGraphQL schemaなどの仕様ファイルを作るところから始めるのがおすすめです。
Q3. 生成物を手で直してもよいですか？
原則として避けたほうがいいです。手で直す場合は、なぜジェネレータでは表現できないのかをREADMEやコメントに残してください。多くの場合、手直しはgenerated外のラッパー層に置けます。
Q4. Claude Agent SDKとClaude Code CLIのどちらを使うべきですか？
手元の開発作業ならCLIが簡単です。社内アプリ、CI、開発者ポータル、Botに組み込むならAgent SDKが向いています。公式ドキュメントではAgent SDKがPythonとTypeScriptからClaude Codeのエージェントループを扱えると説明されています。
Q5. 本番APIに接続してテストしてもよいですか？
所属組織の規程に従ってください。一般には、生成検証ではモック、ステージング、契約テストを優先し、本番APIや実顧客データへのアクセスは避ける設計が安全です。秘密情報はClaude Codeの出力やログに含めないでください。
Q6. SDK生成にMCPは必要ですか？
必須ではありません。MCPは、仕様の正本が外部システムにある、Issue trackerや社内DBと連携したい、リリースノートを自動で集めたい、といった場合に有効です。まずはローカル仕様ファイルと既存スクリプトだけで始めるのが扱いやすいです。
参考・出典
- Claude Code Overview — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Agent SDK overview — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Agent SDK reference – TypeScript — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Agent SDK reference – Python — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Run Claude Code programmatically — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Get structured output from agents — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Claude Code settings — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Hooks reference — Anthropic / Claude Code Docs（参照日：2026-07-07）
- Connect to external tools with MCP — Anthropic / Claude Code Docs（参照日：2026-07-07）
- How Claude remembers your project — Anthropic / Claude Code Docs（参照日：2026-07-07）
まとめ：今日から始める3つのアクション
- 今日やること：
CLAUDE.mdに、API仕様の正本、生成物の置き場所、実行してよい検証コマンド、秘密情報を扱わないルールを書いてください。 - 今週中にやること：Claude Codeで仕様監査プロンプトを実行し、既存の生成スクリプト、HTTP層、認証、テストの棚卸しをしてください。
- 今月中にやること：1つのAPIと1つの言語だけを対象に、生成コマンド、型チェック、代表テスト、README更新までをPull Request化してください。
あわせて読みたい：Claude CodeでバックエンドAPI開発を進める実践ガイド、Claude CodeでAPI変更レビューを行う手順、Claude Codeでテスト生成とTDDを進めるガイドも、SDK生成後の品質担保に役立ちます。
次回予告：次の記事では、生成したAPIクライアントを社内パッケージとして配布するためのバージョニング、CHANGELOG、破壊的変更検出、移行ガイド作成を扱います。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆。
