affaan-m/search-first

/search-first — コーディング前に調査する

「既存のソリューションを実装前に検索する」ワークフローを体系化します。

トリガー

以下の場合にこのスキルを使用します:

• 既存のソリューションが存在する可能性が高い新しい機能を開始する場合
• 依存関係やインテグレーションを追加する場合
• ユーザーが「X 機能を追加して」と要求し、コードを書こうとしている場合
• 新しいユーティリティ、ヘルパー、または抽象化を作成する前

ワークフロー

┌─────────────────────────────────────────────┐
│  0. ツール利用可能性の事前確認              │
│     依存する前に検索チャネルを確認；        │
│     スキップしたチャネルを正直に報告する    │
├─────────────────────────────────────────────┤
│  1. ニーズ分析                              │
│     必要な機能を定義する                    │
│     言語/フレームワークの制約を特定する     │
├─────────────────────────────────────────────┤
│  2. 並列検索（researcher エージェント）     │
│     ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│     │  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 設定 | 公式ドキュメント/ウェブ検索にフォールバック | | スキルディレクトリ | ls ~/.claude/skills ~/.codex/skills（該当する場合） | ローカルスキルカタログが利用できないと明示 |

クイックモード（インライン）

ユーティリティを書いたり機能を追加したりする前に、以下を確認します:

0. これはリポジトリに既に存在するか？ → まず関連モジュール/テストを rg で確認
1. これはよくある問題か？ → npm/PyPI を検索
2. MCP はあるか？ → ~/.claude/settings.json を確認して検索
3. このためのスキルはあるか？ → ~/.claude/skills/ を確認
4. GitHub に実装/テンプレートがあるか？ → 新規コードを書く前に保守された OSS の GitHub コード検索を実行

フルモード（エージェント）

非自明な機能には、researcher エージェントを起動します:

Agent(subagent_type="general-purpose", prompt="
  既存のツールを調査してください: [説明]
  言語/フレームワーク: [言語]
  制約: [あれば]

  検索先: npm/PyPI、MCP サーバー、Claude Code スキル、GitHub
  返却: 推薦付きの構造化比較
")

古い Claude Code ドキュメントではこれを Task(...) と呼ぶ場合があります；アクティブなハーネスが公開している現在のエージェント/サブエージェントツール名を使用してください。

カテゴリ別検索ショートカット

開発ツール

• Linting → 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

統合ポイント

planner エージェントとの統合

planner はフェーズ1（アーキテクチャレビュー）の前に researcher を呼び出すべきです:

• Researcher が利用可能なツールを特定
• Planner がそれらを実装計画に組み込む
• 計画での「車輪の再発明」を回避

architect エージェントとの統合

architect は以下のために researcher に相談すべきです:

• テクノロジースタックの決定
• 統合パターンの発見
• 既存のリファレンスアーキテクチャ

iterative-retrieval スキルとの統合

段階的な発見のために組み合わせます:

• サイクル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）with retry plugin, httpx（Python）with built-in retry
アクション: 採用 — got/httpx をリトライ設定で直接使用
結果: カスタムコードなし、本番実証済みのライブラリ

例3: 「設定ファイルリンターを追加」

必要: プロジェクト設定ファイルをスキーマに対して検証
検索: npm "config linter schema", "json schema validator cli"
発見: ajv-cli（スコア: 8/10）
アクション: 採用 + 拡張 — ajv-cli をインストール、プロジェクト固有のスキーマを記述
結果: 1 パッケージ + 1 スキーマファイル、カスタム検証ロジックなし

アンチパターン

• コードへの飛び込み: 既存のものがあるか確認せずにユーティリティを書く
• MCP の無視: MCP サーバーが既にその機能を提供しているかチェックしない
• サイレントスキップ: 検索チャネルが利用できなかったのに「何も見つからなかった」と報告する
• 過度なカスタマイズ: ライブラリをラップしすぎてそのメリットを失う
• 依存関係の肥大化: 1つの小さな機能のために巨大なパッケージをインストールする