スマートフォンから本番環境の問題をデバッグする

金曜日の午後7時。友人と夕食中にスマートフォンがPagerDutyアラートで振動します：決済サービスのエラー率が15%にスパイクしました。ノートパソコンは自宅にあります。チームメイトはオフラインです。このインシデントはあなたが対応する番です。

これがTactic Remoteが存在する理由です。このチュートリアルでは、iPhoneのみを使用した現実的な本番デバッグワークフローを解説し、リモートで問題を調査、診断、修正する方法を示します。

シナリオ設定

このチュートリアルでは、現実的なシナリオに取り組みます：

• サービス： Node.js決済処理API
• 症状： /api/payments/processエンドポイントでの500エラー
• 影響： 決済試行の15%が失敗
• 環境： SSH経由で本番ログが利用可能、コードベースはMac上

自宅のMacはオンで、Tactic Remoteコンパニオンアプリが実行されています。iPhoneから接続して調査を開始します。

フェーズ1：トリアージ（5分）

最初の目標は、範囲と緊急性を理解することです。プロジェクトディレクトリを指すClaude Codeセッションを開始します：

We have a production incident. The /api/payments/process endpoint
is returning 500 errors for ~15% of requests. This started approximately
30 minutes ago.

Help me investigate:
1. Check the git log for any recent deployments (last 24 hours)
2. Look at the payment processing code in src/api/payments/
3. Check if there were any dependency updates recently

Claude Codeがコードと最近の変更を調査します。その間、スマートフォンのブラウザでモニタリングダッシュボードを開いて確認します：

• エラー率は安定しているか、増加しているか、減少しているか？
• すべてのインスタンスに影響があるか、一部だけか？
• 失敗するリクエストにパターンがあるか？

Claude Codeが見つける可能性があるもの： 3時間前のコミットでStripe SDKの依存関係がv12.1.0からv13.0.0に更新されており、破壊的なAPI変更が含まれていた。

フェーズ2：診断（10分）

仮説（Stripe SDKの更新）を基に、より深く掘り下げます：

Compare the Stripe SDK v12 and v13 changelog.
Check our payment processing code for any API calls that changed
between versions. Focus on the payment intent creation and
confirmation flow in src/api/payments/processor.ts.

Claude Codeがコードを分析し、具体的な非互換性を特定します。典型的な発見：

Found the issue. In Stripe SDK v13, the `payment_intents.create()` method
changed its error handling behavior:

- v12: Returns { error: { type, message } } for card declines
- v13: Throws StripeCardError exception for card declines

Our code in processor.ts:45-52 checks for `result.error` but doesn't
catch the new exception type. When a card is declined, the uncaught
exception propagates as a 500 error.

This explains the 15% error rate — approximately 15% of payment
attempts involve card declines (expired cards, insufficient funds, etc.)
that now throw uncaught exceptions.

この診断は具体的で、テスト可能で、観察された動作を説明しています。スマートフォンから、先に進む前に内容が妥当か確認できます。

フェーズ3：修正（10分）

修正を実装します。2つの選択肢があります：

オプションA：クイックロールバック

状況が緊急で、前のバージョンが安定していた場合：

Revert the Stripe SDK update. Change package.json to pin
stripe at v12.1.0. Create a commit with message:
"hotfix: revert Stripe SDK to v12 (fixes payment 500 errors)"

承認ステップ： Claude Codeはpackage.jsonの変更とnpm installの実行の承認を求めます。承認カードで変更内容を確認して承認します。

オプションB：前方修正

v13で動作するようにコードを修正したい場合（他の改善を失うロールバックを避ける）：

Fix the payment processing code to handle both the legacy error
response format and the new exception-based error handling in
Stripe SDK v13.

Specifically:
1. Wrap the payment_intents.create() call in a try/catch
2. Catch StripeCardError and convert it to our standard error format
3. Keep the existing result.error check as a fallback
4. Add a test case for the card decline scenario

Commit with: "hotfix: handle Stripe v13 exception-based card decline errors"

