Troubleshoot - 体系的なデバッグ

役割の明確化: このスキルは体系的なデバッグに特化しています。

•テストの作成 → /write-tests

•コード品質の自動修正 → /ensure-quality

•コードの詳細分析 → /analyze

目的

このスキルは以下を提供します：

•問題の体系的な特定: エラーメッセージや症状から根本原因を追跡
•エビデンスベースの分析: データに基づく診断とアプローチ
•段階的な解決策: 最小限の変更で問題を解決
•再発防止策: 同様の問題を防ぐための予防策提案

いつ使用するか

プロアクティブ使用（自動で使用を検討）

以下の状況では、ユーザーが明示的に要求しなくても使用を検討してください：

•
エラーが発生している
- •テスト実行失敗
- •型チェックエラー
- •ランタイムエラー
- •インポートエラー
•
パフォーマンス問題
- •処理時間の遅延
- •メモリリーク
- •API応答時間の増加
•
予期しない動作
- •期待と異なる結果
- •断続的に発生する問題
- •環境依存の問題

明示的な使用（ユーザー要求）

•/troubleshoot コマンド
•「デバッグして」「エラーを調査して」などの直接的な要求

デバッグプロセス

ステップ 1: 問題の特定

症状を収集し、問題の範囲を明確化します。

実施内容:

yaml

症状の収集:
  - エラーメッセージ
  - 発生条件
  - 影響範囲
  - 再現手順

チェックポイント:

• エラーメッセージを完全に収集
• 再現手順を確立
• 影響範囲を特定

ステップ 2: 原因分析

体系的にログやスタックトレースを解析します。

実施内容:

yaml

分析手法:
  - スタックトレース解析
  - ログファイル調査
  - 環境差分の確認
  - タイミング問題の検証

使用ツール:

bash

# ログ確認
Read log_file.log

# スタックトレース解析
Grep "Traceback" -A 10 log_file.log

# 関連ファイル検索
Glob "**/*error*.py"

チェックポイント:

• スタックトレースを完全に読み取った
• ログファイルから関連情報を抽出
• 環境変数や設定の違いを確認

ステップ 3: 仮説立案

証拠に基づき、問題の原因仮説を立てます。

実施内容:

yaml

仮説の優先順位:
  1. 最も可能性が高い原因
  2. 最も影響が大きい原因
  3. 最も修正が簡単な原因

分析手法:

Five Whys (なぜなぜ分析)

yaml

症状: APIがタイムアウトする
なぜ1: レスポンスに5秒以上かかる
なぜ2: データベースクエリが遅い
なぜ3: インデックスが不足している
なぜ4: 大量データ投入時に作成されなかった
なぜ5: マイグレーションスクリプトの不備

根本原因: マイグレーションプロセスの改善が必要

二分探索デバッグ

yaml

手法: 問題の範囲を半分ずつ絞り込む
1. 全体の中間点でテスト
2. 問題がある側を特定
3. その範囲の中間点でテスト
4. 問題箇所を特定するまで繰り返し

チェックポイント:

• 複数の仮説を立てた
• 優先順位をつけた
• 検証方法を決定

ステップ 4: 解決策の実装

段階的に修正を適用し、副作用を確認します。

実施内容:

yaml

修正アプローチ:
  - 最小限の変更
  - 段階的な適用
  - 副作用の確認
  - テストの追加

使用ツール:

bash

# コード修正
Edit file_path old_string new_string

# テスト実行
Bash make test

# 型チェック
Bash make typecheck

チェックポイント:

• 最小限の変更で修正
• テストで修正を確認
• 回帰テストを追加

ステップ 5: 検証と予防策

修正を検証し、再発防止策を提案します。

実施内容:

yaml

検証方法:
  - 修正を確認するテスト
  - 回帰テスト
  - パフォーマンステスト

予防策:
  - 同様の問題を防ぐ方法
  - 監視の追加
  - ドキュメント化

チェックポイント:

• 全テストがパス
• 予防策を提案
• ドキュメント更新

デバッグモード

--fix (自動修正モード)

一般的なエラーパターンを認識し、安全な修正を自動適用します。

適用範囲:

•型エラー（型変換の追加）
•インポートエラー（パッケージ追加）
•フォーマットエラー（make format）
•リントエラー（自動修正可能な項目）

制約:

•ロジック変更は行わない
•安全性を優先
•ロールバック可能な修正のみ

--prod (本番環境対応モード)

本番環境の問題に対し、最小限の変更で修正します。

特徴:

•最小限の変更で修正
•ダウンタイムの最小化
•緊急パッチの作成
•ロールバック計画の提供

プロセス:

•問題の影響範囲を特定
•最小限の修正を適用
•ロールバック手順を準備
•段階的デプロイ計画

