/search-first — コードを書く前に調査する
「既存の解決策を探してから実装する」ワークフローを体系化します。
トリガー
以下の場合にこのスキルを使用します:
- 既存の解決策が存在しそうな新機能を開始する場合
- 依存関係や統合を追加する場合
- ユーザーが「X機能を追加して」と依頼し、コードを書き始めようとしている場合
- 新しいユーティリティ、ヘルパー、抽象化を作成する前
ワークフロー
┌─────────────────────────────────────────────┐
│ 0. ツール可用性事前チェック │
│ 検索チャネルが利用可能かを確認 │
│ 利用不可なら正直にスキップを報告 │
├─────────────────────────────────────────────┤
│ 1. ニーズ分析 │
│ 必要な機能を定義 │
│ 言語/フレームワークの制約を特定 │
├─────────────────────────────────────────────┤
│ 2. 並列検索 (リサーチャーエージェント) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ スキル │ │ Web │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. 評価 │
│ 候補をスコアリング (機能性、メンテナンス、│
│ コミュニティ、ドキュメント、ライセンス、 │
│ 依存関係) │
├─────────────────────────────────────────────┤
│ 4. 判断 │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ そのまま│ │ 拡張/ │ │ カスタム│ │
│ │ 採用 │ │ ラップ │ │ 構築 │ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. 実装 │
│ パッケージのインストール / MCPの設定 / │
│ 最小限のカスタムコードの記述 │
└─────────────────────────────────────────────┘
判断マトリクス
| シグナル | アクション |
|---|---|
| 完全一致、メンテナンス良好、MIT/Apacheライセンス | 採用 — そのままインストールして使用 |
| 部分一致、良い基盤 | 拡張 — インストール + 薄いラッパーを記述 |
| 複数の弱い一致 | 構成 — 2～3つの小さなパッケージを組み合わせ |
| 適切なものが見つからない | 構築 — 調査結果を参考にカスタムコードを記述 |
使い方
ステップ 0: ツール可用性事前チェック
これはエージェント向けのガイダンスであり、実行可能なセットアップスクリプトではありません。現在のタスクとプロジェクトに関連するチャネルのみをチェックします。
| チャネル | 確認方法 | 見つからない場合 |
|---|---|---|
| リポジトリ検索 | rg --files と対象を絞った rg クエリ | 目に見えるファイルのみを調査したと報告 |
| パッケージレジストリ | npm --version、python -m pip --version、またはプロジェクトのパッケージマネージャー | Web/ドキュメント検索を使用し、レジストリのカバレッジは主張しない |
| GitHub CLI | gh auth status | 公開Webまたはローカルのgit履歴のみを使用 |
| MCP/ドキュメントツール | 利用可能なツールリストまたはローカルのMCP設定 | 公式ドキュメント/Web検索にフォールバック |
| スキルディレクトリ | 該当する場合 ls ~/.claude/skills ~/.codex/skills | ローカルスキルカタログが利用不可だったと報告 |
クイックモード（インライン）
ユーティリティを作成したり機能を追加する前に、頭の中で以下を実行します:
- これはリポジトリに既に存在するか？ → まず関連モジュール/テストを
rgで検索 - これは一般的な問題か？ → npm/PyPI を検索
- これに対応するMCPはあるか？ →
~/.claude/settings.jsonを確認して検索 - これに対応するスキルはあるか？ →
~/.claude/skills/を確認 - GitHubの実装/テンプレートはあるか？ → 新しいコードを書く前に、メンテナンスされているOSSをGitHubコード検索で確認
フルモード（エージェント）
重要な機能の場合は、リサーチャーエージェントを起動します:
Agent(subagent_type="general-purpose", prompt="
[説明] に対する既存ツールを調査:
言語/フレームワーク: [言語]
制約: [任意]
検索対象: npm/PyPI、MCPサーバー、Claude Codeスキル、GitHub
戻り値: 推奨事項付きの構造化比較
")
古いClaude Codeのドキュメントではこれを Task(...) と呼んでいる場合があります。現在のハーネスで公開されているエージェント/サブエージェントツール名を使用してください。
カテゴリ別検索ショートカット
開発ツール
- リンティング →
eslint、ruff、textlint、markdownlint - フォーマット →
prettier、black、gofmt - テスト →
jest、pytest、go test - プリコミット →
husky、lint-staged、pre-commit
AI/LLM統合
- Claude SDK → 最新ドキュメントはContext7を確認
- プロンプト管理 → MCPサーバーを確認
- ドキュメント処理 →
unstructured、pdfplumber、mammoth
データとAPI
- HTTPクライアント →
httpx(Python)、ky/undici(Node) - バリデーション →
zod(TS)、pydantic(Python) - データベース → 最初にMCPサーバーを確認
コンテンツと公開
- Markdown処理 →
remark、unified、markdown-it - 画像最適化 →
sharp、imagemin
統合ポイント
プランナーエージェントとの連携
プランナーはフェーズ1（アーキテクチャレビュー）の前にリサーチャーを起動します:
- リサーチャーが利用可能なツールを特定
- プランナーがそれらを実装計画に組み込む
- 計画における「車輪の再発明」を回避
アーキテクトエージェントとの連携
アーキテクトは以下についてリサーチャーに相談します:
- 技術スタックの決定
- 統合パターンの発見
- 既存のリファレンスアーキテクチャ
反復検索スキルとの連携
プログレッシブな発見のために組み合わせる:
- サイクル1: 広範な検索 (npm、PyPI、MCP)
- サイクル2: 上位候補の詳細評価
- サイクル3: プロジェクト制約との互換性テスト
例
例1: 「デッドリンクチェックを追加」
ニーズ: Markdownファイルの壊れたリンクをチェック
検索: npm "markdown dead link checker"
発見: textlint-rule-no-dead-link (スコア: 9/10)
アクション: 採用 — npm install textlint-rule-no-dead-link
結果: カスタムコードゼロ、実績のあるソリューション
例2: 「HTTPクライアントラッパーを追加」
ニーズ: リトライとタイムアウト処理を備えた堅牢なHTTPクライアント
検索: npm "http client retry"、PyPI "httpx retry"
発見: got (Node) にリトライプラグイン、httpx (Python) に組み込みリトライ
アクション: 採用 — got/httpxをリトライ設定で直接使用
結果: カスタムコードゼロ、プロダクション実績のあるライブラリ
例3: 「設定ファイルリンターを追加」
ニーズ: プロジェクト設定ファイルをスキーマに対して検証
検索: npm "config linter schema"、"json schema validator cli"
発見: ajv-cli (スコア: 8/10)
アクション: 採用 + 拡張 — ajv-cliをインストール、プロジェクト固有のスキーマを記述
結果: 1パッケージ + 1スキーマファイル、カスタム検証ロジックなし
アンチパターン
- いきなりコードを書く: 既存のものがあるか確認せずにユーティリティを作成する
- MCPを無視する: MCPサーバーが既に機能を提供しているか確認しない
- 黙ってスキップする: 検索チャネルが利用不可だったのに「何も見つからなかった」と報告する
- 過剰カスタマイズ: ライブラリをラップしすぎてメリットを損なう
- 依存関係の肥大化: 小さな機能一つに巨大なパッケージをインストールする