godgrep

godgrep

意図に応じて、コードベース検索タスクを適切なツールに振り分けます。

ツールの振り分け

意図	主なツール	あわせて検討するツール
キーワード／シンボル検索（正確な識別子がわかっている）	mcp__plugin_ora_fff__grep	定義の検索には LSP
複数パターンの OR 検索 — 1 つの識別子の命名バリエーション	mcp__plugin_ora_fff__multi_grep	mcp__plugin_ora_fff__grep の逐次実行
ファイルの検索（名前で検索）	mcp__plugin_ora_fff__find_files	内容の一致検索には mcp__plugin_ora_fff__grep
概念／「X はどのように機能するか」／「Y はどこで処理されるか」（識別子がまだわからない）	mcp__plugin_ora_morph__codebase_search	morph で見つからない場合のみ、find_files + fff__grep + Read にフォールバック
機能をエンドツーエンドで追跡する	最初の全体像の把握には mcp__plugin_ora_morph__codebase_search	特定の呼び出し箇所の確認には mcp__plugin_ora_fff__grep
X のすべての使用箇所を検索する	LSP の参照検索	mcp__plugin_ora_fff__grep
特定のシンボルを検索する	LSP の定義へ移動	mcp__plugin_ora_fff__grep
構造的なコードパターン	ast-grep	フォールバックとして mcp__plugin_ora_fff__grep
git インデックス外／フォールバック	shell の grep / find	最終手段として、fff の後に使用
Git の履歴／blame	Bash（git log/blame）	—

質問が単一の広範な概念に関する場合は、mcp__plugin_ora_morph__codebase_search を 1 回呼び出すことで、複数の観点から並列に検索する必要はありません。2～3 個の並列検索に分けるのは、独立した識別子ベースの検索が複数ある場合に限ります（例：「X の呼び出し元と Y の定義を一度に検索する」）。

アンチパターン：機能に対する手当たり次第の OR 検索

1 つの機能に対して、長い OR パターンで推測語を列挙しないでください。同義語を見落とし、出力がノイズに埋もれます。

# Shotgun-grep — fragile, no signal
grep -r "FreeGift|ProgressBar|GiftModal|BuyXGetY|percentOff|fixedOff|salepify"
grep -r "appUpdate|checkAppUpdate|versionCheck|setAppUpdateHandler|needUpdate"

代わりに、README やディレクトリ構造をざっと確認して機能の実際の名称を把握し、具体的な語を 1 つ選んで grep し、最上位の検索結果を Read して参照先をたどります。multi_grep は1 つの識別子の命名バリエーション（例：['ActorAuth', 'PopulatedActorAuth', 'actor_auth']）を検索するためのものであり、機能に関連する用語を推測するためのものではありません。

Morph codebase_search — 意味・概念に関するクエリのデフォルト

mcp__plugin_ora_morph__codebase_search は、並列で grep とファイルの読み込みを行う Morph WarpGrep サブエージェントを実行し、内容を統合した回答を返します。「X はどのように動作するか」「Y はどこで処理されるか」「Z をつなぎ合わせているものは何か」「W を行う箇所をすべて見つけて」といった質問では、まずこれを使ってください。こうした質問では、Morph を 1 回呼び出すほうが fff__grep と Read を 4～8 回実行するより効率的です。

• 次の場合に使用します：質問が概念的・意味的なもの、または「X に関連するコードを見つけて」というもので、grep する単一の正確な識別子がない場合。理由：Morph は、呼び出し元のエージェントが通常は逐次的に行う grep、読み込み、要約の一連の処理を並列化するため、レイテンシとターン数を大幅に削減できます。
• 次の場合は使用しないでください：具体的な識別子がある場合は、fff__grep のほうが高速で網羅的であり、1 回の呼び出しで正確な file:line の検索結果を返します。
• 引用箇所は信頼し、結論は検証してください：Morph の file:line 参照は実在するコード箇所を示しますが、統合された説明（コードが 何をしているか、質問とどう関係するか）は誤っている可能性があります。回答の根拠として重要な場合は、引用箇所を Read で読み込み、Morph の解釈を確認してから伝えてください。

ast-grep

Abstract Syntax Tree パターンを使用した構造的なコード検索です。テキストではなく、コードの構造を照合します。

パターン検索

ast-grep run --pattern '<pattern>' --lang <lang> <path>

# Find all console.log calls
ast-grep run --pattern 'console.log($ARG)' --lang javascript .

# Find class declarations
ast-grep run --pattern 'class $NAME' --lang python /path/to/project

複雑なルール

インライン YAML（一時ファイルを使わず、すばやく反復できます）：

ast-grep scan --inline-rules "<yaml>" <path>

# Find async functions containing await
ast-grep scan --inline-rules "id: async-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" /path/to/project

ルールファイル（複雑なルールに推奨）：

# Write rule to a temp file, then scan
ast-grep scan --rule /tmp/my_rule.yml /path/to/project

AST の確認

ast-grep run --pattern '<code>' --lang <lang> --debug-query=cst

ルールが一致しない場合は、--debug-query=cst を使って具象構文木を出力し、正しい kind の値を確認してください。利用できる形式は cst（すべてのノード）、ast（名前付きノードのみ）、pattern（ast-grep がパターンをどのように解釈するか）です。

重要なルール

• 関係ルール（inside、has）では必ず stopBy: end を使用してください。指定しない場合、検索は一致しない最初のノードで停止し、サブツリー全体をたどりません。

has:
  pattern: await $EXPR
  stopBy: end # required for deep traversal

• シェル内のメタ変数はエスケープしてください：ダブルクォート文字列では \$VAR、シングルクォート文字列では '$VAR' を使用します
• シンプルな形から始め（まずパターン）、必要な場合にのみ kind と関係ルールを追加します
• all／any／not を使って、複雑な構造クエリを組み立てます

リファレンス：完全なガイドは references/ast-grep/ast-grep.md、YAML ルール構文は references/ast-grep/rule_reference.md を参照してください。

---

mcp__plugin_ora_fff__grep／mcp__plugin_ora_fff__find_files／LSP で十分な場合は、ast-grep を使わないでください。ast-grep は低速で、より多くのリソースを消費します。テキスト検索だけでなくコード構造の理解が必要な場合に限り、ast-grep を使用してください。