gh-code-search

GitHub コード検索

インテリジェントなマルチ検索オーケストレーションを通じて、GitHub から実際のコード例を取得します。

前提条件

必須：

• gh CLI のインストールと認証（gh auth login --web）
• Node.js + pnpm

検証：

gh auth status  # Should show authenticated

使用方法

cd plugins/knowledge-work/skills/gh-code-search
pnpm install  # First time only
pnpm search "your query here"

使用するタイミング

ユーザーが次のことを求めた場合に、このスキルを呼び出します：

• 実際の使用例（「X はどのように実装されていますか？」）
• ライブラリの使用パターン（「workflow.dev の使用例を見せてください」）
• 実装方法（「GitHub 検索を行う claude code のスキル」）
• アーキテクチャパターン（「TypeScript のリポジトリパターン」）
• 特定のフレームワークやライブラリのベストプラクティス

複数の検索を細やかに組み合わせる必要がある例：

• 「React フックを探す」→ useState/useEffect（インポート）、function use（定義）、const use =（アロー関数）を検索するクエリが必要です
• 「Express のエラーハンドリングミドルウェア」→ (req, res, next) =>（シグネチャ）、app.use（登録）、function(err,（エラーハンドラー）のクエリが必要です
• 「XState の使い方」→ useMachine、createMachine、interpret（実際の関数名。「state machine」ではありません）を検索するクエリが必要です
• 「TypeScript プロジェクト向け GitHub Actions」→ .yml ワークフローファイル、actions/setup-node、tsc または pnpm build（実際のコマンド）を検索するクエリが必要です

仕組み

役割分担：

スクリプトの役割（ツールの実装）

1. GitHub で認証します（gh CLI トークン）
2. 単一の検索クエリを実行します（Octokit API、ページネーション、テキストマッチ）
3. 品質に基づいて順位付けします（スター数、更新時期、コード構造）
4. 上位 10 件のファイルを並列で取得します
5. 事実データを抽出します（インポート、構文パターン、指標）
6. コード、メタデータ、およびすべてのファイルの GitHub URLを含む整形済み Markdown を返します

スクリプトは単一クエリのツールです。 Claude が複数回の呼び出しをオーケストレーションします。

Claude のオーケストレーションの役割

Claude は複数のフェーズから成るワークフローを実行します：

1. クエリ戦略の生成： 次の点を考慮して、対象を絞った検索クエリを 3～5 件作成します：

   • 言語のコンテキスト（TypeScript と JavaScript の違い）
   • ファイルの種類による違い（React の tsx と ts、設定ファイルと実装ファイル）
   • 詳細度のバリエーション（広い範囲から狭い範囲へ）
   • 関連用語の拡張

2. 逐次的な検索の実行： 中間結果に応じてクエリを調整しながら、ツールを複数回実行します

3. 結果の集約： すべてのコードファイルを統合し、リポジトリとパスで重複を除外して、GitHub URL を保持します

4. パターンの分析： 共通するインポート、アーキテクチャスタイル、実装パターンを抽出します

5. 包括的な要約： トレードオフ、推奨事項、重要なコードの要点、および意味のあるすべてのファイルの GitHub URLを含めて、調査結果をまとめます

---

Claude のオーケストレーションワークフロー

ステップ 1：リクエストを分析してクエリを生成する（必須）

ユーザーのリクエストを分析して、次の項目を判断します。

• 主な言語／フレームワーク（TypeScript、Python、Go など）
• 探す具体的なパターン（フック、ミドルウェア、設定、アクション）
• 必要なファイル形式の違い（tsx と ts、yaml と json など）

ニュアンスを考慮し、対象を絞ったクエリを 3〜5 件生成します。

例 1：「React フックを探す」

• クエリ 1：useState useEffect language:typescript extension:tsx（インポート文やコンポーネント内のフックの使用箇所に一致）
• クエリ 2：function use language:typescript extension:ts（function useFetch() のようなフック定義に一致）
• クエリ 3：const use = language:typescript（const useAuth = () => のようなアロー関数形式のフックに一致）

例 2：「Express のエラー処理」

• クエリ 1：(req, res, next) => language:javascript（ミドルウェア関数のシグネチャに一致）
• クエリ 2：app.use express（Express ミドルウェアの登録箇所に一致）
• クエリ 3：function(err, req, res, next) language:javascript（4 つのパラメーターを持つエラーハンドラーのシグネチャに一致）

例 3：「React での XState ステートマシン」

• クエリ 1：useMachine language:typescript extension:tsx（const [state, send] = useMachine(machine) のような React フックの使用箇所に一致）
• クエリ 2：createMachine language:typescript（ステートマシンの定義やインポートに一致）
• クエリ 3：interpret xstate language:typescript（const service = interpret(machine) のようなサービスの作成箇所に一致）

各クエリの根拠：

• 実際のコードパターン（関数名、インポート文、シグネチャ）に一致させます
• 人間にとって分かりやすい検索語やドキュメント内の表現ではなく、コードパターンを使います
• ファイル拡張子を変えることで、異なるユースケースを網羅します（コンポーネントには tsx、ユーティリティには ts）
• 具体的な関数名や変数名を使い、実際の実装を見つけます
• シグネチャパターンで、アロー関数や関数宣言など、一般的なコード構造に一致させます
• 言語／拡張子のフィルターを使い、関係のない言語の検索結果を除外します

チェックポイント： 次へ進む前に、クエリが 3〜5 件生成されていることを確認します

---

ステップ 2：検索を順番に実行する

各クエリを順番に実行します。

cd plugins/knowledge-work/skills/gh-code-search
pnpm search "query text here"

各検索の後に：

1. 結果数を記録する — 多すぎますか？少なすぎますか？
2. 品質を示す指標を確認する — スター数、新しさ、コード構造のスコア
3. パターンを特定する — 結果は特定の手法に収束していますか？
4. 必要に応じて次のクエリを調整する：
   • 結果が多すぎる → フィルターを追加して範囲を絞ります
   • 結果が少なすぎる → 制限の厳しいフィルターを削除して範囲を広げます
   • 有力なパターンが見つかった → 類似のバリエーションを検索します

成功したクエリを記録する — どの検索方法が効果的だったかを、要約用に記録します

早期終了： 最初の 2〜3 件のクエリで高品質な結果が 30 件以上得られた場合、残りのクエリは省略できます

---

ステップ 3：結果を集約する

すべての検索結果からコードファイルをまとめます。

1. 各検索結果から GitHub URL とともにファイルを収集する
2. repository.full_name + file_path を使って重複を除外する
   • 重複がある場合は、スコアが最も高いバージョンを残します
   • 同じファイルがどのクエリで見つかったかを記録します（関連性の高さを示します）
3. 多様性を保つ — 複数のリポジトリが含まれるようにします（1 つのリポジトリから 10 ファイルを選ぶことは避けます）
4. 出典を記録する — 各ファイルを見つけたクエリを記録します（分析に役立ちます）
5. GitHub URL を保持する — 要約に含めるため、すべてのファイルの完全な GitHub URL を維持します

結果： GitHub URL 付きの、重複のない高品質なコードファイル 15〜30 件の統合リスト

---

Step 4: パターンを分析する

すべてのコードファイルから事実に基づくパターンを抽出します：

インポートの分析：

• よく使われるインポートを一覧表示します（ライブラリごとにグループ化）
• 標準ライブラリとサードパーティの依存関係を特定します
• バージョン固有のパターンを記録します（例：React 18 のフック）

アーキテクチャのパターン：

• 関数ベースとクラスベースの実装
• カスタムフックとインラインロジック
• ミドルウェアチェーンと単一ハンドラー
• 設定のパターン（環境変数、設定ファイル、インライン）

コード構造：

• 関数のシグネチャ（パラメーター、戻り値の型）
• エラー処理の方法（try/catch、エラーミドルウェア、Result 型）
• テストのパターン（単体テストと統合テスト、モックの方法）
• ドキュメントのスタイル（JSDoc、インラインコメント、README）

言語の使用状況：

• TypeScript と JavaScript の割合
• Strict モードの使用状況
• 型定義のパターン

論評は加えないでください。意見ではなく、事実を抽出してください。分析はステップ 5 で行います。

---

Step 5: 包括的な要約を作成する

出力形式（構造を厳密に維持）：

# GitHub Code Search: [User Query Topic]

## Search Strategy Executed

Ran [N] targeted queries:
1. `query text` - [brief rationale] → [X results]
2. `query text` - [brief rationale] → [Y results]
3. ...

**Total unique files analyzed:** [N]

---

## Pattern Analysis

### Common Imports
- `library-name` - Used in [N/total] files
- `another-lib` - Used in [M/total] files

### Architectural Styles
- **Functional Programming** - [N] files use pure functions, immutable patterns
- **Object-Oriented** - [M] files use classes, inheritance
- **Hybrid** - [K] files mix both approaches

### Implementation Patterns
- **Pattern 1 Name**: [Description with prevalence]
- **Pattern 2 Name**: [Description with prevalence]

---

## Approaches Found

### Approach 1: [Name]
**Repos:** [repo1], [repo2]
**Characteristics:**
- [Key trait 1]
- [Key trait 2]

**Example:** [repo/file_path:line_number](github_url)
```language
[relevant code snippet - NOT just first 40 lines]

アプローチ 2：[名前]

[同様の構成]

---

トレードオフ

アプローチ	メリット	デメリット	最適な用途
アプローチ 1	[メリット]	[デメリット]	[ユースケース]
アプローチ 2	[メリット]	[デメリット]	[ユースケース]

---

推奨事項

ユースケース（ユーザーのコンテキストから推測）に応じて：

1. 第一の推奨事項： [アプローチ名]

   • 理由： [分析に基づく根拠]
   • 実装： [大まかな手順]
   • 参考資料： repo/file_path:line_number

2. 代替案： [別のアプローチ]

   • 適するケース： [こちらが適しているシナリオ]
   • 参考資料： repo/file_path:line_number

---

主なコードセクション

[概念 1]

ソース： repo/file_path:line_range

[Specific relevant code - imports, key function, not arbitrary truncation]

重要な理由： [簡潔な説明]

[概念 2]

ソース： repo/file_path:line_range

[Specific relevant code]

重要な理由： [簡潔な説明]

---

分析したすべての GitHub ファイル

重要： すべての検索で見つかった、意味のあるファイルすべての GitHub URL を含めてください。

分析したファイルをすべて（15～30 件）、リポジトリごとにグループ化して一覧表示します：

[repo-owner/repo-name] ([stars]⭐)

• file_path - [言語] - [このファイルが示す内容の簡単な説明]
• file_path - [言語] - [簡単な説明]

[repo-owner/repo-name2] ([stars]⭐)

• file_path - [言語] - [簡単な説明]

形式： 該当する場合は行番号を含む、GitHub の blob への直接 URL を使用します（例：https://github.com/owner/repo/blob/main/path/file.ts#L10-L50）

**Summary characteristics:**
- **Factual** - Based on extracted data, not assumptions
- **Actionable** - Clear recommendations with reasoning
- **Contextualized** - References specific code locations with line numbers
- **Balanced** - Shows trade-offs, not just "best practice"
- **Comprehensive** - Covers patterns, approaches, trade-offs, recommendations
- **Accessible** - GitHub URLs for ALL meaningful files so users can explore full source code

---

### Step 6: Save Results to File

**After generating comprehensive summary, persist for future reference:**

1. **Generate timestamp:**
   - Invoke `timestamp` skill to get deterministic YYYYMMDDHHMMSS format
   - Example: `20250110143052`

2. **Sanitize query for filename:**
   - Convert user's original query to kebab-case slug
   - Rules: lowercase, spaces → hyphens, remove special chars, max 50 chars
   - Example: "React hooks useState" → "react-hooks-usestate"

3. **Construct file path:**
   - Directory: `docs/research/github/`
   - Format: `<timestamp>-<sanitized-query>.md`
   - Full path: `docs/research/github/20250110143052-react-hooks-usestate.md`

4. **Save using Write tool:**
   - Content: Full comprehensive summary from Step 5
   - Ensures persistence across sessions
   - User can reference past research

5. **Log saved location:**
   - Inform user where file was saved
   - Example: "Research saved to docs/research/github/20250110143052-react-hooks-usestate.md"

**Why save:**
- Comprehensive summaries represent significant analysis work (30-150s of API calls)
- Users may want to reference patterns/trade-offs later
- Builds searchable knowledge base of GitHub research
- Avoids re-running expensive queries for same topics

---

## Error Handling

**Common issues:**

- **Auth errors:** Prompt user to run `gh auth login --web`
- **Rate limits:** Show remaining quota, reset time. If hit during multi-search, stop gracefully with partial results
- **Network failures:** Continue with partial results, note which queries failed
- **No results for query:** Note in summary, adjust subsequent queries to be broader
- **All queries return same files:** Note low diversity, recommend broader initial queries

**Graceful degradation:** Partial results are acceptable. Complete summary based on available data.

---

## Limitations

- GitHub API rate limit: 5,000 req/hr authenticated (multi-search uses more quota)
- Each tool invocation fetches top 10 results only
- Skips files >100KB
- Sequential execution takes longer than single query (10-30s per query)
- Provides factual data, not conclusions (Claude interprets patterns)
- Deduplication assumes exact path matches (renamed files treated as unique)

---

## Typical Execution Time

**Per query:** 10-30 seconds depending on:
- Number of results (100 max)
- File sizes
- Network latency
- API rate limits

**Full workflow (3-5 queries):** 30-150 seconds

**Optimization:** If first queries yield sufficient results, skip remaining queries

---

## Integration Notes

**Example: User asks "find Claude Code skills doing github search"**

```javascript
// 1. Claude analyzes: Skills use SKILL.md with frontmatter, likely in .claude/skills/
// 2. Claude generates queries:
//    - "filename:SKILL.md github search" (matches SKILL.md files with "github search" text)
//    - "octokit.rest.search language:typescript" (matches actual Octokit API usage)
//    - "gh api language:typescript path:skills" (matches gh CLI usage in skills)
// 3. Claude executes sequentially:
cd plugins/knowledge-work/skills/gh-code-search
pnpm search "filename:SKILL.md github search"
// [analyze results]
pnpm search "octokit.rest.search language:typescript"
// [analyze results]
pnpm search "gh api language:typescript path:skills"
// 4. Claude aggregates, deduplicates, analyzes patterns
// 5. Claude generates comprehensive summary with trade-offs and recommendations

---

テスト

多様なクエリでワークフローを検証します：

• シンプル：「React hooks」（3 件以上のクエリを生成し、結果を統合すること）
• 複雑：「GitHub Actions TypeScript project setup」（設定と実装のクエリが必要）
• あいまい：「state management」（Redux、Zustand、XState、Context の各クエリを生成すること）

品質を確認します：

• 重複排除が機能する（要約内に重複したファイルがない）
• 多様なリポジトリが含まれる（1 つのリポジトリだけに偏っていない）
• 要約にトレードオフと推奨事項が含まれる
• コードスニペットが関連性のある内容になっている（恣意的に切り取られていない）