github-research

GitHub リサーチスキル

トリガー

ユーザーが次のことを求めたときに、このスキルを有効にします：

• 「[topic] のリポジトリを探して」「[topic] について GitHub で調査して」
• 「[topic] のオープンソースコードを分析して」
• 「[paper/technique] の実装を探して」
• 「[algorithm] を実装しているリポジトリはどれ？」
• /github-research <deep-research-output-dir> スラッシュコマンドを使用する

概要

このスキルは、研究テーマに関連する GitHub リポジトリを体系的に見つけ、評価し、詳細に分析します。deep-research の出力（論文データベース、フェーズレポート、コード参照）を読み込み、オープンソースコードを再利用するための実用的な統合ブループリントを作成します。

インストール先：~/.claude/skills/github-research/ — スクリプト、リファレンス、このスキルの定義。 出力先：現在の作業ディレクトリを基準とする ./github-research-output/{slug}/。 入力：deep-research の出力ディレクトリ（paper_db.jsonl、フェーズレポート、code_repos.md などを含む）

6 フェーズのパイプライン

Phase 1: Intake     → Extract refs, URLs, keywords from deep-research output
Phase 2: Discovery  → Multi-source broad GitHub search (50-200 repos)
Phase 3: Filtering  → Score & rank → select top 15-30 repos
Phase 4: Deep Dive  → Clone & deeply analyze top 8-15 repos (code reading)
Phase 5: Analysis   → Per-repo reports + cross-repo comparison
Phase 6: Blueprint  → Integration/reuse plan for research topic

出力ディレクトリの構成

github-research-output/{slug}/
├── repo_db.jsonl                     # Master repo database
├── phase1_intake/
│   ├── extracted_refs.jsonl          # URLs, keywords, paper-repo links
│   └── intake_summary.md
├── phase2_discovery/
│   ├── search_results/               # Raw JSONL from each search
│   └── discovery_log.md
├── phase3_filtering/
│   ├── ranked_repos.jsonl            # Scored & ranked subset
│   └── filtering_report.md
├── phase4_deep_dive/
│   ├── repos/                        # Cloned repos (shallow)
│   ├── analyses/                     # Per-repo analysis .md files
│   └── deep_dive_summary.md
├── phase5_analysis/
│   ├── comparison_matrix.md          # Cross-repo comparison
│   ├── technique_map.md              # Paper concept → code mapping
│   └── analysis_report.md
└── phase6_blueprint/
    ├── integration_plan.md           # How to combine repos
    ├── reuse_catalog.md              # Reusable components catalog
    ├── final_report.md               # Complete compiled report
    └── blueprint_summary.md

スクリプトのリファレンス

すべてのスクリプトは Python 3 で、標準ライブラリのみを使用し、~/.claude/skills/github-research/scripts/ にあります。

スクリプト	目的	主なフラグ
extract_research_refs.py	deep-research の出力から GitHub URL、論文参照、キーワードを解析します	--research-dir、--output
search_github.py	gh api 経由で GitHub リポジトリを検索します	--query、--language、--min-stars、--sort、--max-results、--topic、--output
search_github_code.py	実装を求めて GitHub のコードを検索します	--query、--language、--filename、--max-results、--output
search_paperswithcode.py	論文からリポジトリへの対応付けを Papers With Code で検索します	--paper-title、--arxiv-id、--query、--output
repo_db.py	JSONL リポジトリデータベースを管理します	サブコマンド：merge、filter、score、search、tag、stats、export、rank
repo_metadata.py	gh api 経由で詳細なメタデータを取得します	--repos、--input、--output、--delay
clone_repo.py	分析用にリポジトリをシャロークローンします	--repo、--output-dir、--depth、--branch
analyze_repo_structure.py	ファイルツリー、主要ファイル、LOC 統計をマッピングします	--repo-dir、--output
extract_dependencies.py	依存関係ファイルを抽出して解析します	--repo-dir、--output
find_implementations.py	クローンしたリポジトリ内で特定のコードパターンを検索します	--repo-dir、--patterns、--output
repo_readme_fetch.py	クローンせずに README を取得します	--repos、--input、--output、--max-chars
compare_repos.py	リポジトリ間の比較マトリックスを生成します	--input、--output
compile_github_report.py	すべてのフェーズの結果をまとめて最終レポートを作成します	--topic-dir

