Search Tools

Search Tools Best Practices

検索ツール（file_candidates, code_search, sym_index, sym_find）の効果的な使用方法を支援するスキル。エージェントが適切なツールを選択し、パフォーマンスと精度を最適化するためのガイドラインを提供する。

主な機能:

• ツール選択ガイド: タスクに最適な検索ツールの選択
• パフォーマンス最適化: 高速かつ効率的な検索実行
• エッジケース対応: よくある失敗パターンと回避策
• 統合ワークフロー: 複数ツールを組み合わせた検索パターン

v2.0.0の新機能:

• 自動除外: DEFAULT_EXCLUDESがデフォルトで適用（node_modules, .git, dist等）
• 結果キャッシュ: 同一検索の高速化（TTL: 5-10分）
• Agent Hints: 結果の信頼度と次のアクション提案
• 統一エラー処理: SearchToolErrorによる分類されたエラーメッセージ

使用タイミング

以下の場合にこのスキルを読み込む：

• ファイルやコードを検索する場合
• シンボル定義を探す場合
• コードベースの探索を行う場合
• 検索パフォーマンスを最適化する場合

ツール選択ガイド（CRITICAL）

新機能（v2.0.0）

自動除外パターン（DEFAULT_EXCLUDES）

検索ツールは以下のパターンをデフォルトで除外します：

const DEFAULT_EXCLUDES = [
  "node_modules", ".git", "dist", "build", "coverage",
  ".next", ".nuxt", "vendor", "__pycache__", ".cache",
  "*.min.js", "*.min.css", ".pi/search", ".pi/analytics"
];

無効化方法: exclude: [] を明示的に指定

// デフォルト除外を無効化して全ファイルを検索
file_candidates({
  pattern: "*.ts",
  exclude: []  // 空配列で無効化
})

結果キャッシュ

検索結果は自動的にキャッシュされます：

Agent Hints

各検索結果には details.hints が含まれます：

{
  results: [...],
  truncated: false,
  details: {
    hints: {
      confidence: 0.85,          // 0.0-1.0
      suggestedNextAction: "refine_pattern",  // 結果が少ない場合
      alternativeTools: ["sym_find"]          // 代替ツール提案
    }
  }
}

suggestedNextAction の値:

• refine_pattern: 結果が0件、パターンを修正
• expand_scope: 検索範囲を広げる
• increase_limit: 結果が切り捨てられている
• try_different_tool: 別のツールを試す

統一エラー処理（SearchToolError）

エラーは以下のカテゴリに分類されます：

検索履歴

全ての検索クエリは履歴に記録され、関連クエリの推薦に使用されます。

意思決定フローチャート

タスクの種類は？
│
├─ ファイル/ディレクトリを探す
│   └─ file_candidates を使用
│
├─ コードパターンを検索する
│   └─ code_search を使用
│
└─ 関数/クラス定義を探す
    │
    ├─ インデックス済み？
    │   ├─ Yes → sym_find を使用（高速）
    │   └─ No  → sym_index で生成後、sym_find を使用
    │
    └─ 1回限り？
        └─ code_search でも代用可能

ツール比較表

file_candidates（fd wrapper）

概要

fdコマンドを使用した高速ファイル・ディレクトリ列挙。globパターン、拡張子フィルタ、深度制限などをサポート。

基本構文

file_candidates({
  pattern: "*.ts",        // globパターン（--glob自動付与）
  type: "file",           // "file" | "dir"
  extension: ["ts", "tsx"], // 拡張子フィルタ
  exclude: ["node_modules", "dist"], // 除外パターン
  maxDepth: 3,            // 最大深度
  limit: 50               // 結果数制限
})

ベストプラクティス

1. 必ず除外パターンを指定する

// 良い例: node_modules等を除外
file_candidates({
  pattern: "*.ts",
  exclude: ["node_modules", ".git", "dist", "build"]
})

// 悪い例: 除外なし（大量の不要なファイルが返る可能性）
file_candidates({
  pattern: "*.ts"
})