--deep (深い分析モード)

問題を徹底的に調査します。

実施内容:

•スタックトレースの完全解析
•関連コードの調査
•依存関係の追跡
•過去の類似問題の検索

使用場面:

•原因が不明な問題
•断続的に発生する問題
•パフォーマンス問題

--interactive (対話的デバッグモード)

ユーザーとの対話を通じてデバッグを進めます。

実施内容:

•ステップバイステップの調査
•仮説の検証
•部分的な修正の試行
•フィードバックループ

使用場面:

•複雑な問題
•複数の原因が絡む場合
•最適な解決策が不明な場合

一般的な問題パターン

型エラー

問題:

python

TypeError: unsupported operand type(s) for +: 'int' and 'str'

診断:

yaml

原因:
  - 型の不一致を検出
  - 変数の型を追跡
  - 型変換の必要性を特定

解決策:
  - 明示的な型変換
  - 型ヒントの追加
  - バリデーションの実装

修正例:

python

# 修正前
result = count + user_input

# 修正後
result = count + int(user_input)

インポートエラー

問題:

python

ModuleNotFoundError: No module named 'package_name'

診断:

yaml

原因:
  - パッケージの存在確認
  - インストール状態の確認
  - パスの問題を調査

解決策:
  - uv add package_name
  - PYTHONPATH の修正
  - 仮想環境の確認

修正手順:

bash

# パッケージ追加
uv add package_name

# 依存関係同期
uv sync --all-extras

# 確認
make typecheck

パフォーマンス問題

問題:

python

API response time exceeds 1000ms

診断:

yaml

原因:
  - ボトルネックの特定
  - クエリの分析
  - メモリ使用量の確認

解決策:
  - クエリの最適化
  - キャッシングの実装
  - 非同期処理の導入

修正例:

python

# 修正前（N+1問題）
users = User.query.all()
for user in users:
    print(user.profile.name)  # 各ユーザーごとにクエリ

# 修正後（eager loading）
users = User.query.options(joinedload(User.profile)).all()
for user in users:
    print(user.profile.name)  # 1回のクエリで取得

既存ツールとの連携

ツール	用途
`make test`	テストによる問題の再現
`make typecheck`	型関連の問題確認
`make lint`	コード品質問題の検出
`uv run python -m pdb`	Pythonデバッガーの使用
`git bisect`	問題が導入されたコミットの特定

使用例:

bash

# 問題の再現
make test

# 型エラーの詳細確認
make typecheck

# git bisectで問題のコミット特定
git bisect start
git bisect bad HEAD
git bisect good <last_known_good_commit>

使用例

例1: 型エラーのデバッグ

状況: TypeError: 'NoneType' object is not subscriptable が発生

処理:

•スタックトレースを読み取る
•None が返される箇所を特定
•None チェックを追加
•テストで確認

期待される出力:

yaml

診断レポート:
  問題: NoneType エラー
  重大度: HIGH
  影響範囲: ユーザー認証機能

根本原因:
  原因: user が None の場合の処理が不足
  証拠: auth/login.py:45 で user.profile にアクセス
  場所: src/auth/login.py:45

解決策:
  推奨アプローチ: None チェックを追加
  実装手順:
    1. user が None の場合の早期リターンを追加
    2. エラーハンドリングを実装
    3. テストケースを追加

検証方法:
  - test_login_with_invalid_user を追加
  - make test でパスを確認

例2: パフォーマンス問題の調査

状況: API レスポンス時間が 500ms から 2000ms に増加

処理:

•プロファイリングで原因を特定
•N+1 クエリ問題を発見
•eager loading に変更
•パフォーマンステストで検証

期待される出力:

yaml

診断レポート:
  問題: API レスポンス時間の増加
  重大度: MEDIUM
  影響範囲: ユーザー一覧API

根本原因:
  原因: N+1 クエリ問題
  証拠: 100件のユーザーに対し101回のDBクエリ
  場所: api/users.py:23

解決策:
  推奨アプローチ: eager loading の導入
  実装手順:
    1. joinedload を使用してプロファイルを一括取得
    2. クエリ数を測定（101回 → 1回）
    3. レスポンス時間を測定（2000ms → 150ms）

予防策:
  - SQLクエリのログ監視を追加
  - パフォーマンステストをCI/CDに追加

例3: インポートエラーの解決

状況: ModuleNotFoundError: No module named 'requests'

処理:

•依存関係を確認
•パッケージを追加
•依存関係を同期
•型チェックで確認

期待される出力:

yaml

診断レポート:
  問題: インポートエラー
  重大度: CRITICAL
  影響範囲: HTTPクライアント機能

根本原因:
  原因: requests パッケージが未インストール
  証拠: pyproject.toml に依存関係なし
  場所: src/client/http.py:1

