API / SDK
開発者向けの Claude API / SDK 連携ガイドです。認証、ストリーミング、ツール呼び出し、コスト管理、エージェント構築まで、動くコード例とともに本番運用の勘所を解説します。個人開発での実運用の実例も交えて紹介しています。
Claude API の Code Execution ツールに月次の売上CSV集計を任せる — Files API 連携から課金の落とし穴まで
月末に形式の違う売上CSVを突き合わせる作業を、Claude API の Code Execution ツールに任せた実装をまとめます。Files API 連携、コンテナ再利用、5分最小課金やファイルプリロード課金などの注意点を実例ベースで扱います。
月次クレジット移行を前に、自動パイプラインの工程配分を見直した記録
6月15日の課金変更で Agent SDK・headless 実行・GitHub Actions が月次クレジット制へ移行します。自動投稿パイプラインの工程を実測トークンから棚卸しし、3つの実行経路へ振り分け直した設計判断を共有します。
Claude API のモデル抽象レイヤー設計 — 世代交代に業務ロジックを巻き込まない内部アーキテクチャ
モデル文字列を業務コードに直書きすると、世代交代のたびに本番が静かに壊れます。論理ロールと物理モデルIDを切り離す anti-corruption layer を、TypeScript と Python の動くコード・移行コスト・実運用の判断軸とあわせて設計します。
MCP の tools 以外の3つの能力を使い分ける：resources・prompts・sampling の設計
MCP サーバーで何でも tools にしてしまう設計の限界を、resources・prompts・sampling という3つの primitive で解きほぐします。壁紙アプリのアセット管理サーバーを題材に、判断基準と実装、クライアント対応の現実的な制約までまとめました。
自律エージェントの破壊的操作に事前条件・事後条件の契約ゲートを付ける
スキーマも型も通るのに中身が壊れている——自律エージェントのもっともらしい失敗を、事前条件・事後条件の契約ゲートで止める設計です。tryGuard・commitGuard・rollbackの構造、TypeScriptでの実装、スナップショットによる安全な巻き戻し、既存エージェントへの後付け手順まで紹介します。
ユーザーレビューやクラッシュログをClaude APIに渡す前に — 個人情報を可逆マスキングする前処理の設計メモ
App StoreのレビューやCrashlyticsのログをClaude APIで分析するとき、本文に紛れ込む個人情報をどう扱うかは避けて通れません。出力から実データへ辿り直せる可逆マスキングの設計と、本番で踏んだ落とし穴を実装コード付きでまとめました。
Crashlyticsのクラッシュを根本原因ごとに束ねる — Claude APIで作るトリアージの設計メモ
Crashlyticsの「Issue」は同じ原因を別物として散らしてしまうことがあります。累計5,000万DLのアプリ運用で溜まったクラッシュを、Claude APIで根本原因ごとに束ね直して優先順位をつける設計を、動くコードと実測値とともに共有します。
Claude 非同期パイプラインで「毒メッセージ」を隔離する — デッドレターキュー設計の実装メモ
1件の壊れた入力がバッチ全体を止める「毒メッセージ」問題を、Cloudflare Queues のデッドレターキューで隔離する設計と実装。Claude API 特有の失敗パターンの切り分けまで実体験ベースでまとめます。
再現できないエージェント障害をなくす設計 — 決定論的リプレイとイベントソーシング
深夜に一度だけ失敗した自律エージェントの障害は、そのまま再実行しても再現できません。モデル出力やツール入出力といった非決定の境界をイベントログに記録し、決定論的にリプレイして原因を特定する設計を、スキーマ定義から録音再生ラッパー、実行単位のコスト配賦まで実装コードとともに解説します。
Claude API の max_tokens 打ち切りを継続生成でつなぐ — 重複とコードブロック分断を防ぐ実装
長文生成が途中で切れる max_tokens 打ち切りを検出し、assistant プレフィルで続きを書かせ、つなぎ目の重複やコードフェンスの分断を防いで安全に組み立てる継続生成の実装パターンをまとめました。
Claude の品質回帰を eval ハーネスで自動検出する設計
プロンプトを少し直したら、別の入力で出力が静かに悪化していた。本番投入した Claude の品質をプロンプト変更やモデル更新のたびに守るための eval ハーネスを、実装コードと運用での実測値とともに整理しました。
Claude API に画像 URL を渡すと invalid_request_error が出るときの切り分け
Claude API の Messages で `source.type: url` を指定した画像が invalid_request_error で落ちるとき、原因は URL スキーム・MIME・サイズ・到達性のどれかにほぼ収束します。診断順に整理します。
Claude API のプロンプトキャッシュを 5m と 1h で二段に分ける — TTL を分けるとコストは下がり運用は安定する
Anthropic API の cache_control には 5 分と 1 時間という 2 種類の TTL があります。これを「静的な前提情報は 1h、可変な few-shot は 5m」と二段に分けて運用する設計を、私の本番ワークロードで観測した数値とともに整理しました。
Claude API の本番観測性を OpenTelemetry GenAI 規約で再設計する — モデル移行とコスト監査に耐える設計メモ
Claude API を組み込んだプロダクションサービスの観測性を、OpenTelemetry GenAI セマンティック規約に揃えて再設計するための実装メモ。スパン属性、メトリクス、コスト追跡、モデル切替時のリプレイ性を、個人開発サービスで運用してきた経験から具体的なコードで示します。
Claude API のストリーミングで tool_use の引数が JSON パースに失敗する原因と対処
Claude API のストリーミングで tool_use を受け取ると、なぜか JSON.parse が SyntaxError を返す。input_json_delta の正しい組み立て手順と、再接続時の取りこぼし対策をまとめます。
Claude API のスケジュール運用で観察した tail latency と、リトライストームを抑えるガードレール設計
個人開発で 6 サイトを並行運用し、14 日分のログから p95/p99 の輪郭とリトライ嵐の発生条件を観測しました。ジッタ・バジェット・サーキットブレーカーを組み合わせた本番ガードレールの実装と、観測 → 設計 → 改善の比較値をまとめます。
Claude API の構造化レスポンスを本番で安定させる — tool_use と JSON Schema、多層検証の実装メモ
Claude API の応答を JSON で受け取る実装は数行で書けますが、本番運用では「形は正しいが意味が壊れている」レスポンスにどう備えるかが分かれ目になります。tool_use・JSON Schema・ドメイン検証を組み合わせた多層パイプラインを、壁紙アプリの分類処理での実体験を交えて整理しました。
Claude API のグレースフル・デグラデーション設計 — AI 機能が静かに動き続ける 4 階層フォールバック
Claude API を本番運用すると、モデル単位のフォールバックだけでは守りきれない時間帯が必ず出てきます。SLI 連動の 4 階層デグラデーション設計を、Python と TypeScript のコード・SLO バーンレート・実運用の判断軸とあわせて整理しました。
二段構えのモデル構成 — Haiku 4.5 オーケストレーター × Opus 4.6 ワーカーで保つコストと品質の均衡
オーケストレーションをHaiku 4.5に、専門タスクをOpus 4.6に任せる二段構えの構成を、公表単価に当てた月次試算つきで書き残します。ワーカーに任せる5つの判定基準、ストリーミングの使い分け、詰まった落とし穴、そして来なかった値上げに備えて設計を動かしてしまった失敗まで。
Claude API のレスポンスを Cloudflare R2 にアーカイブする実装メモ — 監査・再現性・障害分析の3軸設計
Claude API のリクエストとレスポンスを Cloudflare R2 に保存して、監査・障害分析・本番リプレイの3つに使う設計を、Workers の waitUntil パターンと D1 メタデータインデックス込みで実装メモにまとめました。
Claude API の Tool Result Submitted エラーをリトライ層で吸収する — 会話履歴を自分で修復する小さな実装
Claude API の「Tool result could not be submitted because the previous turn」エラーを、リトライ層で会話履歴を巻き戻して再送信する実装パターンと、私が壁紙アプリ運営の API 連携で実際にハマった原因の切り分け順序を書きました。
Claude API の 529 Overloaded を本番アプリで吸収する — レジリエンス実装パターン
529 Overloaded は単発のリトライでは止まりません。累計5,000万DLのアプリ運用で踏んできた失敗を踏まえ、ユーザー体験を落とさずに吸収するためのキュー化・モデル切替・フォールバック設計をコード付きで整理します。
Claude API のジョブキューに優先度と公平性を組み込む設計 — 5,000万DL個人開発で実装したバックプレッシャーの実践
Claude API を本番運用すると必ず詰まる「長文1リクエストが短文100リクエストを止める」問題に、3層プライオリティキューと DRR で公平性を入れた実装の話です。アーティスト・個人開発者の廣川政樹が5,000万DLアプリで運用してきた構成を、コードと運用メトリクスとともに共有します。
Claude の『このモデルは現在利用できません』が出る時に効くモデル選択フォールバックの設計
Claude API で『このモデルは現在利用できません（this model is currently unavailable）』と返ってきたとき、529 Overloaded やレート制限と同じ扱いにすると遠回りになります。エラーの種類を SDK の例外クラスで見分け、モデル ID をリクエスト単位で切り替えるフォールバックの実装と、思い込みで書きやすい落とし穴をまとめました。
Claude API の 200K コンテキストをどう割り振るか — システム・ツール・メモリ・履歴の予算枠を実運用で決めた話
Claude API の 200K コンテキストを「無制限の置き場」ではなく予算として扱い、システム・ツール定義・メモリ・履歴・回答ヘッドルームに枠を切る設計を、TypeScript の実装コードと壁紙アプリ運用で得た数値とともに記録しました。
Claude API の tool_result could not be submitted が再発しないための回復ハンドラ設計
Claude API でエージェントを長時間動かしていると、ある日突然 'tool_result could not be submitted' が連発し始めることがあります。再試行しても直らない、ストリーミング途中で死ぬ、そして次のセッションでもまた出る — 常時稼働のエージェント基盤で実際に踏み抜いた4種類の原因と、TypeScript で書いた回復ハンドラの実装を整理しました。
App Store Connect・Play Console・Crashlytics・AdMob を横断する『朝刊エージェント』を Claude Agent SDK で組んだ1ヶ月の運用記録
アプリ6本を運営していると、朝起きて4つの管理画面を順に開くだけで30分以上消えていきます。その時間を 1 通のダイジェストに圧縮した Claude Agent SDK のレシピを、実測データつきで共有します。
Claude API のトークンコストを月初3日間データから±10%精度で月末予測する
月初の3日間トークン消費データから月末コストを±10%精度で予測するEWMA＋季節性分解モデルの実装と、しきい値超過時に自動的にプロンプトキャッシュやモデルルーティングを切り替える本番設計を解説します。
Claude Agent SDK で複数 MCP サーバを束ねるときのツール名衝突 — 名前空間と動的調停の設計
GitHub MCP と Linear MCP の create_issue が同居したとき、Sonnet 4.6 はどちらを呼ぶか分かりません。複数 MCP を束ねる Claude Agent SDK アプリで踏むツール名衝突の構造、TypeScript で書ける Reconciler の実装、そして本記事に最初に載せた schemaHash が5種類のスキーマ変更を全て見逃していた実測と訂正までをまとめます。
Claude エージェントのツール返り値を圧縮する — 巨大レスポンスを文脈に積まずに集約する設計
データベースの数千行、Webスクレイプ後のHTML、ファイル読み込みの数MBといった巨大なツール出力をそのまま Claude に渡すと文脈が破裂し、コストも品質も同時に悪化します。スキーマ縮約・サマリ・参照渡しの3層で圧縮する本番アーキテクチャを実装パターン付きで整理しました。
Claude API のチャット履歴を階層サマライズする：3 段階圧縮でトークンを 70 % 削減した設計
壁紙アプリのインアプリ AI チャットで増え続ける履歴トークンを抑えるため、直近ターン・中期エピソード・長期エンティティの 3 層に分けて圧縮する設計を、TypeScript の動くコードと 7 週間の運用データつきで記録しました。月額 API 費用を $480 から $145 まで下げています。
Claude エージェントに安全弁を仕込む：個人運営で暴走を止める三層キルスイッチ設計
個人運営の Claude エージェントで実際に経験したリトライ暴走 3 時間で $32 の損失を起点に、プロセス内ガード・プラットフォーム停止フラグ・観察層の三層キルスイッチを Cloudflare Workers + KV で組む設計記録。TypeScript の動くコードと運用メトリクス付き。
Claude SDK でツール呼び出しが InputValidationError で失敗し続ける：Deferred Tools の正しい扱い方
Claude Code SDK や Cowork でツールを呼び出すと InputValidationError が発生するケースの根本原因と解決策。Deferred tools の仕組みを理解し、ToolSearch を正しく使うことで解消できます。
Claude API の Tool Use でスキーマ定義ミスが出たとき：実際に遭遇した3つのパターンと診断手順
Claude API の Tool Use でよく起きるスキーマ定義ミス・invalid_tool_use・Claude がツールを呼ばない問題を、実際のアプリ開発で遭遇したケースをもとに診断手順と修正パターンで解説します。
Claude API で多言語レビュー返信を自動化した実装ログ — App Store 非公式制限との付き合い方
壁紙・ヒーリング系アプリを複数運営する個人開発者が、Claude APIで多言語レビュー返信を自動化した実装ログ。App Storeの8秒待機ルールや1セッション30件制限など、公式ドキュメントには書かれていない落とし穴と解決策を詳解します。
壁紙アプリの一括カテゴリ分類を Claude Vision API で自動化した話 — 実運用で見えた精度と限界
個人開発の壁紙アプリで画像のカテゴリ分類をClaude Vision APIに任せた実体験の記録です。SonnetとHaikuのモデル選択、75枚の手動検証で確かめた分類精度、実運用で踏んだ落とし穴、途中で落ちても再開できるバッチ設計、そして実際にかかったコストの感覚まで正直に書きました。
Claude API Messages Batches API でコストを半額にする — 個人開発者が学んだ非同期処理設計
Claude API の Messages Batches API を使って API コストを最大50%削減する非同期設計パターン。個人開発で実際に運用して気づいた設計判断・コスト試算・本番環境でのエラー処理まで実装コードとともに解説します。
Claude API でアプリ内 AI チャットを実装して踏んだ6つの罠 — 本番投入までの設計記録
Claude APIをアプリ内チャットに組み込んで本番で直面した6つの設計ミスを、個人開発での実運用経験から解説。コンテキスト設計、ストリーミング、セッション管理、コスト監視の実装パターンを動くコード付きで紹介します。
Claude API のモバイル統合で個人開発者が直面する設計判断 — コスト・UX・オフライン対応の実践パターン
Claude APIをiOS/Androidアプリへ組み込むときに迫られるモデル選定・非同期設計・コンテキスト管理・オフライン対応・コスト管理の判断を、動くコードと2026年9月の価格改定を織り込んだ月額試算つきでまとめました。
App Storeのレビュー1,000件をClaude APIで分析したら、自分のアプリの本当の問題が見えてきた
個人開発10年超・累計5,000万DLの経験から語る。App StoreレビューをClaude APIでバッチ分析し、次の改善優先順位を自動生成する実装パターンと、試して気づいた落とし穴を共有します。