プロンプトキャッシュを入れたのに請求が下がらなかったとき — cache_read を計測してヒット率の穴を塞ぐ運用メモ
cache_control を付けたのに Claude API の請求が下がらない。原因を推測で潰す前に cache_read と cache_creation を毎リクエスト記録し、ヒット率の穴を非決定プレフィックス・TTL 失効・しきい値未満の3系統に切り分ける運用メモです。
Extended Thinking を入れたのに精度は横ばい、請求だけ伸びていたとき — 思考トークンの限界効用を計測して budget を決める運用メモ
budget_tokens を大きめに固定したまま、精度が変わらないのに請求だけ伸びていく。思考トークンを台帳に残し、budget を1段上げたときの正解率の伸びを限界効用として計測して、根拠のある値に落とす運用メモです。
出力は同じ、道筋は違う — エージェントの軌跡を不変条件で守る
既定モデルが入れ替わっても最終出力は正しいまま、ツール呼び出しの道筋だけが静かに変わることがあります。実行トレースを記録し、不変条件で機械的にアサートする軌跡回帰ハーネスを実装コードと実測値で整理しました。
Web 監視が『異常なし』と言い続けた二週間 — 沈黙する取りこぼしを計測して切り分ける運用メモ
Cowork と Claude in Chrome で組んだ競合監視が、実際には変化を取りこぼしているのに『変更なし』と報告し続けることがあります。取得成功と抽出成功を分けて計測し、沈黙する失敗を検知する運用手順をまとめました。
Claude API のプロンプトキャッシュが本番で静かにヒットしなくなるとき — TTLと節約額の実測メモ
プロンプトキャッシュは導入直後だけ効いて、本番では知らぬ間にヒットしなくなることがあります。完全一致プレフィックスを静かに壊す5つの要因、5分と1時間TTLの選び方、節約額を推測でなく実測に変える計装、変更頻度の階段で置くブレークポイント設計までを運用目線でまとめました。
スケジュール生成が無音で不発に終わったことを、外側から気づく仕組み
exit 0 で終わったのに成果物がゼロだった——そんな無音の不発を、ジョブ自身のログではなく外部のハートビート台帳と地の事実から検知する設計を、個人開発で複数サイトを自動運用している立場からまとめました。
Claude API のレスポンスキャッシュが「古い答え」と「似て非なる誤答」を返すとき — 鮮度管理と誤ヒット抑制の実装メモ
Claude API のレスポンスキャッシュは速度とコストを劇的に改善しますが、運用で問題になるのは平均ヒット率ではなく、古い答えと意味的な誤ヒットの二つです。キー設計・鮮度管理・誤ヒット抑制・観測の実装をまとめます。
Claude Code の大規模リファクタを 1 コミット単位で巻き戻せる状態に保つ — チェックポイント設計とロールバック検知の実装メモ
Claude Code に大規模リファクタを任せると速さの裏でレビュー不能な巨大 diff が積み上がります。チェックポイントをマニフェストで管理し、コミット粒度を pre-push で機械的に強制し、ロールバック判断を Observability に紐づける——個人開発と受託で固めてきた実装メモです。
Claude API の PII マスキングは台帳運用で決まる — 復元・暗号化・漏洩率の本番設計メモ
Claude APIへ送る前のPIIマスキングで本当に難しいのは検出ではなく、復元用トークン台帳の運用です。正規表現とHaikuのNERによる2層検出、暗号化した共有ストアとしての台帳実装、ゴールデンデータセットによる漏洩率の毎日計測まで、本番で踏んだ落とし穴を含めて動くコード付きで整理します。
Claude API の本番観測性を OpenTelemetry GenAI 規約で再設計する — モデル移行とコスト監査に耐える設計メモ
Claude API を組み込んだプロダクションサービスの観測性を、OpenTelemetry GenAI セマンティック規約に揃えて再設計するための実装メモ。スパン属性、メトリクス、コスト追跡、モデル切替時のリプレイ性を、個人開発サービスで運用してきた経験から具体的なコードで示します。
Claude API のテレメトリを ClickHouse に流して分析する — 本番環境のコスト・遅延・エラーを可視化する設計ガイド
Claude API のリクエスト単位でコスト・遅延・トークン使用量を ClickHouse に蓄積し、Materialized View でリアルタイムダッシュボードを構築する本番運用設計を解説します。
Claude Code の実行を OpenTelemetry で観測する — エージェント処理を本番品質で可視化する設計ガイド
Claude Code のエージェント処理を OpenTelemetry でトレースする本番設計ガイド。フック連携・ツール呼び出し計測・MCP 通信・コスト属性・サンプリングまで、実運用で詰まらないパターンを解説します。