file-search

ファイル検索スキル

テキストパターンには ripgrep、構造的なコードパターンには ast-grep を使用して、効率よくコードを検索します。

目的

ファイル検索スキルを使うと、MassGen 環境にプリインストールされた2つの強力な検索ツールを利用できます。

1. ripgrep (rg)：正規表現に対応した超高速のテキスト検索ツールで、文字列、パターン、テキストの一致を検索します
2. ast-grep (sg)：抽象構文木に基づいてコードパターンを検索する、構文を認識する構造検索ツールです

これらのツールを使って、コードベースを理解し、使用パターンを見つけ、変更の影響を分析し、特定のコード構造を特定します。どちらのツールも、従来の grep コマンドや find コマンドより大幅に高速です。

このスキルを使う場面

次のような場合に、ファイル検索スキルを使います。

• 新しいコードベースを理解するとき（エントリーポイントや主要なクラスを探す）
• リファクタリング前に、関数、クラス、変数のすべての使用箇所を探すとき
• 特定のコードパターン（エラー処理、API 呼び出しなど）を特定するとき
• セキュリティ上の問題（ハードコードされた認証情報、SQL クエリ、eval の使用など）を検索するとき
• 依存関係やインポートを分析するとき
• TODO、FIXME、コードコメントを探すとき

ripgrep を選ぶ場面：

• テキストベースの検索（文字列、コメント、変数名）
• 多数のファイルを対象にした高速でシンプルなパターンマッチング
• 正確なコード構造が重要ではない場合

ast-grep を選ぶ場面：

• 構造的なコード検索（関数シグネチャ、クラス定義）
• 構文を認識したマッチング（コードの意味を理解した検索）
• 複雑なリファクタリング（特定のコードパターンの検索）

検索ツールの実行

MassGen では、execute_command ツールを使って ripgrep と ast-grep を実行します。

# Using ripgrep
execute_command("rg 'pattern' --type py src/")

# Using ast-grep
execute_command("sg --pattern 'class $NAME { $$$ }' --lang python")

どちらのツールも MassGen の Docker コンテナにプリインストールされており、シェルから実行できます。

検索対象を絞り込む

重要：結果が多くなりすぎないよう、必ず対象を絞った検索から始めてください。一致する結果が数千件あると、分析が不可能になり、トークンも無駄になります。

次の方法は、ripgrep と ast-grep の両方に適用できます。

範囲を絞り込む方法

最初から次の方法を適用し、検索対象を効果的に絞り込みます。

1. ファイルの種類／言語を指定する：必ず言語でフィルターします

   # Ripgrep
   rg "function" --type py --type js
   
   # AST-grep
   sg --pattern 'function $NAME($$$) { $$$ }' --lang js
   

2. 特定のディレクトリを対象にする：まず、該当しそうな場所を検索します

   # Ripgrep
   rg "LoginService" src/services/
   
   # AST-grep
   sg --pattern 'class LoginService { $$$ }' src/services/
   

3. 具体的なパターンを使う：できるだけ具体的なパターンを指定します

   # Ripgrep: BAD - too broad
   rg "user"
   # Ripgrep: GOOD - more specific
   rg "class.*User.*Service" --type py
   
   # AST-grep: BAD - too broad
   sg --pattern '$X'
   # AST-grep: GOOD - more specific
   sg --pattern 'class $NAME extends UserService { $$$ }' --lang js
   

4. 結果の件数を制限する：head を使って結果数の上限を設定します

   # Ripgrep
   rg "import" --type py | head -20
   rg "TODO" --count
   
   # AST-grep
   sg --pattern 'import $X from $Y' --lang js | head -20
   

段階的な検索の絞り込み

不慣れなコードを調べるときは、次のワークフローを使います。

Ripgrep の例：

# Step 1: Count matches to assess scope
rg "pattern" --count --type py

# Step 2: If too many results, add more filters
rg "pattern" --type py src/ --glob '!tests'

# Step 3: Show limited results to inspect
rg "pattern" --type py src/ | head -30

# Step 4: Once confirmed, get full results or target further
rg "pattern" --type py src/specific_module/

AST-grep の例：

# Step 1: Assess scope with broad structural pattern
sg --pattern 'function $NAME($$$) { $$$ }' --lang js | head -10

# Step 2: If too many results, narrow to specific directory
sg --pattern 'function $NAME($$$) { $$$ }' --lang js src/

