すべての記事
自律エージェントの破壊的操作に事前条件・事後条件の契約ゲートを付ける
スキーマも型も通るのに中身が壊れている——自律エージェントのもっともらしい失敗を、事前条件・事後条件の契約ゲートで止める設計です。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 の輪郭とリトライ嵐の発生条件を観測しました。ジッタ・バジェット・サーキットブレーカーを組み合わせた本番ガードレールの実装と、観測 → 設計 → 改善の比較値をまとめます。