解決策:
  推奨アプローチ: パッケージの追加
  実装手順:
    1. uv add requests
    2. uv sync --all-extras
    3. make typecheck で確認

予防策:
  - CI/CD で依存関係の検証を追加

例4: 本番環境の緊急対応

状況: 本番環境で 500 Internal Server Error が発生

処理:

•ログから原因を特定
•最小限の修正を準備
•ロールバック計画を作成
•ステージング環境で検証
•本番環境に段階的デプロイ

期待される出力:

yaml

診断レポート:
  問題: 500 Internal Server Error
  重大度: CRITICAL
  影響範囲: 全ユーザー

根本原因:
  原因: 設定ファイルの環境変数が不足
  証拠: config/settings.py で KeyError
  場所: config/settings.py:15

解決策:
  推奨アプローチ: 環境変数の追加とデフォルト値設定
  実装手順:
    1. 環境変数を .env に追加
    2. デフォルト値を設定
    3. ステージング環境で検証
    4. 本番環境にデプロイ

ロールバック計画:
  - 以前のバージョンにロールバック可能
  - データベースマイグレーション不要

予防策:
  - 設定ファイルのバリデーションを追加
  - デプロイ前チェックリストに環境変数確認を追加

出力フォーマット

診断レポート

yaml

診断レポート:
  問題: [エラーの概要]
  重大度: CRITICAL|HIGH|MEDIUM|LOW
  影響範囲: [影響を受ける機能]

根本原因:
  原因: [特定された原因]
  証拠: [原因を裏付けるデータ]
  場所: [ファイル:行番号]

解決策:
  推奨アプローチ: [最適な解決方法]
  実装手順:
    1. [具体的なステップ]
    2. [次のステップ]

  代替案:
    - [別の解決方法]
    - [回避策]

検証方法:
  - [修正を確認するテスト]
  - [回帰テスト]

予防策:
  - [同様の問題を防ぐ方法]
  - [監視の追加]

ベストプラクティス

DO（推奨）

•証拠の収集: 推測ではなくデータに基づく
•再現性の確保: 問題を確実に再現できる手順を確立
•段階的アプローチ: 大きな変更より小さな修正を積み重ねる
•テストの追加: 修正と同時に回帰テストを作成
•ドキュメント化: 問題と解決策を記録

DON'T（非推奨）

•推測で修正を適用する
•大規模な変更を一度に行う
•テストなしで修正を完了とする
•根本原因を特定せずに症状だけ修正
•本番環境で直接デバッグする

品質基準

このスキルの成果物は以下の品質基準を満たす必要があります：

必須（MUST）

• 根本原因が特定されている
• 解決策が実装されている
• テストで修正を確認している
• 予防策が提案されている
• ドキュメント化されている

推奨（SHOULD）

•エビデンスベースの診断
•複数の解決策を提示
•ロールバック計画を含む
•パフォーマンス測定を含む（パフォーマンス問題の場合）

注意事項

•--fix オプションは慎重に使用してください
•本番環境では必ずバックアップを取得してから実行
•原因が特定できない場合は、より詳細なログを有効化
•パフォーマンス問題は必ず計測してから対処

完了条件

このスキルは以下の条件を満たした場合に完了とする：

• 問題の根本原因が特定されている
• 解決策が実装され、テストでパスしている
• 診断レポートが作成されている
• 予防策が提案されている
• ドキュメントが更新されている

参考資料

•@.claude/rules/evidence-based.md: エビデンスベース開発
•@.claude/rules/testing-strategy.md: テスト戦略
•CLAUDE.md: プロジェクト全体のガイドライン

Troubleshoot - 体系的なデバッグ

目的

いつ使用するか

プロアクティブ使用（自動で使用を検討）

明示的な使用（ユーザー要求）

デバッグプロセス

ステップ 1: 問題の特定

ステップ 2: 原因分析

ステップ 3: 仮説立案

Five Whys (なぜなぜ分析)

二分探索デバッグ

ステップ 4: 解決策の実装

ステップ 5: 検証と予防策

デバッグモード

--fix (自動修正モード)

--prod (本番環境対応モード)

--deep (深い分析モード)

--interactive (対話的デバッグモード)

一般的な問題パターン

型エラー

インポートエラー

パフォーマンス問題

既存ツールとの連携

使用例

例1: 型エラーのデバッグ

例2: パフォーマンス問題の調査

例3: インポートエラーの解決

例4: 本番環境の緊急対応

出力フォーマット

診断レポート

ベストプラクティス

DO（推奨）

DON'T（非推奨）

品質基準

必須（MUST）

推奨（SHOULD）

注意事項

完了条件

関連スキル

参考資料