調査スキル は何をしますか?
テクノロジースタック: 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 Issues | 高い | 既知のバグ、エッジケース、回避策 |
| 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: ローカルで再現する
修正をデプロイする前に、ローカルで問題を再現します。
利点:
- ✅ 高速な反復(秒 vs 分)
- ✅ ブレークポイントでデバッグ可能
- ✅ クラウド費用がかからない
- ✅ エッジケースを簡単にテスト可能
パターン:
# ステップ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はtickerのリストを返す」
# ✅ する: 検証
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json
# 構造を検査:
# - listかdictか?
# - どのフィールドが存在するか?
# - それらの型は何か?
# - null値はあるか?
# - ネスト構造はあるか?
例: 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
-- null値を確認
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: 未知のコードベース
タスク: 見たことのないモジュールに機能を追加する
調査手順:
- エントリポイントを見つける
# main関数を検索 rg "def main"
...
[翻訳対象外]