search-hierarchy

検索ツールの使い分け

クエリの種類ごとに、最もトークン効率の高い検索ツールを使用してください。

判断ツリー

Query Type?
├── STRUCTURAL (code patterns)
│   → AST-grep (~50 tokens output)
│   Examples: "def foo", "class Bar", "import X", "@decorator"
│
├── SEMANTIC (conceptual questions)
│   → LEANN (~100 tokens if path-only)
│   Examples: "how does auth work", "find error handling patterns"
│
├── LITERAL (exact identifiers)
│   → Grep (variable output)
│   Examples: "TemporalMemory", "check_evocation", regex patterns
│
└── FULL CONTEXT (need complete understanding)
    → Read (1500+ tokens)
    Last resort after finding the right file

トークン効率の比較

ツール	出力サイズ	最適な用途
AST-grep	~50 tokens	関数やクラスの定義、インポート、デコレーター
LEANN	~100 tokens	概念的な質問、アーキテクチャ、パターン
Grep	~200-2000	正確な識別子、正規表現、ファイルパス
Read	~1500+	ファイルを見つけた後の全体的な理解

フックによる強制

grep-to-leann.sh フックは次の処理を自動的に行います。

1. クエリの種類（構造的／意味的／リテラル）を検出します
2. 構造的なクエリをブロックし、AST-grep を提案します
3. 意味的なクエリをブロックし、LEANN を提案します
4. リテラルパターンは Grep での検索を許可します

すること

• コード構造に関する質問では AST-grep から始めます
• 「X はどのように動作しますか」という質問には LEANN を使用します
• Grep は正確な識別子の一致を探す場合にのみ使用します
• 検索してファイルを見つけてから、そのファイルを読みます

しないこと

• 概念的な質問に Grep を使用しないでください（何も見つかりません）
• 関連するファイルが分かる前にファイルを読まないでください
• AST-grep でファイル名と行番号が分かる場合に Read を使用しないでください
• フックの提案を無視しないでください

例

# STRUCTURAL → AST-grep
ast-grep --pattern "async def $FUNC($$$):" --lang python

# SEMANTIC → LEANN
leann search opc-dev "how does authentication work" --top-k 3

# LITERAL → Grep
Grep pattern="check_evocation" path=opc/scripts

# FULL CONTEXT → Read (after finding file)
Read file_path=opc/scripts/z3_erotetic.py

最適な流れ

1. AST-grep: "Find async functions" → 3 file:line matches
2. Read: Top match only → Full understanding
3. Skip: 4 irrelevant files → 6000 tokens saved