2. limitを常に設定する

// 良い例: 上限を設定
file_candidates({ limit: 100 })

// 悪い例: 無制限（大規模プロジェクトで問題発生）
file_candidates({}) // limit未指定

3. 拡張子フィルタを活用する

// 良い例: extensionフィルタ使用
file_candidates({
  extension: ["ts", "tsx"],
  limit: 50
})

// 悪い例: globパターンで拡張子指定（エラーになる可能性）
file_candidates({
  pattern: "*.ts"  // fdは正規表現として解釈
})

アンチパターン

パフォーマンスガイド

code_search（rg wrapper）

概要

ripgrep（rg）を使用した高速コード検索。正規表現、型フィルタ、コンテキスト行をサポート。

基本構文

code_search({
  pattern: "function \\w+",   // 検索パターン（正規表現）
  path: "src",                // 検索パス
  type: "ts",                 // ファイル型フィルタ
  context: 3,                 // 前後のコンテキスト行数
  ignoreCase: true,           // 大文字小文字無視
  literal: false,             // リテラル検索フラグ
  limit: 50                   // 結果数制限
})

ベストプラクティス

1. パスを絞り込む

// 良い例: 具体的なパスを指定
code_search({
  pattern: "export function",
  path: "src/components",
  limit: 50
})

// 悪い例: プロジェクト全体を検索（遅い・結果過多）
code_search({
  pattern: "function",
  limit: 50
})

2. 型フィルタを活用する

// 良い例: TypeScriptファイルのみ検索
code_search({
  pattern: "interface",
  type: "ts",
  limit: 50
})

// 悪い例: 全ファイルを検索（markdown等も含む）
code_search({
  pattern: "interface"
})

3. リテラル検索を適切に使い分ける

// 正規表現メタ文字を含む場合はリテラル検索
code_search({
  pattern: "/* TODO */",
  literal: true  // 正規表現として解釈させない
})

// パターンマッチが必要な場合は正規表現
code_search({
  pattern: "function \\w+\\(\\)",
  literal: false
})

4. 空パターンを避ける

// 絶対に避ける: 空パターンは全行にマッチ
code_search({
  pattern: ""
})

// 代替案: 具体的なパターンを指定
code_search({
  pattern: "\\S"  // 空白以外の文字を含む行
})

アンチパターン

終了コードの意味

パフォーマンスガイド

sym_index（ctags wrapper）

概要

Universal Ctagsを使用してシンボルインデックスを生成。関数、クラス、変数などの定義位置を記録。

基本構文

sym_index({
  path: "src",           // インデックス対象パス
  force: false           // 強制再生成フラグ
})

ベストプラクティス

1. 生成前に除外パターンを確認する

// 良い例: インデックス生成前に除外を確認
// sym_index自体にはexcludeパラメータがないため、
// パスを絞り込むか、.ctags設定ファイルを使用

sym_index({
  path: "src"  // node_modulesを含まないパスを指定
})

// 悪い例: プロジェクトルートを指定（node_modulesが含まれる）
sym_index({
  path: "."  // 大量の警告が出る可能性
})

2. 大規模プロジェクトでは事前にインデックス生成

// セッション開始時に一度だけ実行
await sym_index({ path: "src" })

// 以降はsym_findで高速検索
await sym_find({ name: "execute", kind: ["function"] })

3. インデックスの有効性を確認する

インデックスファイルが存在するか、sym_findで結果が返ってくるかで判断。

アンチパターン

パフォーマンスガイド

sym_find（シンボル検索）

概要

sym_indexで生成されたインデックスから、シンボル定義を高速検索。

基本構文

sym_find({
  name: "execute",           // シンボル名（ワイルドカード可）
  kind: ["function"],        // 種別フィルタ
  file: "src/utils",         // ファイルパスフィルタ
  limit: 50                  // 結果数制限
})

ベストプラクティス

1. kindフィルタで種別を絞り込む

// 良い例: 関数のみを検索
sym_find({
  name: "handle*",
  kind: ["function"],
  limit: 20
})

