調査スキル は何をしますか?
技術スタック: AWS CLI, Git, ripgrep, jq, curl, ブラウザ DevTools
出典: CLAUDE.md の調査原則とデバッグパターンから抽出
このスキルを使用するタイミング
以下の場合に調査スキルを使用します:
- ✓ 同じバグが2回以上の修正試行後も持続する場合
- ✓ 未知のコードベースを理解する必要がある場合
- ✓ 本番インシデントを調査している場合
- ✓ アーキテクチャ上の決定を行う場合
- ✓ 複雑なシステムの相互作用をデバッグする場合
- ✓ 新しい技術やライブラリを学習する場合
以下の場合はこのスキルを使用しないでください:
- ✗ 最初の修正試行(まずは明白な解決策を試す)
- ✗ よく理解している問題(そのまま修正する)
- ✗ 時間が重要なインシデント(先に修正し、後から調査する)
クイック調査決定木
問題は何ですか?
├─ この問題を初めて見ましたか?
│ ├─ はい → 明白な修正を試す(反復)
│ └─ いいえ → 2回試行後も同じバグ?→ 調査
│
├─ 本番インシデントですか?
│ ├─ 現在ユーザーに影響?→ まずロールバック/ホットフィックス、後で調査
│ └─ 事後分析?→ 詳細調査
│
├─ コードベースを理解する必要がありますか?
│ ├─ 特定の関数/モジュール?→ コード+テストを読む
│ ├─ システムアーキテクチャ?→ リクエストフローを追跡
│ └─ 歴史的コンテキスト?→ Git blame + コミット履歴
│
├─ 技術的な決定ですか?
│ ├─ 公式ドキュメントを読む(ブログ記事ではない)
│ ├─ 代替案を比較する(トレードオフ)
│ ├─ 実際のユースケースでプロトタイプを作成
│ └─ 決定を文書化する(ADR)
│
└─ API/ライブラリ統合ですか?
├─ 型要件を読む(推測しない)
├─ バージョン互換性を確認
├─ 最小限の例をテスト
└─ 実際のデータで検証
ループパターン: メタループ → 初期依存
エスカレーショントリガー:
/reflectが明らかにする:「3回修正を試みたが、すべて同じエラーで失敗」/traceの出力が試行間で同一- パターン: 再試行ループに行き詰まっている(実行は変わるが、結果は変わらない)
- アクション:
/hypothesisを使用して前提に疑問を投げかける(初期依存に切り替え)
使用するツール:
/observe- システムの動作を観察(何が失敗しているか)/hypothesis- 代替説明を生成(なぜ私が考えているのと違う形で失敗するのか?)/research- 仮説を体系的にテスト/validate- 新しい理解が正しいか確認/reflect- 調査後の学びを統合
これが機能する理由: 調査スキルは自然に初期依存ループに適合します。前提に疑問を投げかけ、単に実行を修正するのではありません。
構造の概要については、思考プロセスアーキテクチャ - フィードバックループ を参照してください。
コア調査原則
原則1: 反復の前に調査
CLAUDE.md より:
「同じバグが2回の修正試行後も持続する場合は、反復を停止し調査を開始します。より多くの推測をデプロイする代わりに、30〜60分間根本原因の理解に投資します。」
これが重要な理由:
- ❌ 反復: 高速フィードバックだが、2回以上の失敗試行後は無駄
- ✅ 調査: 初期コストはかかるが、3回以上の失敗デプロイサイクルを防ぐ
パターン:
試行1: 仮説 + デプロイ(8分)
↓ 失敗
試行2: 別の仮説 + デプロイ(8分)
↓ 失敗
試行3: ❌ 停止 - 別の推測をデプロイしない
調査モードに切り替え:
- 仕様/ドキュメントを読む(15分)
- 実際のデータを検査(10分)
- ローカルで再現(20分)
- 根本原因を特定(15分)
↓ 合計: 60分の調査
試行3(根本原因あり): 修正をデプロイ(8分)
✅ 成功
合計時間: 76分(盲目的反復の120分以上と比較)
原則2: 一次情報を読む
情報品質の階層:
| ソースタイプ | 信頼性 | 使用タイミング |
|---|---|---|
| 公式ドキュメント | 最高 | APIの動作、型要件の最初の参照先 |
| ソースコード | 非常に高い | ドキュメントが不明瞭または不完全な場合 |
| GitHub Issue | 高い | 既知のバグ、エッジケース、回避策 |
| Stack Overflow | 中 | 一般的な問題、ドキュメントを読んだ後 |
| ブログ記事 | 低 | 一般的な概念、実装の詳細ではない |
| ChatGPT/AI | 最低 | 出発点のみ、常に検証が必要 |
例: 型システム統合
# ❌ ダメ: ChatGPTに「PyMySQLはJSONカラムにdictを受け入れますか?」と尋ねる
# ChatGPTは幻覚を見たり、古い答えを返す可能性がある
# ✅ 良い: PyMySQLのドキュメントを読む
open https://pymysql.readthedocs.io/en/latest/
# ✅ 良い: 最小限の例でテストする
python3 << 'EOF'
import pymysql
import json
# テスト: PyMySQLはJSONカラムにdictを受け入れるか?
data = {'key': 'value'}
try:
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
print("✅ Dictが受け入れられた")
except TypeError as e:
print(f"❌ Dictが拒否された: {e}")
# 代わりにJSON文字列を試す
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
print("✅ JSON文字列が受け入れられた")
EOF
原則3: ローカルで再現する
修正をデプロイする前に、ローカルで問題を再現します。
利点:
- ✅ 高速な反復(分単位ではなく秒単位)
- ✅ ブレークポイントでデバッグ可能
- ✅ クラウドコストがかからない
- ✅ エッジケースを簡単にテスト可能
パターン:
# ステップ1: 最小限の失敗ケースを抽出
# Lambda関数全体をテストする代わりに...
# ❌ 悪い例: AWSにデプロイし、ログを確認し、繰り返す
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# CloudWatchログを30秒待つ...
# ✅ 良い例: ローカルで再現する
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher
# Lambdaと全く同じコード
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result) # 即時フィードバック
EOF
原則4: 実際のデータを検査する
データの形状を推測せず、実際の例で検証します。
よくある間違い:
- APIがdictを返すと推測(listを返す可能性あり)
- フィールドが存在すると推測(nullまたは欠落している可能性あり)
- 型を推測(intではなくstringの可能性あり)
パターン:
# ❌ ダメ: 推測する
# 「APIはティッカーのリストを返す」
# ✅ 良い: 検証する
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json
# 構造を検査:
# - list か dict か?
# - どのフィールドが存在するか?
# - それらの型は?
# - ヌル値はあるか?
# - ネストされた構造はあるか?
例: Auroraスキーマ調査
# SSMトンネル経由でAuroraに接続
aws ssm start-session \
--target i-1234567890abcdef0 \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'
# 実際のスキーマを検査(推測しない)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;
-- 実際のデータ型を確認
SELECT
symbol,
report_json,
typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G
-- ヌル値を確認
SELECT COUNT(*) as total,
SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL
調査ワークフロー
詳細なステップバイステップの調査プロセスについては WORKFLOW.md を参照してください。
調査チェックリスト
体系的なデバッグチェックリストについては INVESTIGATION-CHECKLIST.md を参照してください。
バウンダリー検証
使用タイミング: 分散システムの調査時(Lambda, Aurora, S3, SQS, Step Functions)
問題: コードは正しく見えるが、未検証の実行バウンダリーにより本番で失敗する
重要な質問:
- このコードはどこで実行されるか?(Lambda, EC2, ローカル?)
- どのような環境が必要か?(環境変数、ネットワーク、権限?)
- どのような外部システムを呼び出すか?(Auroraスキーマ、S3バケット、API形式?)
- エンティティのプロパティは何か?(Lambdaタイムアウト/メモリ、Aurora接続制限、意図された使用法)
- コントラクトをどのように検証するか?(Terraform設定、SHOW COLUMNS、アクセステスト?)
5つの正確性のレイヤー:
- 構文: コードがコンパイルされる(Python構文が有効)
- 意味: コードが主張通りに動作する(ロジックが正しい)
- バウンダリー: コードが必要なものに到達できる(ネットワーク、権限)
- 設定: エンティティ設定がコード要件と一致する(タイムアウト、メモリ)
- 意図: 使用法が設計された目的と一致する(同期Lambdaは非同期作業用ではない)
適用タイミング:
- 「コードは正しく見えるが動作しない」バグ
- マルチサービスワークフロー(Lambda → Aurora → S3)
- 2回のデプロイ試行失敗後(インフラストラクチャ問題)
- 「コードは正しい」と結論付ける前(実行コンテキストの検証)
検証ワークフロー:
1. 実行バウンダリーを特定(コード → ランタイム、コード → データベース、サービス → サービス)
2. 物理エンティティを特定(どのLambda、どのAurora、どのS3バケット)
3. 設定が要件と一致することを検証(タイムアウト、メモリ、同時実行数)
4. 意図が使用法と一致することを検証(非同期Lambdaは同期API用ではない)
5. エビデンスレイヤーを通じて進む(コード → 設定 → ランタイム → グラウンドトゥルース)
調査ワークフローとの統合:
- フェーズ1(観察): バウンダリー関連の失敗に気付く(タイムアウト、権限拒否、スキーマ不一致)
- フェーズ2(仮説): どのバウンダリーが侵害されている可能性があるかを特定
- フェーズ3(調査): バウンダリー検証チェックリストを体系的に適用
- フェーズ4(検証): グラウンドトゥルースを通じてコントラクトを検証(実際の実行をテスト)
参照: 包括的な検証ワークフローについては 実行バウンダリーチェックリスト を参照
関連原則:
- 原則 #20(実行バウンダリー規律) - CLAUDE.md
- 原則 #2(プログレッシブエビデンス強化) - すべてのレイヤーを通じて検証
- 原則 #15(インフラストラクチャ-アプリケーションコントラクト) - コードとインフラストラクチャを同期
アーキテクチャ調査
使用タイミング: 技術、パターン、アーキテクチャアプローチ間の選択時
問題: 「X vs Y」の比較では、構造化された分析なしに漠然とした「状況による」答えになる
解決策: 体系的な比較のためのOWLベースの関係性分析フレームワークを適用
ステップ:
-
比較する概念を定義
- Xとは何か?(定義、場所、目的、例)
- Yとは何か?(定義、場所、目的、例)
-
4つの関係タイプを適用:
- 部分-全体: 一方が他方の一部か、それとも同等か?
- 補完: 重複しない懸念事項を処理し、連携するか?
- 置換: 一方が他方を置き換えられるか?どのような条件下で?
- 構成: 多層システムに階層化/構成できるか?
-
具体的な例で文書化
- 抽象理論ではなく実際のシナリオを提供
- トレードオフ分析を含める(得るものと失うもの)
-
分析に基づいて推奨を行う
- 直感ではなく関係性分析に基づく
- 避けるべきアンチパターンを含める
参照: 包括的な方法論については 関係性分析ガイド を参照
ユースケース例:
- 「キャッシングにRedisとDynamoDBのどちらを使うべきか?」→ 置換&構成分析を適用
- 「CDNとアプリケーションキャッシングはどのように関連するか?」→ 補完&構成分析を適用
- 「マイクロサービス vs モノリス?」→ 部分-全体&トレードオフ分析を適用
一般的な調査シナリオ
シナリオ1: 型システムの不一致
症状: 2回試行後も同じエラー、サイレント失敗
調査手順:
-
ターゲットシステムのドキュメントを読む
# PyMySQLドキュメント open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # 探すもの: execute()はどの型を受け入れるか? -
最小限の例をテストする
import pymysql import json # 仮説をテスト: Dict vs JSON文字列 data = {'key': 'value'} # テスト1: Dict try: cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,)) except TypeError as e: print(f"Dict失敗: {e}") # テスト2: JSON文字列 cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),)) print("JSON文字列成功") -
自信を持って修正を適用する
# これでjson.dumps()が必要であることがわかった def store_report(symbol: str, report_json: dict): cursor.execute( "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)", (symbol, json.dumps(report_json)) # 文字列に変換 )
シナリオ2: 本番インシデント
症状: ユーザーがエラーを報告、ダッシュボードがスパイクを示す
調査手順:
-
トリアージ(5分未満)
# エラー数を確認 aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $(($(date +%s) - 600))000 \ --filter-pattern "ERROR" \ --query 'length(events)' # 開始時期を確認 aws cloudwatch get-metric-statistics \ --namespace AWS/Lambda \ --metric-name Errors \ --dimensions Name=FunctionName,Value=worker \ --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \ --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ --period 60 \ --statistics Sum -
即時緩和(10分未満)
# 以前のバージョンにロールバック CURRENT=$(aws lambda get-alias --function-name worker --name live \ --query 'FunctionVersion' --output text) PREVIOUS=$((CURRENT - 1)) aws lambda update-alias \ --function-name worker \ --name live \ --function-version $PREVIOUS echo "v$CURRENT から v$PREVIOUS にロールバックしました" -
事後分析(30〜60分)
# エビデンスを収集 mkdir incident-$(date +%Y%m%d-%H%M%S) cd incident-* # エラーログをエクスポート aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $INCIDENT_START \ --end-time $INCIDENT_END \ --filter-pattern "ERROR" > errors.json # メトリクスをエクスポート aws cloudwatch get-metric-statistics ... > metrics.json # デプロイ差分を取得 git diff v$PREVIOUS v$CURRENT > deployment.diff # 分析(根本原因分析) # - 何が変わったか? # - 何が失敗したか? # - なぜ失敗したか? # - どうやって防ぐか?
シナリオ3: 未知のコードベース
タスク: 見たことのないモジュールに機能を追加
調査手順:
- エントリポイントを見つける
# メイン関数を検索 rg "def main"
[翻訳省略] - 続きは原文参照