Claude Codeが変更を行い、テストを実行します。ターミナルビューでテスト結果を確認しましょう。

承認フロー： 複数の承認リクエストが表示される可能性があります：

1. src/api/payments/processor.tsの変更 — 承認（これが修正）
2. src/api/payments/__tests__/processor.test.tsの変更 — 承認（テスト追加）
3. npm testの実行 — 承認（修正の検証）

フェーズ4：デプロイ（5分）

修正がコミットされテストが通ったら：

Push this commit to the main branch.
Then trigger the deployment pipeline by running our deploy script:
./scripts/deploy.sh production

重要な承認： Claude Codeはデプロイコマンドの承認を求めます。これはワークフローで最もリスクの高いアクションです。慎重に確認しましょう：

• コミットメッセージが修正内容と一致していることを確認
• デプロイ先が正しいこと（production）を確認
• 前のステップでテストが通ったことを確認

承認後、Claude Codeがデプロイを実行します。ターミナル出力でデプロイの進行状況を監視しましょう。

フェーズ5：確認（5分）

デプロイ完了後：

Check the deployment status. Then help me verify:
1. Run a test request against the production payment endpoint
2. Check if the error rate has started decreasing
3. Look for any new error patterns in the last 5 minutes

同時に、スマートフォンでモニタリングダッシュボードを確認します。デプロイ完了後数分以内にエラー率が下がり始めるはずです。

インシデント後：レポートの作成

インシデントの記憶が新しいうちに（まだ夕食中、コースの間に）：

Write a post-incident report based on our investigation:

Include:
- Timeline of events
- Root cause (Stripe SDK v13 breaking change)
- Impact (15% payment failure rate for ~1 hour)
- Resolution (code fix to handle new exception type)
- Action items to prevent recurrence

Format as a markdown document in docs/incidents/

これにより月曜の朝までにチームに完全なインシデントレポートが届きます。夕食の同席者はほとんど中断に気づかなかったでしょう。

効果的なリモートデバッグのヒント

広く始めて、狭く絞る。 すぐに仮説に飛びつかないでください。特定の原因に集中する前に、Claude Codeに全体像（最近の変更、エラーパターン、システム状態）を調査させましょう。

承認ゲートをチェックポイントとして使う。 各承認リクエストは、Claude Codeが何をしているかを確認する自然なチェックポイントです。調査が正しい方向に進んでいるか確認するために活用しましょう。

診断と修正を分離する。 明確な診断を得て、内容が妥当であることを確認してから変更を実装しましょう。これにより、根本原因を理解せずに変更を行う「修正の追いかけ」を防ぎます。

デバッグ中にコミュニケーションする。 チームにインシデントチャネルがある場合、スマートフォンから更新を投稿しましょう：

• 「決済500エラーを調査中。Stripe SDKの更新が原因と疑われる。」
• 「確認：SDK v13がカード拒否のエラーハンドリングを変更。修正をデプロイ中。」
• 「修正デプロイ完了。エラー率が正常に戻りつつある。」

これにより関係者に情報が共有され、重複した調査を防ぎます。

限界を知る。 一部の本番問題は、インフラアクセス、データベースクエリ、またはClaude Codeでは実行できないシステムレベルのデバッグが必要です。行き詰まったら、エスカレーションしましょう — ワークステーションで5分で済むことにスマートフォンで1時間費やさないでください。

インシデントツールキットの構築

インシデントが発生する前に準備しておきましょう：

1. デプロイスクリプトとモニタリングツールにアクセスできる本番デバッグセッションを事前に準備する。
2. Claude Codeが従えるインシデント対応プロンプトをプロンプトライブラリに作成する。
3. プレッシャーが本物になった時にフローに慣れるように、重要でない状況でワークフローをテストする。
4. どこからでもデバッグできるようにCloudflare Tunnelアクセスを確保する。

本番インシデントは都合の良いタイミングを待ってくれません。Tactic Remoteは、どこにいても効果的に対応するためのツールを確保します。