すべての記事
共通エージェント定義をセッション単位で使い分ける運用設計
Managed Agents で土台のエージェント定義を1つに畳み、バージョン固定とセッションローカルな上書きを使い分ける設計を、検証付きのコードと運用の落とし穴とともにまとめました。
プロンプトキャッシュを入れたのに請求が下がらなかったとき — cache_read を計測してヒット率の穴を塞ぐ運用メモ
cache_control を付けたのに Claude API の請求が下がらない。原因を推測で潰す前に cache_read と cache_creation を毎リクエスト記録し、ヒット率の穴を非決定プレフィックス・TTL 失効・しきい値未満の3系統に切り分ける運用メモです。
ユーザーに届くAI生成の短文を、公開前に二段ゲートで止める
アプリでユーザーに届くAI生成の短文を、決定的ルール層とClaude分類層の二段ゲートで公開前に検査する設計です。fail-closedを芯に据えた判定統合、生成時に検疫して配信時は取り出すだけの構成、生成数で効くコスト設計、人間のサンプリング体制まで実装コード付きで整理しました。
検索の精度は二段目で決まる — 埋め込みで粗く集め、Claude で並べ直す個人ナレッジ検索
埋め込み検索だけでは「意味は近いが答えではない」候補が上位に残ります。粗く集めた候補を Claude で並べ直す二段検索の設計を、構造化スコアリング・棄権・コスト試算まで個人ナレッジ検索の実装でまとめました。
Claude API の同時実行を束ねる — シングルフライトで重複推論とキャッシュ・スタンピードを防ぐ
同一プロンプトが同時に何度も Claude へ飛ぶ重複推論を、シングルフライト（request coalescing）で束ねる設計です。プロセス内・分散環境の実装、ジッター付きリトライ、負のキャッシュまで実測付きでまとめました。
画像を原寸で送るか縮小するか — Opus 4.7 の高解像度ビジョンで1枚ごとに解像度を決めるコスト設計
Opus 4.7 の高解像度ビジョンで壁紙の細部分類は上がったのに、全部を原寸で送ったら週のトークンが跳ねました。1枚ごとに解像度と使うモデルを決める preflight を設計し、精度を保ったままコストを下げた実測を残します。
Extended Thinking を入れたのに精度は横ばい、請求だけ伸びていたとき — 思考トークンの限界効用を計測して budget を決める運用メモ
budget_tokens を大きめに固定したまま、精度が変わらないのに請求だけ伸びていく。思考トークンを台帳に残し、budget を1段上げたときの正解率の伸びを限界効用として計測して、根拠のある値に落とす運用メモです。
Claude API の 413 request too large を設計で避ける — 送信前サイズ見積もりと分割の実装
長文と画像と tool_result を1リクエストに詰めすぎると Claude API は 413 request too large で落ちます。32MB の壁・base64 の膨張・処理段階で起きる隠れた上限を実測し、送信前にサイズを見積もって安全に分割する設計をコード付きでまとめました。
APIキーに有効期限を付けると、失効は事故ではなく予定になる — 無人運用の鍵カレンダー設計
Console で APIキーに有効期限を設定できるようになりました。無人で回している夜間ジョブを止めないために、二重鍵の重ね替えとローカルの失効台帳で「予定された失効」を運用に組み込む方法をまとめます。
非ストリーミングの長い応答が10分の壁で黙って二重課金されていた — SDK既定のタイムアウトと自動リトライを設計し直す
Anthropic SDK の既定タイムアウト10分と自動リトライ2回が、長い非ストリーミング応答を裏で二重に走らせて課金することがあります。発生の仕組みと、ストリーミング切替・明示的な timeout/max_retries・ローカル台帳で止める実装を、実測値とともにまとめました。
生成した壁紙が既存カタログに似すぎていないか — 知覚ハッシュで絞り Claude Vision で最終判定する近重複検出
SHA256の完全一致ではすり抜ける再配色・軽いクロップのニアデュプを、知覚ハッシュの事前フィルタとClaude Visionの最終判定で捕まえる二段構えのパイプライン。実測のprecision較正とコスト設計まで、壁紙カタログの個人運用から共有します。
本番で観測した引数分布からツールスキーマを締め直す
Claudeのツール呼び出しが渡してくる引数を本番で丸ごと記録し、その分布からJSON Schemaにenumやpatternを足して締め直す運用手法を整理しました。緩いスキーマが生む意味のドリフトの実例、段階的に締める手順、締め直し前後の実測値、状況別の推奨まで計測コード付きで紹介します。