iterative-retrieval

iterative-retrieval の概要

iterative-retrieval は、エージェント型の作業で起こりがちな「コンテキスト問題」を解くためのワークフローパターンです。サブエージェントは最初、何が必要かを判断するには情報が足りず、そこから段階的に正しいファイル・用語・パターンへ絞り込んでいきます。特に、ワークフロー設計者、コードベース探索を行う人、そして初回取得では情報が足りないことが多い iterative-retrieval for Workflow Automation を構築している人に向いています。

ユーザーが本当に気にするのは理屈そのものではなく、この skill によってエージェントがよくある2つの失敗を避けられるかどうかです。つまり、コンテキストを送りすぎて予算を超えること、あるいは少なすぎて処理が止まることです。iterative-retrieval の主な価値は、探索を一発勝負の推測ではなく、ループに変える点にあります。

iterative-retrieval が解決すること

この skill は、事前には分からないコードベース固有のコンテキストに依存するタスクで使います。たとえば、実装パターンの特定、関連ファイルの洗い出し、最初の検索後に検索語を絞り直す、といった場面です。特に、明確な人間の指示なしに大きな repo を読み解く必要があるエージェントで効果的です。

iterative-retrieval が他と違う理由

「ざっと見て判断して」とだけ言う一般的なプロンプトと違い、iterative-retrieval には dispatch、evaluate、refine、repeat という具体的な取得ループがあります。これにより、サブエージェントのオーケストレーションがしやすくなります。とくに、広くてノイズの多い一括ダンプではなく、予測可能にコンテキストを増やしたいプロセスに向いています。

向いている使い方

この skill は、アーキテクチャの発見、RAG 風のコード探索、そして初回取得を意図的に不完全にするマルチエージェント・ワークフローに適しています。逆に、答えがすでに手元の情報だけで出せる場合、repo が小さい場合、または最初から対象ファイルを正確に指定できる場合は、あまり向きません。

iterative-retrieval の使い方

インストールして有効化する

skill manager から skill のインストールパスを使い、エージェントのワークフローを skills/iterative-retrieval/SKILL.md に向けます。この repo における典型的な iterative-retrieval のインストール例は次のとおりです。

npx skills add affaan-m/everything-claude-code --skill iterative-retrieval

最も効果が出るのは、すでに関連ファイルを人手で全部選び終えた後ではなく、コンテキスト探索が必要な仕事に対して呼び出す場合です。

あいまいな目的を使えるプロンプトに変える

この skill は、プロンプトに「目的」「範囲」「停止条件」が入っていると最もよく機能します。よい入力の例は次のようになります。

• 目的: 「認証フローを見つけて、トークン更新がどこで処理されているか説明して」
• 範囲: 「テストではなく、本番コードだけを検索して」
• 制約: 「各取得パスで見るファイルは数個以内に抑えて」
• 成功条件: 「自信を持って答えられる最小のファイルセットを返して」

iterative-retrieval usage は、モデルに一度のあいまいな依頼で repo 全体を推測させることではなく、コンテキストを絞り込むことが本質だからです。

最初に読むべきファイル

まず SKILL.md を開き、次に repo が提供している補助ドキュメントを確認します。この repo では、実務上の入口は今も SKILL.md です。インストール時に skill 本体だけがコピーされるなら、それが唯一の正本になります。その後、環境内に近接するワークフロードキュメントがあれば目を通し、ループを自分のオーケストレーション規則に合わせてください。

取得ループを回す

基本の流れは、狭い検索を投げる → 返ってきたコンテキストで十分か評価する → 足りなかった点をもとに次の検索を絞る → エージェントが行動できるだけの証拠が揃うまで繰り返す、です。重要なのは、毎回同じクエリを言い換えるのではなく、各パスで新しく見つかった用語を次に引き継ぐことです。

iterative-retrieval skill の FAQ

iterative-retrieval は大規模 codebase 専用ですか？

いいえ。サイズは重要ですが、実際の引き金は不確実性です。読む前にどのファイルが重要か予測できないなら、中規模の repo でも iterative-retrieval は役立ちます。

どんなときは使わないほうがいいですか？

すでに範囲が明確なタスク、関連ファイルが分かっているケース、固定入力を使った直接的なプロンプトで足りる場合は、iterative-retrieval は使わないほうがよいです。そのようなケースでは、ループの分だけオーバーヘッドが増え、答えの質はあまり上がりません。

通常のプロンプトより優れていますか？

探索タスクでは、はい。通常のプロンプトは、モデルが最初から正しいコンテキストを当てられる前提になりがちです。iterative-retrieval は、部分結果を読んだあとにプロンプトを適応させる必要があり、最終的な答えがその適応に左右されるときに向いています。

初心者でも使いやすいですか？

はい。ループをそのまま守るなら使いやすいです。学習コストの中心は構文ではなく、最初の取得を「役立つだけの小ささ」と「適切な用語が出るだけの広さ」の両方を満たすように選ぶことです。

iterative-retrieval skill を改善する方法

1回目の検索対象をもっと鋭くする

品質を最も大きく上げるのは、最初の問いの立て方です。「関連コードを探して」ではなく、特定の挙動・サブシステム・意思決定ポイントを指定してください。すでに分かっていること、推測していること、そして有用な手がかりとして何が見えればよいかも含めると、iterative-retrieval usage の効率が大きく上がります。

よくある失敗パターンに注意する

典型的な失敗は取りすぎです。エージェントが大量のファイルを引いてきて、結果から学べなくなります。もう一つは取り足りなさで、次に探すべき検索語を特定できるだけのコンテキストがありません。1回目の結果が一般的なファイルばかりなら、検索範囲を広げるのではなく、用語、呼び出し元、エントリポイントを尋ねて絞り込み直してください。

推測ではなく証拠で反復する

最初の出力のあとに返すのは、最も情報価値の高い材料だけに絞ります。たとえば、ファイル名、関数名、エラーメッセージ、見慣れない用語です。新しい証拠を足さずに、単に「もう一度見て」と頼むのは避けてください。iterative-retrieval for Workflow Automation で最も効果が高い改善は、この証拠ループをオーケストレーションに組み込み、各パスで検索空間が変わるようにすることです。

repo のルールに合わせる

環境に命名規則、フォルダ境界、エージェントの引き継ぎルールがあるなら、最初の取得の前にプロンプトへ織り込んでください。この skill は、すべての codebase を一般的な検索問題として扱うのではなく、実際の構造を尊重したときに最も強く機能します。