# Step 3: Make pattern more specific
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/

# Step 4: Target exact location
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/services/

検索結果が多すぎる場合

検索で数百件の一致が返された場合（rg と sg の両方に適用）：

1. ファイルの種類／言語のフィルターを追加する：--type py（rg）または --lang python（sg）
2. ディレクトリの範囲を狭める：. の代わりに src/ を検索する
3. パターンを具体化する：パターンの前後にコンテキストを追加する
4. 単語境界を使う：単語全体のみを対象にするには -w フラグを使う（rg）
5. head にパイプする：| head -50 で出力を制限する
6. テストファイルを除外する：--glob '!*test*'（rg）を指定するか、テスト用ディレクトリを避ける（sg）

絞り込みの例：

# Step 1: Too broad (10,000+ matches)
rg "error"

# Step 2: Add file type (1,000 matches)
rg "error" --type py

# Step 3: Add directory scope (200 matches)
rg "error" --type py src/

# Step 4: Make pattern specific (20 matches)
rg "raise.*Error" --type py src/

# Step 5: Target exact location (5 matches)
rg "raise.*Error" --type py src/services/

使い方

Ripgrep (rg)

# Basic text search
rg "pattern" --type py --type js

# Common flags
-i              # Case-insensitive
-w              # Match whole words only
-l              # Show only filenames
-n              # Show line numbers
-C 3            # Show 3 lines of context
--count         # Count matches per file
--glob '!dir'   # Exclude directory

# Examples
rg "function.*login" --type js src/
rg -i "TODO" --count
rg "auth|login|session" --type py

AST-Grep (sg)

# Structural code search
sg --pattern 'function $NAME($$$) { $$$ }' --lang js

# Metavariables
$VAR     # Matches single AST node
$$$      # Matches zero or more nodes

# Examples
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'import $X from $Y' --lang js
sg --pattern 'async function $NAME($$$) { $$$ }' src/

よく使う検索パターン

# Security issues
rg -i "password\s*=\s*['\"]" --type py
rg "\beval\(" --type js

# TODOs and comments
rg "TODO|FIXME|HACK"

# Code structures
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'try { $$$ } catch ($E) { $$$ }' --lang js

# Dependencies
rg "from requests import" --type py
rg "require\(['\"]" --type js

# Refactoring
rg "\.old_method\(" --type py
rg "@deprecated" -A 5

ファイルの種類のフィルター

ripgrep でよく使うファイルの種類：py、js、ts、rust、go、java、c、cpp、html、css、json、yaml、md

使用できるすべての種類を確認するには --type-list を使うか、カスタムの種類を定義します。

rg --type-add 'config:*.{yml,yaml,toml,ini}' --type config "pattern"

パフォーマンスのヒント

詳しい方法については、「検索対象を絞り込む」セクションを参照してください。主なヒント：

# Limit scope to specific directories
rg "pattern" src/

# Filter by file type
rg "pattern" --type py --type js

# Exclude large directories
rg "pattern" --glob '!{node_modules,venv,.git}'

# Use fixed strings (no regex) for speed
rg -F "exact string"

# Count before viewing full results
rg "pattern" --count --type py

ベストプラクティス

1. 範囲を絞ってから広げる：最初から具体的なパターン、ファイルの種類、ディレクトリの範囲を指定します
2. 表示する前に件数を確認する：--count または | head -N を使って、結果の量を事前に確認します
3. ファイルの種類を必ず指定する：言語で絞り込むには、--type（rg）または --lang（sg）を使います
4. よくあるノイズを除外する：習慣的に --glob '!{node_modules,venv,.git,dist,build}' を追加します
5. ツールを組み合わせる：テキストパターンには rg、コードの構造パターンには sg を使います
6. コンテキストを戦略的に使う：前後の行を表示するには -C N を追加します。ただし、出力の量に注意してください

トラブルシューティング

• 一致するものが見つからない：ファイルの種類のフィルターを確認し、大文字と小文字を区別しない検索には -i を試し、まず部分的なパターンで検索します
• 処理が遅すぎる：--glob でディレクトリを除外し、--type でファイルの種類を絞り、検索パスを限定します
• AST-grep の問題：--lang が正しいことを確認し、より単純なパターンを試すか、rg を使ってコードの存在を確認します

リソース

• Ripgrep のドキュメント
• AST-grep のドキュメント