---

フェーズ 1：入力

目標：deep-research の出力から、関連する参照、URL、キーワードをすべて抽出します。

手順

1. 出力ディレクトリの構成を作成します：

   SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
   mkdir -p github-research-output/$SLUG/{phase1_intake,phase2_discovery/search_results,phase3_filtering,phase4_deep_dive/{repos,analyses},phase5_analysis,phase6_blueprint}
   

2. deep-research の出力から参照を抽出します：

   python ~/.claude/skills/github-research/scripts/extract_research_refs.py \
     --research-dir <deep-research-output-dir> \
     --output github-research-output/$SLUG/phase1_intake/extracted_refs.jsonl
   

3. 抽出した参照を確認します：生成された JSONL を読みます。次の項目を確認します：

   • レポート内で直接見つかった GitHub URL
   • 論文タイトルと arxiv ID（Papers With Code で検索するため）
   • 研究キーワードとテーマ（GitHub 検索クエリに使用）

4. 入力の概要を記述します：次の内容を含めて phase1_intake/intake_summary.md を作成します：

   • 直接見つかった GitHub URL の数
   • コードへのリンク候補がある論文の数
   • 抽出した主な研究テーマ
   • フェーズ 2 で予定している検索クエリ

チェックポイント

• extracted_refs.jsonl にエントリがある
• intake_summary.md が作成されている
• 検索戦略が文書化されている

---

フェーズ 2：探索

目標：複数の情報源から幅広く検索し、候補となるリポジトリを 50～200 件見つけます。

手順

1. 直接の URL で検索する：フェーズ 1 の GitHub URL があれば、メタデータを取得します：

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --repos owner1/name1 owner2/name2 ... \
     --output github-research-output/$SLUG/phase2_discovery/search_results/direct_urls.jsonl
   

2. Papers With Code を検索する：arxiv ID がある論文ごとに検索します：

   python ~/.claude/skills/github-research/scripts/search_paperswithcode.py \
     --arxiv-id 2401.12345 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/pwc_2401.12345.jsonl
   

3. キーワードで GitHub を検索する（研究テーマに基づいて 3～8 個のクエリを使用します）：

   python ~/.claude/skills/github-research/scripts/search_github.py \
     --query "multi-agent LLM coordination" \
     --min-stars 10 --sort stars --max-results 50 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/gh_query1.jsonl
   

4. GitHub のコードを検索する（特定の実装を対象とします）：

   python ~/.claude/skills/github-research/scripts/search_github_code.py \
     --query "class MultiAgentOrchestrator" \
     --language python --max-results 30 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/code_query1.jsonl
   

5. 説明がないリポジトリの README を取得する：

   python ~/.claude/skills/github-research/scripts/repo_readme_fetch.py \
     --input <repos.jsonl> \
     --output github-research-output/$SLUG/phase2_discovery/search_results/readmes.jsonl
   