// 悪い例: 種別未指定（変数や定数も含まれる）
sym_find({
  name: "handle*"
})

2. nameパターンを活用する

// ワイルドカード使用
sym_find({ name: "use*" })      // useで始まるシンボル
sym_find({ name: "*Handler" })  // Handlerで終わるシンボル
sym_find({ name: "*State*" })   // Stateを含むシンボル

3. ファイルパスで絞り込む

// 特定ディレクトリ内のシンボルのみ
sym_find({
  name: "create",
  file: "src/factory",
  limit: 20
})

kindの主要な値

アンチパターン

パフォーマンス

• インデックス済みの場合: <20ms（超高速）
• インデックス未生成の場合: 事前にsym_indexが必要

統合ワークフロー

ワークフロー1: 新機能実装箇所の特定

1. file_candidates で関連ファイルを特定
   ↓
2. code_search でパターンを検索
   ↓
3. sym_find で具体的な関数定義を特定

// Step 1: 関連ファイルを探す
const files = await file_candidates({
  pattern: "*auth*",
  extension: ["ts"],
  exclude: ["node_modules", "test"],
  limit: 20
})

// Step 2: 認証関連のコードを検索
const results = await code_search({
  pattern: "authenticate|login|token",
  path: files[0].path,
  type: "ts",
  limit: 30
})

// Step 3: 関数定義を特定
const definitions = await sym_find({
  name: "*auth*",
  kind: ["function"],
  limit: 10
})

ワークフロー2: リファクタリング対象の調査

1. sym_index でインデックス生成（大規模プロジェクト）
   ↓
2. sym_find で対象シンボルを検索
   ↓
3. code_search で使用箇所を検索

// Step 1: インデックス生成（一度だけ）
await sym_index({ path: "src" })

// Step 2: リファクタリング対象の関数を特定
const targets = await sym_find({
  name: "deprecated*",
  kind: ["function"],
  limit: 50
})

// Step 3: 使用箇所を検索
for (const target of targets) {
  const usages = await code_search({
    pattern: target.name,
    path: "src",
    type: "ts",
    limit: 20
  })
}

ワークフロー3: 並列検索でパフォーマンス最大化

// 複数の検索を並列実行
const [files, functions, patterns] = await Promise.all([
  file_candidates({
    extension: ["ts"],
    exclude: ["node_modules"],
    limit: 50
  }),
  sym_find({
    kind: ["function"],
    limit: 100
  }),
  code_search({
    pattern: "TODO|FIXME",
    type: "ts",
    limit: 30
  })
])

エラーハンドリング

一般的なエラーと対応

フォールバック戦略

// 1. まず高速な検索を試す
let results = await code_search({
  pattern: targetPattern,
  limit: 50
})

// 2. 結果が空の場合、パターンを緩める
if (results.length === 0) {
  results = await code_search({
    pattern: simplifiedPattern,
    ignoreCase: true,
    limit: 100
  })
}

// 3. それでも見つからない場合はファイル探索
if (results.length === 0) {
  const files = await file_candidates({
    pattern: "*related*",
    limit: 20
  })
  // ファイル内容を直接確認
}

クイックリファレンス

タスク別ツール選択

パフォーマンス最適化の優先順位

1. 除外パターンを設定（node_modules, .git, dist等）
2. limitを設定（無制限を避ける）
3. パスを絞り込む（プロジェクト全体を避ける）
4. 型フィルタを使用（type: "ts"等）
5. 並列実行を活用（Promise.all）

設定例

.ctags（プロジェクトルート）

--exclude=node_modules
--exclude=dist
--exclude=build
--exclude=.git
--languages=TypeScript,JavaScript

推奨除外パターン

const DEFAULT_EXCLUDES = [
  "node_modules",
  ".git",
  "dist",
  "build",
  "coverage",
  ".next",
  ".nuxt",
  "vendor",
  "__pycache__",
  "*.min.js"
]

Converted and distributed by TomeVault — claim your Tome and manage your conversions.