すべての記事
Claude Files API のファイルが知らぬ間に溜まる — 内容ハッシュ台帳で重複を止め、孤児を回収する
自動パイプラインで Files API を使うと、同じファイルが何度もアップロードされ孤児ファイルが静かに溜まります。内容ハッシュ台帳での重複排除と、参照されなくなったファイルの GC 設計を実装例つきで解説します。
Claude API の静的キーをやめる — Workload Identity Federation で CI と本番を鍵なしに切り替える
Claude Platform で一般提供が始まった Workload Identity Federation を使い、sk-ant- 形式の静的キーを数分で失効する OIDC トークンへ移行する設計を扱います。GitHub Actions の鍵なし認証、移行手順、トークン更新まで具体的に整理しました。
Claude API のコスト計算が請求と合わないとき — usage の4トークンバケットを正しく会計する
プロンプトキャッシュを有効にすると、自前のコスト集計とコンソールの請求額が食い違うことがあります。input_tokensにキャッシュ分が含まれない仕様、単価の異なる4つのトークンバケットの重み付き会計、1コール1行で突合できる台帳の組み方までを運用上の注意とともにまとめました。
Claude API のストリーミングは「全部届く」前提が崩れる — 部分失敗を回復に変える運用メモ
Claude API のストリーミングは、同時接続が増えた途端に途中で切れ・重複し・半端なツール引数を吐きます。部分失敗を異常ではなく前提として扱い、静かに回復させるための実装と監視を、運用で削れた具体例とともにまとめました。
pause_turn の継続ループに上限を入れる — 無人で長時間サーバーツールを安全に回す
web_search や code execution など長時間サーバーツールを使うと返ってくる pause_turn を、無人運用で安全に継続する設計をまとめました。4種類の stop_reason を1ループで分岐し、継続回数と時間に上限を入れ、セグメントを跨ぐ usage を数える実装まで扱います。
90秒で切られるコード実行セルを跨いで、長いバッチをチェックポイント分割で回す
Claude のコード実行ツールはセル単位で90秒の上限が明示されました。長いバッチがここで打ち切られないよう、コンテナのファイルシステムへ進捗を残してセルを跨いで再開する設計を、計測・冪等なチェックポイント・撤退判断まで実装コード付きで整理します。
公開したくない社内サービスに Managed Agents を繋ぐ — MCP トンネル設計の勘所
Claude Managed Agents から、インターネットに公開していない社内 MCP サーバーへ安全に接続する設計を扱います。MCP トンネル・自前サンドボックス・認可境界・障害時の縮退まで、実運用で必要な判断を整理しました。
検索結果を二度運ばない — response_inclusion で消費済みブロックを応答から外す設計
dynamic filtering を有効にしたエージェントで出力トークンが膨らむ原因は、code execution が消費し終えた検索結果ブロックが応答に二重で乗ることにあります。response_inclusion を excluded にして安全に外せる条件と、full を保つべき条件を実装と判断表で整理しました。
service_tier で優先枠をユーザー応答だけに振り向ける
Priority Tier を契約しているのにピーク時だけユーザー向け応答が遅くなる——その原因を service_tier の auto と standard_only の挙動から切り分け、背景ジョブを優先枠から隔離する構成を、自動運用の実例とともにまとめました。
effort パラメータを工程ごとに振り分けて Claude の出力コストと待ち時間を整える
Claude API の effort パラメータは思考・本文・ツール呼び出しを含む出力トークン全体を制御します。一律 high をやめ、工程ごとに段階配分する実装と動的ルーターを、個人開発の自動運用での実測とともに解説します。
サブエージェントの並列実行で、1つの失敗が全体を巻き込まない設計
複数のサブエージェントを並列に走らせる fan-out / fan-in 構成を、トークン予算・結果コントラクト・部分失敗の扱いまで含めて設計します。1つのブランチが落ちても全体を止めない実装と実測値を共有します。
Cloudflare AI Gateway を Claude の手前に置くと、見えるはずの数字が見えなくなる — 運用で効いた計装メモ
Cloudflare AI Gateway を Claude API の前段に置いたあと、コスト按分・セマンティックキャッシュの誤ヒット・フォールバックの静かな品質低下・予算の実効化で実際につまずいた箇所と、その手当てをコード付きでまとめます。