service-debugging について
サービス障害を体系的に調査・修正するための開発者向けガイドです。症状の収集から修正の検証まで、ログ、デプロイ履歴、再現、根本原因分析を扱います。
主な機能
- 01症状と影響範囲の事前確認
- 02デプロイ履歴、ヘルス状態、ログの確認
- 03エラー種別に応じた調査範囲の絞り込み
- 04再現と git bisect による原因特定
- 05修正前の失敗テストと修正後の検証
活用シーン
- 01API エラーやサービスクラッシュの調査
- 02遅いクエリ、タイムアウト、データ欠損の診断
- 03デプロイ後に発生したリグレッションの追跡
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/service-debuggingを入力して読み込まれたか確認します。
同梱ファイルcommon-issues.md
詳細
サービスのデバッグ
サービスの問題を調査して修正するための、体系的なアプローチです。症状から原因を突き止めます。
使用する場面
- API エンドポイントでエラー（4xx、5xx）が返される
- パフォーマンスが低下している、またはクエリが遅い
- サービスが起動しない、またはクラッシュする
- サービス間でデータに不整合がある
- デプロイ後に何かが壊れた
- ユーザーから「何かが壊れている」と報告された
手順
1. 症状を集める
コードに手を加える前に、以下を収集します。
- 何が壊れていますか？（具体的なエンドポイント、機能、動作）
- いつから発生していますか？（デプロイ後ですか？徐々にですか？突然ですか？）
- 誰に影響していますか？（すべてのユーザー、特定のユーザー、特定のデータですか？）
- エラーメッセージはありますか？（ログ、HTTP レスポンス、スタックトレース）
2. 明らかな点を確認する
まず以下を実行します。問題の 80% はこれで見つかります。
# Recent deploys (did someone push something?)
git log --oneline -10
# Service health
curl -s http://localhost:8080/health | jq .
# Recent errors in logs
grep -i "error\|exception\|fatal" logs/app.log | tail -20
# Database connectivity
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"
# Environment variables (missing or wrong?)
env | grep -i "DB_\|API_\|SECRET_" | sort
3. 範囲を絞り込む
| 症状 | 最初に確認すること |
|---|---|
| 500 エラー | ログのスタックトレース → 例外を投げている行を見つける |
| 404 エラー | ルート登録 → コントローラーが読み込まれていますか？ |
| 401/403 エラー | 認証設定 → @Secured は正しいですか？トークンは有効ですか？ |
| レスポンスが遅い | データベース → 遅いクエリに対して EXPLAIN を実行する |
| タイムアウト | 外部サービス → 下流の API は応答していますか？ |
| データが見つからない | 論理削除 → deleted_at が設定されていますか？クエリのフィルターが間違っていませんか？ |
| サービスが起動しない | Bean の作成 → @Factory と @Singleton の配線を確認する |
4. 再現する
- ローカルでバグを再現できますか？
- 失敗する最小限のリクエストは何ですか？
- 常に失敗しますか、それとも断続的に失敗しますか？
5. 根本原因を見つける
リグレッションの場合は git bisect を使います。
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each commit until you find the one that broke it
関連コードを見つけるには grep を使います。
# Find where the error message comes from
grep -r "error message text" --include="*.kt" src/
# Find all callers of a broken function
grep -r "functionName" --include="*.kt" src/
6. 修正して検証する
- バグを再現するテストを書く（レッド）
- コードを修正する（グリーン）
- テストスイート全体を実行する
- ユーザーに影響する問題なら手動でテストする
よく見られるバグとその修正方法については、
common-issues.mdを参照してください。
注意点
- 症状ではなく原因を修正してください。 データの問題を隠す null チェックを追加すると、後でそのデータの問題に悩まされることになります。
- コードのせいにする前に、デプロイログを確認してください。 設定変更、環境変数の更新、インフラの変更は、コードのバグよりも多くの障害を引き起こします。
- 「自分のマシンでは動く」は、たいてい環境の違いを意味します。 ローカルの環境変数、データベースの状態、サービスのバージョンを対象環境と比較してください。
- 断続的な障害は、たいてい競合状態が原因です。 10 回に 1 回失敗する場合は、並行アクセス、共有された可変状態、接続プールの枯渇を調べてください。
- 最初のデバッグ手順としてサービスを再起動しないでください。 診断に役立つ状態が失われます。まずログを読み、必要に応じて再起動してください。
- 論理削除されたレコードは、「データが見つからない」原因の第 1 位です。 クエリで常に
deleted_at IS NULLを確認してください。
ルール
- コードを変更する前に、必ず症状を集める
- 修正前に、失敗するテストを書く
- 最近の git 履歴を確認する。バグのほとんどはリグレッションです
- 根本原因を理解せずに修正をデプロイしない
- ユーザーに影響した場合は、インシデントを記録する
コメント
Markdown 対応