すべての記事
月次クレジット移行を前に、自動パイプラインの工程配分を見直した記録
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」と二段に分けて運用する設計を、私の本番ワークロードで観測した数値とともに整理しました。