/search-first — コードを書く前に調査せよ
新しい機能、ユーティリティ、統合を作成したり、ライブラリを選定する前に、まず既存のソリューションを検索してください。最高のコードとは、書かなくて済むコードです。
このスキルは規律であり、メカニズムではありません。検索の方法 — 並列サブエージェント、ライブドキュメント参照、レジストリクエリ — はエージェントハーネスに委ねられ、変化し続けます。このスキルが固定するのは、そうした変化の中でも生き残る部分、すなわち検索前に明確に言語化し、ソースの優先順位に従って検索し、判定を記録して終了するという規律です。規律を前面に押し出し、メカニズムは委任してください。
ステップ0 — 要件を明文化する(必須、ユーザーに見えるテキスト)
ツール呼び出しやサブエージェントの前に、プレーンなアシスタントテキスト(ツール引数に埋め込まない)で2~3文を記述し、次の内容を明らかにしてください。
- 何の機能が必要か — 具体的に、「Xサポート」のような抽象的な表現ではなく
- 言語/フレームワーク — 実装に使用するもの
- 制約 — 既存の依存関係、パフォーマンス制限、ライセンス要件
理由: これにより検索クエリが外部化され、ユーザーは努力を費やす前に方向転換でき、監査可能な記録が残ります。argsに要件が含まれているサブエージェント呼び出しではこのステップを満たしたことになりません。ユーザーはツール引数ではなくチャットテキストを読みます。まずテキストとして要件を発行し、その後でその内容を反映したツールを呼び出してください。
ステップ1 — ソースの優先順位に従って検索する
以下の順序で確認し、強力な一致が見つかった時点で早期に停止してください。
- このリポジトリ —
rg/grep で関連モジュールとテストを検索する。目的のものがすでに存在している可能性があります。 - パッケージレジストリ — 使用中の言語の npm / PyPI / crates / Go モジュール。
- MCPサーバー — 最初に既に設定済みのサーバー、次にレジストリ。機能がすでに組み込まれている可能性があります。
- インストール済みのスキル/エージェント/ツール — ハーネスがすでに持っているかもしれません。
- メンテナンスされたOSS / テンプレート — 新しいコードを書く前にGitHubでコード検索を行う。
決定時にライブドキュメントを参照してください(例:context7、またはレジストリ自体)。記憶に頼ったパッケージ情報は古くなります。
ステップ2 — 評価し、判定(Verdict)を記録する
候補を全体的に評価してください。機能的適合性、メンテナンス状況(最終コミット日、イシュー応答速度)、コミュニティ、ドキュメント、ライセンス、依存関係のフットプリント。長所と短所を文章で説明してください。数値スコア(8/10)、アルファベットグレード、重み付きポイントテーブルは付けないでください。それらは誤った精度を生み出します。エビデンスに基づいた1つの判定が正直な出力です。
| 判定 | 条件 | アクション |
|---|---|---|
| Adopt(採用) | 完全一致、適切にメンテナンス、パーミッシブライセンス | そのままインストールして使用 |
| Extend(拡張) | 良い基盤、部分的に適合 | インストール + 薄いラッパー/設定 |
| Compose(合成) | いくつかの弱い一致 | 2~3の小さなパッケージを組み合わせる |
| Build(自作) | 適切なものがない | 独自に作成 — ただし見つけた情報に基づいて |
毎回、認識可能な1行の判定で終了してください — この行が成果物です。
Verdict: <Adopt|Extend|Compose|Build> — <パッケージ名 または "custom"> — <エビデンスに基づく理由>
判定行がない検索は不完全なパスです。作業自体は行いましたが、ユーザー(または次のステップ)が行動できる決定を残していません。これはこのワークフローで最もよく見られる失敗です。理由にはエビデンス(スター数、最終コミット日、具体的な機能一致)を添え、形容詞(「良さそう」「人気」)だけで済ませないでください。
クイックモード vs フルモード
- クイックモード(インライン) — 単一の明白なニーズに対する場合: ステップ0~2を自分で実行し、数回の検索で判定を述べてください。
- フルモード(委任) — 重要なニーズに対する場合: ステップ0の後、調査をリサーチサブエージェント(ソリューション発見のためにハーネスが提供するもの)に委ねてください。明文化した内容をサブエージェントのプロンプトにミラーリングし、候補と上記の形式の判定を返させてください。本当に難しい質問のためにのみ、重いマルチソース調査を予約してください。ライブラリを見つけることは研究レポートよりも軽いタスクです。
ユーザーが「調査をスキップ」と言った場合
ユーザーから調査をスキップするよう指示された場合(「とにかく実装して」「時間がない」「好きなのを使って」)、それでも実装前に判定行として決定を記録してください。調査のスキップ自体が一つの決定です。したがって、他のパスと同様に判定を取得します(これにより選択が監査可能になり、軌道修正の機会が開かれ続けます)。
ご依頼により調査をスキップします — Xの既存ライブラリは確認していません。
Verdict: <Adopt|Build> — <暫定的な選択 または "custom"> — ご依頼により調査なしで選択。60秒スキャンをご希望の場合はお知らせください。
理由: ユーザーは既存のソリューションが存在することを知らないかもしれません。黙ってスキップすると、軌道修正の機会を奪います。判定行の後は、検索せずに実装を進めてください。これをフルリサーチをこっそり行うための抜け道にしないでください。
アンチパターン
- コードに飛びつく — ユーティリティが存在するか確認せずに作成してしまう。
- MCP/インストール済み機能を無視する — すでに組み込まれているものを再構築する。
- カスタマイズしすぎる — ライブラリを厚くラップして、その利点を損なう。
- 依存関係の肥大化 — 小さな機能のために巨大なパッケージをインストールする。
- 判定なしの検索 — 作業は行ったが、決定を記録しない。
例(説明用 — パッケージはライブで確認のこと)
これらは判定がどのように読まれるかを示しています。特定のパッケージを推奨するものではありません。特定のパッケージに依存する前に再検索してください。
- デッドリンクチェック → メンテナンスされ、パーミッシブライセンスのリンクチェックルールで、すべてのリンクタイプをカバー →
Verdict: Adopt — textlint-rule-no-dead-link — 活発なメンテナンス、MIT、完全カバレッジ - Qiitaクロス投稿 → メンテナンスされていない部分的なラッパーのみ存在 →
Verdict: Build — custom — メンテナンスされた完全なソリューションなし。HTTPクライアント経由でプラットフォームAPIを再利用 - 日本語用語の一貫性 → 辞書ベースのチェッカーで、プロジェクト設定が必要 →
Verdict: Extend — textlint-rule-prh — インストール + プロジェクト辞書