Communitygithub.com

調査スキル

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

調査スキル とは?

このスキルは、継続的な問題のデバッグや複雑なシステムの理解において、推測による反復作業ではなく体系的な調査を促進します。同じバグが2回の修正試行後も解決しない場合、30〜60分の調査に切り替えることで、根本原因を特定し、無駄なデプロイサイクルを防止します。主な原則として、一次情報源(公式ドキュメント、ソースコード)の参照、ローカルでの再現、実データの検証、実行境界の確認などを重視しています。AWS CLI、Git、ripgrep、jq、curl、ブラウザDevToolsなどのツールを活用し、調査プロセスを効率化します。また、分散システムの境界検証やアーキテクチャ比較のためのOWLベースの関係分析フレームワークも提供しており、調査と分析を構造化するための実践的なワークフローを含んでいます。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/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 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つの層:

  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. エントリポイントを見つける
    # main関数を検索
    rg "def main"
    

...

[翻訳対象外]

Individual skills in this repo

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

majiayu000/claude-skill-registry

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

関連スキル