Communitygithub.com

調査スキル

体系的な調査と根本原因分析を行います。永続的な問題のデバッグ、複雑なシステムの理解、アーキテクチャ上の決定を行う前に使用します。

調査スキル とは?

このスキルは、同一バグが2回以上の修正試行後も解決しない場合や、複雑なシステム障害、アーキテクチャ上の意思決定、または未知のコードベースへの関与が必要な状況において、反復的な推測に頼るのではなく、体系的な調査に切り替えるための原則とワークフローを提供します。主な原則として、「反復の前の調査」、「一次情報の参照」、「ローカルでの再現」、「実際のデータの検査」を掲げ、AWS CLI、ripgrep、jq、curl、Gitなどのツールを使用した実践的なコマンド例を多数含んでいます。また、分散システムにおける実行境界の検証、アーキテクチャ上の選択肢を比較するためのOWLベースの関係性分析フレームワーク、そして具体的なシナリオ(型システムの不一致、本番インシデント、未知のコードベース)ごとの詳細な手順を提供します。このスキルはClaude CodeなどのAIエージェント向けに設計されており、メタループから初期依存ループへの切り替えパターンを通じて、前提条件に疑問を投げかけ、エビデンスに基づいた調査を促進します。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/research-awannaphasch2016-jousef-landing

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

調査スキル は何をしますか?

技術スタック: 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つの正確性のレイヤー:

  1. 構文: コードがコンパイルされる(Python構文が有効)
  2. 意味: コードが主張通りに動作する(ロジックが正しい)
  3. バウンダリー: コードが必要なものに到達できる(ネットワーク、権限)
  4. 設定: エンティティ設定がコード要件と一致する(タイムアウト、メモリ)
  5. 意図: 使用法が設計された目的と一致する(同期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ベースの関係性分析フレームワークを適用

ステップ:

  1. 比較する概念を定義

    • Xとは何か?(定義、場所、目的、例)
    • Yとは何か?(定義、場所、目的、例)
  2. 4つの関係タイプを適用:

    • 部分-全体: 一方が他方の一部か、それとも同等か?
    • 補完: 重複しない懸念事項を処理し、連携するか?
    • 置換: 一方が他方を置き換えられるか?どのような条件下で?
    • 構成: 多層システムに階層化/構成できるか?
  3. 具体的な例で文書化

    • 抽象理論ではなく実際のシナリオを提供
    • トレードオフ分析を含める(得るものと失うもの)
  4. 分析に基づいて推奨を行う

    • 直感ではなく関係性分析に基づく
    • 避けるべきアンチパターンを含める

参照: 包括的な方法論については 関係性分析ガイド を参照

ユースケース例:

  • 「キャッシングにRedisとDynamoDBのどちらを使うべきか?」→ 置換&構成分析を適用
  • 「CDNとアプリケーションキャッシングはどのように関連するか?」→ 補完&構成分析を適用
  • 「マイクロサービス vs モノリス?」→ 部分-全体&トレードオフ分析を適用

一般的な調査シナリオ

シナリオ1: 型システムの不一致

症状: 2回試行後も同じエラー、サイレント失敗

調査手順:

  1. ターゲットシステムのドキュメントを読む

    # PyMySQLドキュメント
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # 探すもの: execute()はどの型を受け入れるか?
    
  2. 最小限の例をテストする

    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文字列成功")
    
  3. 自信を持って修正を適用する

    # これで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: 本番インシデント

症状: ユーザーがエラーを報告、ダッシュボードがスパイクを示す

調査手順:

  1. トリアージ(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
    
  2. 即時緩和(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 にロールバックしました"
    
  3. 事後分析(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: 未知のコードベース

タスク: 見たことのないモジュールに機能を追加

調査手順:

  1. エントリポイントを見つける
    # メイン関数を検索
    rg "def main"
    

[翻訳省略] - 続きは原文参照

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

関連スキル