6. すべての結果を統合データベースにまとめる：

   python ~/.claude/skills/github-research/scripts/repo_db.py merge \
     --inputs github-research-output/$SLUG/phase2_discovery/search_results/*.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   

7. 発見ログを作成する：使用した検索クエリ、ソースごとの結果、見つかったユニークなリポジトリの合計数を記載した phase2_discovery/discovery_log.md を作成します。

レート制限

• GitHub 検索 API：30 リクエスト/分（認証済み）
• Papers With Code API：厳密な制限はありませんが、節度を持って利用してください（1 リクエスト/秒）
• 必要に応じて、バッチ処理に --delay 1.0 を追加します

チェックポイント

• repo_db.jsonl に 50～200 件のリポジトリが登録されている
• 検索の詳細を記載した discovery_log.md がある

---

フェーズ 3：フィルタリング

目標：リポジトリをスコアリングして順位付けし、詳細分析の対象として上位 15～30 件を選定します。

手順

1. すべてのリポジトリのメタデータを拡充する：

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl \
     --delay 0.5
   

2. リポジトリをスコアリングする（品質スコアと活動スコア）：

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   

3. LLM による関連性スコアリング：品質スコア順の上位約 50 件のリポジトリに目を通し、以下の基準に基づいて relevance_score（0.0～1.0）を割り当てます：

   • 研究トピックとの直接的な関連性
   • 実装の完全性
   • コード品質を示すシグナル（README、説明）
   • 関連性スコアを更新します：

   python ~/.claude/skills/github-research/scripts/repo_db.py tag \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --ids owner/name --tags "relevance:0.85"
   

4. 複合スコアを計算して順位付けする：

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   python ~/.claude/skills/github-research/scripts/repo_db.py rank \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --by composite_score
   

5. 上位のリポジトリを選定する：上位 15～30 件に絞り込みます：

   python ~/.claude/skills/github-research/scripts/repo_db.py filter \
     --input github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --max-repos 30 --not-archived
   

6. フィルタリングレポートを作成する：phase3_filtering/filtering_report.md を作成します：

   • フィルタリング前後の統計
   • スコアの分布
   • スコアと選定理由を記載した上位 30 件のリポジトリ

スコアリング式

activity_score = sigmoid((days_since_push < 90) * 0.4 + has_recent_commits * 0.3 + open_issues_ratio * 0.3)
quality_score  = normalize(log(stars+1) * 0.3 + log(forks+1) * 0.2 + has_license * 0.15 + has_readme * 0.15 + not_archived * 0.2)
composite_score = relevance * 0.4 + quality * 0.35 + activity * 0.25

チェックポイント

• 15～30 件のリポジトリを含む ranked_repos.jsonl
• スコアリングの詳細を記載した filtering_report.md

---

フェーズ 4：詳細分析

目標：上位 8～15 件のリポジトリをクローンし、詳細に分析します。

手順

1. 詳細分析の対象リポジトリを選定する：順位付きリストから上位 8～15 件を選びます。

2. 各リポジトリをクローンする（浅いクローン）：

   python ~/.claude/skills/github-research/scripts/clone_repo.py \
     --repo owner/name \
     --output-dir github-research-output/$SLUG/phase4_deep_dive/repos/
   

3. クローンした各リポジトリの構造を分析する：

   python ~/.claude/skills/github-research/scripts/analyze_repo_structure.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_structure.json
   

4. 依存関係を抽出する：

   python ~/.claude/skills/github-research/scripts/extract_dependencies.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_deps.json
   

5. 実装を探す：研究に関連する主要なアルゴリズムや概念を検索します：

   python ~/.claude/skills/github-research/scripts/find_implementations.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --patterns "class Transformer" "def forward" "attention" \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_impls.jsonl
   

6. コードを詳しく読む：各リポジトリについて、構造分析で特定した主要なソースファイルを読みます。リポジトリごとの分析結果を phase4_deep_dive/analyses/{name}_analysis.md に記載します：

   • アーキテクチャの概要
   • 実装されている主要なアルゴリズム
   • コード品質の評価
   • API／インターフェース設計
   • 依存関係と要件
   • 強みと制約
   • 再利用性の評価（コンポーネントをどれだけ簡単に抽出できるか）

7. 詳細分析の概要を作成する：phase4_deep_dive/deep_dive_summary.md

重要：実際にコードを読む

README を要約するだけではいけません。必ず以下を行ってください：

• 主要なソースファイル（エントリーポイント、コアモジュール）を読む
• 実際の実装方法を理解する
• 研究の概念を実装する具体的な関数／クラスを特定する
• コードのパターン、設計上の判断、トレードオフを記録する

チェックポイント

• repos/ にリポジトリがクローンされている
• リポジトリごとの分析ファイルが analyses/ にある
• deep_dive_summary.md が作成されている

---

フェーズ 5：分析

目標：リポジトリを横断して比較し、手法とコードの対応関係をマッピングします。

手順

1. 比較マトリックスを生成：

   python ~/.claude/skills/github-research/scripts/compare_repos.py \
     --input github-research-output/$SLUG/phase4_deep_dive/analyses/ \
     --output github-research-output/$SLUG/phase5_analysis/comparison.json
   

2. 比較マトリックスを作成：phase5_analysis/comparison_matrix.md を作成します。

   • 言語、LOC、スター数、フレームワーク、ライセンス、テストの各項目でリポジトリを比較する表
   • 依存関係の重複分析
   • リポジトリごとの強みと弱み

3. 手法マップを作成：phase5_analysis/technique_map.md を作成します。

   • 各論文の概念／研究手法を、該当するリポジトリ、ファイル、関数に対応付ける
   • 実装が見つからない手法（ギャップ）を特定する
   • 同じ概念に対する代替実装を記録する

4. 分析レポートを作成：phase5_analysis/analysis_report.md を作成します。

   • 調査結果のエグゼクティブサマリー
   • コード分析から得られた重要な知見
   • 用途別に推奨するリポジトリ

チェックポイント

• リポジトリ比較表を含む comparison_matrix.md
• 概念をコードに対応付けた technique_map.md
• 調査結果をまとめた analysis_report.md

---

フェーズ 6：設計図

目標：実行可能な統合・再利用計画を作成します。

手順

1. 統合計画を作成：phase6_blueprint/integration_plan.md を作成します。

   • リポジトリを組み合わせるための推奨アーキテクチャ
   • 段階的な統合方法
   • 依存関係の解決方針
   • 想定される競合とその解決方法

2. 再利用カタログを作成：phase6_blueprint/reuse_catalog.md を作成します。

   • 再利用可能なコンポーネントごとに、ソースリポジトリ、ファイルパス、関数／クラス、機能、抽出方法を記載する
   • ライセンス互換性マトリックス
   • 統合にかかる労力の見積もり（簡単／中程度／難しい）

3. 最終レポートをまとめる：

   python ~/.claude/skills/github-research/scripts/compile_github_report.py \
     --topic-dir github-research-output/$SLUG/
   

4. 設計図の概要を作成：phase6_blueprint/blueprint_summary.md を作成します。

   • 1ページのエグゼクティブサマリー
   • 上位 5 件のリポジトリとその選定理由
   • 推奨する次のステップ

チェックポイント

• integration_plan.md が完成している
• コンポーネントカタログを含む reuse_catalog.md
• final_report.md が完成している
• エグゼクティブサマリーとしての blueprint_summary.md

---

品質に関する規約

1. リポジトリは合成スコアで順位付けします：relevance × 0.4 + quality × 0.35 + activity × 0.25
2. 詳細な調査では、README だけでなく実際のコードを読む必要があります
3. 統合設計図では、論文の概念を具体的なコードファイル／関数に対応付ける必要があります
4. 段階的に保存します：各フェーズの成果物は、作成したらすぐにディスクに書き込みます
5. チェックポイントからの再開：出力済みのファイルを確認すれば、どのフェーズからでも再開できます
6. すべてのスクリプトは標準ライブラリのみを使用する Python です — pip によるインストールは不要です
7. GitHub API へのアクセスには gh CLI が必要です（認証済みである必要があります）
8. すべての検索を通じて、repo_id（owner/name）で重複を除外します
9. レート制限に注意します：GitHub 検索 API の制限（30 req/min）を守ります

エラー処理

• gh がインストールされていない場合：ユーザーに警告し、インストール手順を提示します
• リポジトリがアーカイブ済み／削除済みの場合：適切にスキップし、ログに記録します
• クローンに失敗した場合：スキップしてログに記録し、残りのリポジトリの処理を続けます
• Papers With Code API が停止している場合：スキップし、GitHub 検索のみを利用します
• 作業が失われないよう、進捗は常に部分的でもディスクに書き込みます

参考資料

• 詳細なフェーズ実行ガイダンスについては references/phase-guide.md を参照してください
• 詳細調査スキル：~/.claude/skills/deep-research/SKILL.md
• 論文データベースのパターン：~/.claude/skills/deep-research/scripts/paper_db.py