ripgrep

Ripgrep スキル

ripgrep バイナリを使用した強化コード検索です。注：コードの発見やランキング、小さな出力を優先する場合は `pnpm search:code` を、最速で正確なリテラル一致を優先する場合は生の `rg` を使用してください。 - `pnpm search:code` を使用したハイブリッドコード検索（BM25 テキスト検索＋セマンティックベクトルランキング） - 網羅的なパターン検索（すべての一致を対象とし、上位 N 件にランキングしない）には生の ripgrep を使用 - 高度な正規表現パターン（-P フラグによる PCRE2） - .ripgreprc によるカスタムファイルタイプ定義 - .gitignore およびカスタム無視パターンとの統合

⚡ 推奨：ハイブリッドコード検索

日常的なコードの発見には、ハイブリッド検索システムを使用してください。

• テキスト検索はセットアップ不要ですぐに使えます（ripgrep ベースの BM25）
• セマンティック検索には、初回のみインデックスのビルドが必要です：pnpm code:index:reindex（GPU で約 12 分、CPU で約 17 分）
• GPU 高速化された fastembed による埋め込み（NVIDIA CUDA を自動検出）
• メモリセーフ：ONNX Runtime のメモリリークを回避するため、埋め込み処理を独立したサブプロセスで実行
• ハイブリッドスコアリング：Reciprocal Rank Fusion（RRF）により、テキスト一致とセマンティック類似性を組み合わせます

前提条件

# Build the semantic index (one-time, or after major codebase changes)
pnpm code:index:reindex

# Verify .env has embeddings enabled (should be default)
# HYBRID_EMBEDDINGS=on
# LANCEDB_EMBEDDING_MODE=fastembed

インデックスをビルドしていない場合、pnpm search:code はテキストのみの一致検索にフォールバックします。「authentication flow」のような概念を表すクエリは、埋め込みがないと良好な結果を返しません。

検索コマンド

# Project structure (directory tree + entry points + dependency graph + Mermaid)
pnpm search:structure

# Token budget analysis (file sizes + token estimates + refactor advice)
pnpm search:tokens .claude/lib          # directory analysis
pnpm search:tokens path/to/file.cjs     # single file analysis

# Semantic + text hybrid search (concept discovery, ranked results)
# Repeated/similar queries served from cache (~5ms hit vs ~800ms miss)
pnpm search:code "authentication logic"
pnpm search:code "export class User"

# One-shot search + compress + dedup pipeline (for large context tasks)
pnpm search:compress "how does routing work"

# Get file content with line numbers
pnpm search:file src/auth.ts 1 50

# Cache observability (daemon must be running)
pnpm search:code --cache-stats          # view hits, misses, entries
pnpm search:code --cache-clear          # flush cached results

pnpm search:structure — ファイルやコードの場所を把握する

編集、リファクタリング、オンボーディングの作業を始める前に、必ず最初に実行してください。 次の情報を含む全体像を把握できます。

1. ディレクトリツリー — 最大 3 階層のフォルダー構造（node_modules、.git を除く）
2. エントリーポイント — すべての ESM export および CJS module.exports 宣言と、ファイル名・行番号の参照
3. 主要な依存関係 — インポート回数の多いモジュール（import と require の両方）とその数。次のように分類されます。
   • 📦 外部パッケージ（node:test、path、fs、child_process）
   • 📁 ローカルモジュール（最も多くインポートされている内部ファイル。アーキテクチャ上の要所です）
4. Mermaid 図 — 次の情報を含む依存関係の視覚的なグラフ
   • フォルダーごとのエクスポート数を示すディレクトリサブグラフ
   • 外部依存関係のサブグラフ
   • ハブノードとして強調表示された、最も多くインポートされているローカルモジュール

エージェントでの活用方法：

• 編集前：pnpm search:structure を実行し、変更するコードを担当するディレクトリを特定します
• 要所の特定：📁 のローカル依存関係のうち、件数が最も多いものは最も多くのモジュールとつながっています。そこを変更すると、最も広範囲に影響します
• エントリーポイントの特定：エクスポート一覧には、公開 API を公開するファイルが表示されます。まずはそこから読み始めてください
• アーキテクチャの把握：Mermaid 図から、最も相互に接続されているディレクトリがわかります
• リファクタリング前：依存関係の件数から、名前変更や移動によって影響を受けるファイル数がわかります

pnpm search:tokens [path] — コンテキストに収まる量を把握する

ファイルやディレクトリの読み取り方法を決める前に、必ず実行してください。 次の情報がわかります。

• ファイルごと、ディレクトリごとのトークン数の推定値（トークンあたり約4文字）
• ファイルを直接読み取るか、オフセット／上限を指定するか、代わりに search:code を使うかについての具体的なアドバイス
• 特別な対応が必要な最大サイズのファイル
• トークン数に基づくディレクトリのランキング — 優先的に調査するサブディレクトリを決められます

# Check a specific file
pnpm search:tokens .claude/lib/memory/lancedb-client-impl.cjs
# Output: Size: 41.1KB | Tokens: ~10.5K | Advice: △ MEDIUM — use Read with offset/limit

# Check a directory
pnpm search:tokens .claude/lib
# Output: 333 files, 2.0MB, ~527K tokens (too large to read all — use search:code)

# Check the whole project
pnpm search:tokens .
# Output: 12478 files, 61MB, ~16M tokens with per-directory breakdown

トークン数の目安：

• ✓ OK（8Kトークン未満）— ファイル全体を安全に Read できます
• △ MEDIUM（8～32K）— offset／limit パラメーターを指定して Read するか、search:file を使います
• ⚠ LARGE（32～100K）— ファイル全体を Read するより search:code を推奨します。対象箇所だけを読み取ってください
• ⚠ OVER（100K超）— search:code を使うか、context-compressor スキルを呼び出す必要があります

context-compressor を呼び出すタイミング：

• ディレクトリの合計が100Kトークンを超えていて、サブシステム全体を理解する必要がある場合
• ファイルが32Kトークンを超えていて、特定の行ではなく要約が必要な場合
• コンテキストウィンドウの上限を超えるプロンプトを作成する場合

リファクタリングの推奨事項 — 15Kトークンを超えるソースコードファイルについて、ツールが分割を推奨します。

pnpm search:tokens .claude/hooks/routing
# Output includes:
#   ✂ REFACTOR RECOMMENDED: user-prompt-unified.core.cjs (18.2K tokens)
#     Split into ~3 modules of ~8K tokens each:
#       user-prompt-unified.cjs          — thin facade (re-exports)
#       user-prompt-unified-impl.cjs     — main logic
#       user-prompt-unified-helpers.cjs  — extracted helpers

これはソースコードファイル（.js、.cjs、.mjs、.ts、.py）にのみ適用され、データファイルや設定ファイルには適用されません。このパターンは、コードベースに既存の分割方法がある場合にそれに従います（例：routing-table.cjs → routing-table-data.cjs、index-manager.cjs → index-manager-operations.cjs）。

pnpm search:compress "query" — 検索と圧縮をまとめて実行

search:tokens の結果、あるトピックが32Kトークンを超えていて、圧縮した要約が必要な場合に使います。

次の一連の処理を1つのコマンドにまとめています。

1. ハイブリッド検索で、クエリに関連するファイルを見つけます
2. 実際のファイル内容を読み取ります（ファイルパスだけではありません）
3. コーパスのサイズに応じて圧縮率を適応的に設定します（小規模なら0.8、大規模なら0.1）
4. 証拠考慮モードで Python エンジンを使って圧縮します
5. 抽出した知見を既存のメモリー（patterns.json、gotchas.json）と照合し、重複を除きます
6. 圧縮したコンテキストと分類済みのメモリーレコードを含む JSON を出力します

pnpm search:compress "how does the routing system work"
# Returns JSON:
# {
#   "ok": true,
#   "search": { "query": "...", "hits": 20 },
#   "compression": { "mode": "evidence_aware", "skeletonRatio": 0.5 },
#   "memoryRecords": { "patterns": [...], "gotchas": [...], "issues": [...], "decisions": [...] },
#   "dedupStats": { "total": 24, "kept": 18, "filtered": 6 }
# }

主な機能：

• 適応型圧縮：小規模なコーパス（8Kトークン未満）では80％を保持し、大規模なコーパス（100Kトークン超）では10％のみを保持します
• メモリーの重複排除：すでにメモリーシステムにあるパターンや注意点は再保存しません
• 証拠による制御：クエリで十分な一致が見つからない場合に中断するには、--fail-on-insufficient-evidence を使います

自動最適化（操作不要）

これらの機能は、コマンドを実行しなくてもバックグラウンドで動作します。

クエリーキャッシュ — 繰り返し実行する search:code クエリや、意味的に類似したクエリは、メモリー内キャッシュから返されます（約5ms、キャッシュなしでは約800ms）。キャッシュではコサイン類似度（しきい値：0.95）を使うため、「routing system」と「how routing works」は同じキャッシュ結果を共有します。エントリーの有効期限は5分です。キャッシュはデーモンプロセス内に保持されるため、クエリ間で維持されます。

BM25 の自動更新 — ファイルを編集すると、BM25 テキストインデックスが差分更新されます（ファイルあたり約10ms）。そのため、code:index:reindex を実行しなくても、search:code には常に最新の変更が反映されます。更新されるのはテキストインデックスのみです。セマンティック埋め込みを更新するには、インデックス全体を再構築する必要があります。

キャッシュの可観測性：

pnpm search:code --cache-stats    # entries, hits, misses, hit rate
pnpm search:code --cache-clear    # flush all cached results

検索モードの契約（決定論的）

モード	使用するタイミング	レイテンシ	出力
pnpm search:structure	最初のステップ：プロジェクトの構成を把握し、編集箇所を探す	高速	ディレクトリツリー + エクスポート + 依存関係 + Mermaid
pnpm search:tokens [path]	読む前：ファイル／ディレクトリがコンテキストに収まるか確認する	高速	トークン数の推定 + リファクタリングのアドバイス
pnpm search:code "query"	概念の調査、未知のパスの検索。自動キャッシュ（再実行時は約5ms）	約0.2～0.8秒（初回）、約5ms（キャッシュ時）	関連度順のコンパクトな上位20件
pnpm search:compress "query"	大きなコンテキストの場合：検索 + 圧縮 + 重複排除を一度に実行	約2～5秒	JSON：圧縮されたコンテキスト + メモリレコード
rg -F "literal"	編集前の正確なシンボル／リテラル検索とアンカー確認	最速（約35ms）	すべての一致箇所（順位付けなし）
Grep（組み込み）	監査での網羅的なパターン検索	高速	コンテキスト付きのすべての一致箇所

必須の選択手順：

• 最初に：pnpm search:structure を実行して全体を把握します。ディレクトリ構成と依存関係の集中箇所を確認します。
• サイズを確認：ファイルを読む前に pnpm search:tokens を実行し、ファイルがコンテキストに収まるか確認します。
• 次に：概念を調査するために pnpm search:code を実行し、タスクに関連するファイルを探します。繰り返しのクエリは自動的にキャッシュされます。
• 大きなコンテキストの場合：広いトピックについて圧縮された理解が必要なときは pnpm search:compress を使用します。検索 + 適応型圧縮 + メモリの重複排除を1つのコマンドにまとめます。
• 編集前に：rg -F で正確なアンカーを検証し、想定した場所にシンボル／関数があることを確認します。
• 監査では：網羅的な検索には Grep（組み込み）を使用します。上位N件ではなく、すべての一致箇所が必要です。
• BM25 テキストインデックスはファイルの編集時に自動更新されます（手動操作は不要です）。
• fzf は人間が介在するワークフローでは引き続き任意で使用できます。自動化では必須にしないでください。

編集前に場所を特定する（エージェントに必須のワークフロー）

ファイルを書き込む、または編集する前に、エージェントは必ずその場所を特定してください。手当たり次第の編集はトークンを浪費し、エラーの原因になります。

ステップ1 — 全体を把握する（タスクごとに1回実行）：

pnpm search:structure

出力を読み、以下を把握します：

• どのディレクトリがあり、それぞれに何が含まれているか
• 最も多くインポートされているモジュール（カウント数の多いローカル依存関係 📁）
• パブリック API の場所（エントリーポイント一覧）

ステップ2 — トークン予算を確認する（ファイルを読む前）：

# Is this file safe to Read in full, or do I need search:code?
pnpm search:tokens .claude/lib/memory/lancedb-client-impl.cjs
# Output: △ MEDIUM (10.5K tokens) — use Read with offset/limit

# How big is this directory? Can I read all files?
pnpm search:tokens .claude/lib/routing
# If >32K total → use search:code for discovery, don't try to read everything

ステップ3 — 調査する（サブタスクごと）：

# Find files related to your task concept
pnpm search:code "hook validation pre-tool"

これにより、概念との関連性が高いファイルが順位付けされて返されます。ファイルパスを記録してください。

ステップ4 — 場所を特定する（編集のたびに、その前に実行）：

# Confirm exact symbol location with line numbers
rg -F "validateHookInput" -g "*.cjs" -n

# Read the file to understand context (use offset/limit for MEDIUM+ files)
pnpm search:file .claude/lib/utils/hook-input.cjs 1 50

ステップ5 — 影響範囲を確認する（リファクタリングの前）：

# How many files import the module you're about to change?
rg -F "hook-input.cjs" -g "*.cjs" -c
# If 40+ files import it, consider backward-compatible changes

このワークフローにより、以下を防止できます：

• コンテキストに収まらない大きなファイルにトークンを浪費する（まずトークン数を確認）
• 間違ったファイルを編集する（異なるディレクトリに同名のファイルがある場合があります）
• リファクタリング中に呼び出し箇所を見落とす（rg -c で正確な数を確認）
• 影響範囲を把握せずに、広くインポートされているモジュールを壊す
• コンテキスト圧縮を不必要に引き起こす（事前にサイズを把握）

fzf による対話的な絞り込み（オペレーター UX）

結果セットが大きい場合は、fzf を使って rg／rga の出力を対話的に絞り込みます。

# rg + fzf + file preview
rg --line-number --no-heading --color=always "auth|token|session" . \
  | fzf --ansi --delimiter ":" \
    --preview "bat --color=always --style=numbers --highlight-line {2} {1}"

# rga (documents/archives) + fzf
rga --line-number --no-heading --color=always "invoice|receipt|policy" . \
  | fzf --ansi --delimiter ":" \
    --preview "bat --color=always --style=numbers --line-range=:300 {1}"

高度な対話型 ripgrep ランチャーのパターン：

: | rg_prefix='rg --column --line-number --no-heading --color=always --smart-case' \
  fzf --ansi --disabled \
      --bind 'start:reload:$rg_prefix ""' \
      --bind 'change:reload:$rg_prefix {q} || true'

使用上のルール：

• オペレーターによる選択／絞り込みには fzf を使い、検索バックエンドの代替としては使わないでください。
• エージェントの検索／ランキングワークフローでは、pnpm search:code をデフォルトとして維持してください。
• 対話的なトリアージや手動での結果選択には、rg／rga と fzf を使ってください。

構造化＋対話型ワークフロー（人によるトリアージ）：

# Structural candidates (ast-grep)
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches .

# Narrow candidates interactively
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches . \
  | fzf --ansi --delimiter ":" \
    --preview "bat --color=always --style=numbers --line-range=:220 {}"

仕組み

1. pnpm code:index:reindex が BM25 テキストインデックスと LanceDB ベクトル埋め込みを構築します
2. 埋め込みの生成は分離されたサブプロセスで実行されます（利用可能な場合は GPU で高速化されます）
3. ONNX のネイティブメモリリークを回収するため、サブプロセスは 50 バッチごとに再起動されます
4. search:code はまずクエリキャッシュを確認し（ヒット時は約 5ms）、ミスした場合は BM25 インデックスとベクトルインデックスを検索します
5. RRF がテキストとセマンティックのランキングを統合し、単一の順序付き結果セットを作成します
6. 今後の類似クエリに備えて結果がキャッシュされます（コサイン類似度 > 0.95 でキャッシュヒット）
7. 編集後のフックが BM25 テキストインデックスを増分更新します（1 ファイルあたり約 10ms）
8. search:compress は検索、適応型圧縮、メモリの重複排除を 1 つのパイプラインに統合します

設定

# Semantic search (default: on after running code:index:reindex)
HYBRID_EMBEDDINGS=on

# Embedding engine (fastembed recommended for speed + GPU support)
LANCEDB_EMBEDDING_MODE=fastembed

# Subprocess isolation for ONNX memory safety (default: on)
EMBED_SUBPROCESS=on

# Query cache (auto-caches repeated/similar queries)
SEARCH_CACHE_ENABLED=on            # Kill switch: set to off to disable
SEARCH_CACHE_TTL_MS=300000          # Cache TTL: 5 minutes
SEARCH_CACHE_SIMILARITY=0.95        # Cosine threshold for semantic cache hit

# BM25 incremental update after file edits
BM25_INCREMENTAL_UPDATE=on          # Kill switch: set to off to disable

# Disable semantic search (text-only, fastest, no index needed)
# HYBRID_EMBEDDINGS=off

# Daemon transport for repeated queries (cache lives here)
HYBRID_SEARCH_DAEMON=on
HYBRID_DAEMON_PREWARM=true
HYBRID_DAEMON_IDLE_MS=600000

# Query cache (caches repeated/similar queries by embedding similarity)
SEARCH_CACHE_ENABLED=on          # set to off to disable
SEARCH_CACHE_TTL_MS=300000       # cache entry TTL (5 min)
SEARCH_CACHE_SIMILARITY=0.95     # cosine threshold for cache hit

# BM25 incremental update after file edits
BM25_INCREMENTAL_UPDATE=on       # set to off to disable

デーモン＋事前ウォームアップ手順書

# Start, verify, prewarm
pnpm search:daemon:start
pnpm search:daemon:status
pnpm search:daemon:prewarm

# Search (daemon path)
pnpm search:code "authentication logic"

# Stop daemon
pnpm search:daemon:stop

このリポジトリで想定されるレイテンシー：

• デーモンの初回クエリ（事前ウォームアップなし）：平均約 1.35 秒
• 事前ウォームアップ後の初回クエリ：平均約 0.40 秒
• デーモンへのウォーム状態での反復クエリ：約 0.18～0.19 秒
• ダイレクトモード（HYBRID_SEARCH_DAEMON=off）：CLI 呼び出しの反復時、平均約 0.73 秒

インデックス構築のパフォーマンス

指標	GPU 使用時（RTX 4070）	CPU のみ
インデックス作成時間（2843 ファイル）	約 12 分	約 17 分
メインプロセスのメモリ使用量	約 200MB	約 200MB
サブプロセスのメモリ使用量（分離時）	約 500MB	約 300MB
必要なヒープ割り当て	4GB	4GB
ディスク上のインデックスサイズ	約 6MB（BM25）＋約 10MB（ベクトル）	同じ

実測パフォーマンスと出力（このリポジトリ）

このリポジトリで同じ 5 つのクエリを使用した結果：

モード	平均レイテンシー	平均出力バイト数	最適な用途
pnpm search:code（HYBRID_EMBEDDINGS=off）	約 227ms	約 461 バイト	簡潔な出力による高速な検索
pnpm search:code（HYBRID_EMBEDDINGS=on）	約 734ms	約 512 バイト	セマンティック／概念クエリ
rg のリテラル検索	約 35ms	約 2478 バイト	正確なシンボル／リテラルの検索

解釈：

• 正確なリテラル／シンボルの検索では、rg が最速です
• ハイブリッド検索は出力ペイロードが大幅に小さくなります（多くの場合、トークンの使用量も抑えられます）
• 埋め込みによりセマンティック検索の再現率は向上しますが、レイテンシーが増加します

選択の目安（実用編）

次の場合は pnpm search:code を使ってください：

• クエリが概念的なもの／自然言語の場合（"auth flow for refresh tokens"）
• エージェントのプロンプト向けに、ランキング済みの結果と簡潔なコンテキストが必要な場合
• デフォルトで出力を少なくしたい場合

次の場合は rg をそのまま使ってください：

• クエリが正確なシンボル／リテラルの場合（TaskUpdate(、HybridLazyIndexer、正確なエクスポート名）
• 可能な限り高速な検索が必要な場合
• 高度な正規表現／PCRE2 の動作が必要な場合

ファイルサイズ別の測定結果（このリポジトリ）

サンプルサイズ：小さいファイル4件（0.5～5KB）、大きいファイル4件（30～109KB）、リテラルトークン検索。

区分	search:code オフ	search:code オン	rg_repo	rg_file
小さいファイル	~230ms / ~2707B	~600ms / ~2965B	~34ms / ~17075B	~15ms / ~1156B
大きいファイル	~228ms / ~2354B	~475ms / ~2847B	~35ms / ~17811B	~15ms / ~6564B

要点：

• rg_file は最速で、対象を絞ったファイル単位の確認に最適です。
• rg_repo はリポジトリ全体のリテラル検索では引き続き最速ですが、出力ペイロードはかなり大きくなります。
• search:code はファイルサイズによるレイテンシーの変動が少なく、プロンプトでの使用時に出力量も通常は少なめです。

実際のシナリオ別プレイブック（検証済みのパターン）

次のシナリオパターンを使って、適切な検索方法をすばやく選びましょう。

シナリオ1：インシデントの初期調査（根本原因が不明）

目標：コンテキストを過剰に消費せずに、本番環境の症状に関係しそうな箇所をすばやく見つけます。

# 1) Start broad and semantic
pnpm search:code "task status not updating after completion"

# 2) Pivot to exact symbol checks once candidates appear
pnpm search:code "TaskUpdate("

パターン：

• まず search:code で意図レベルの再現率を高めます。
• 候補ファイルが特定できたら、リテラル検索やシンボル検索で絞り込みます。

シナリオ2：正確な場所をすばやく検索（識別子がわかっている）

目標：定義や使用箇所をできるだけすばやく正確に特定します。

# Repo-wide exact literal (stable example in this repo)
rg -F "TaskUpdate(" -g "*.cjs" -g "*.js" -g "*.ts" .

# Single-file exact lookup (fastest path)
rg -F "spawnSync" .claude/skills/skill-creator/scripts/create.cjs

パターン：

• 正確なシンボル検索には、特に大きなファイルや既知のパスに対して、未加工の rg -F を使います。

シナリオ3：安全なリファクタリングの準備

目標：名前変更や動作変更の前に、呼び出し箇所をすべて列挙し、影響範囲を評価します。

# 1) Check blast radius — how many files import this module?
pnpm search:structure
# Look at 📁 local deps: "📁 router-state (22)" = 22 files affected by changes

# 2) Gather broad callsites with semantic search
pnpm search:code "TaskUpdate completed status workflow"

# 3) Get EXACT callsite inventory (every match, not ranked)
rg -F "TaskUpdate(" -g "*.cjs" -g "*.js" -g "*.ts" -c
# Shows count per file — plan your edits across all files

# 4) Verify the specific lines before editing
rg -F "TaskUpdate(" -g "*.cjs" -n -C 2

パターン：

• まず search:structure で依存関係の数（影響範囲）を確認します。
• 見落とす可能性のある意味的なバリエーションを見つけるために、ハイブリッド検索を使います。
• ファイルごとの正確な呼び出し箇所数を確認するには、未加工の rg -c を使います。
• 編集前に行番号と前後のコンテキストを確認するには、未加工の rg -n -C 2 を使います。

シナリオ4：セキュリティ監査の一斉検索

目標：リスクのあるパターンを検出し、信頼度の高い一致を正確に確認します。

網羅的な一斉検索（監査）には、rg または Grep（組み込み）を主なツールとして使用してください。 ハイブリッド検索は順位付けされた上位N件の結果を返すため、発見には適していますが、一致箇所を見落とす可能性があります。 セキュリティ監査では、順位付けされたサンプルではなく、パターンの一致箇所をすべて確認する必要があります。

# EXHAUSTIVE sweep first (every match, not ranked)
rg -F "shell: true" -g "*.cjs" -g "*.js" -g "*.mjs"
rg -F "JSON.parse(" -g "*.cjs" -g "*.js" --no-heading
rg "eval\(|new Function\(" -g "*.cjs" -g "*.js"
rg -F "child_process" -g "*.cjs" -g "*.js"

# THEN use hybrid for concept discovery (find patterns you didn't think to grep for)
pnpm search:code "command injection shell execution security"
pnpm search:code "prototype pollution unsafe parsing"

# Verify specific findings with file-level rg
rg -F "exec(" .claude/lib/tools/standard-tools.cjs

パターン：

• 網羅性が重要な一斉検索（セキュリティ、コンプライアンス）には、rg／Grep を使います。
• grep すべきだと知らなかったパターンを見つける概念の発見には、ハイブリッド検索を使います。
• セキュリティに関する判断で、ハイブリッド検索の上位N件の結果だけに頼らないでください。

シナリオ5：アーキテクチャの把握（新しいコントリビューター／エージェント）

目標：構造を理解し、変更を加える場所を把握します。

# 1) Get the full project map (directory tree + exports + deps + Mermaid)
pnpm search:structure

# From the output, you'll see:
#   - Directory tree: which folders exist and their nesting
#   - Entry points: which files export APIs (with file:line)
#   - Top dependencies: most-imported local modules (📁) = architectural hotspots
#     e.g. "📁 memory-manager.cjs (56)" means 56 files import it — high blast radius
#   - Mermaid diagram: visual module graph

# 2) Drill into subsystems by concept
pnpm search:code "routing guard task lifecycle"
pnpm search:code "memory scheduler session context"

# 3) Once you find candidate files, read them
pnpm search:file .claude/lib/routing/router-state.cjs 1 50

# 4) Before editing, confirm exact locations with rg
rg -F "resetToRouterMode" -g "*.cjs" -n

パターン：

• まず search:structure を使い、作業に着手する前に全体像を把握します。
• 件数の多い 📁 ローカル依存関係を確認します。変更が最も広い範囲に影響するモジュールです。
• search:code を使って、対象の概念に関連するファイルを見つけます。
• search:file を使って、特定のファイルを行番号付きで読みます。
• 編集前に正確なシンボルの位置を確認するには、rg -F を使います。

シナリオ6：コードベースの監査／詳細調査

目標：コードベースを体系的に監査し、バグ、セキュリティ上の問題、デッドコードを見つけます。

# 1) Map the project — identify architectural hotspots FIRST
pnpm search:structure
# Key things to note from the output:
#   - 📁 local deps with high counts = audit priority (most connected = most risk)
#   - Entry points list = public API surface to review
#   - Directory tree = scope of what needs auditing

# 2) Exhaustive pattern sweeps with rg (need ALL matches, not top-N)
rg -F "JSON.parse(" -g "*.cjs" -g "*.js" --no-heading
rg -F "shell: true" -g "*.cjs" -g "*.js"
rg "eval\(|new Function\(" -g "*.cjs" -g "*.js"
rg "DEPRECATED|LEGACY|WARN" -g "*.cjs" -g "*.js" -g "*.mjs"
rg -F "catch" -A1 -g "*.cjs" | rg "^\s*\}"  # empty catch blocks

# 3) Concept discovery for patterns you didn't think to grep
pnpm search:code "prototype pollution unsafe parsing"
pnpm search:code "race condition concurrent file write"
pnpm search:code "hardcoded secret credential password"

# 4) Cross-reference: find what calls a specific module
pnpm search:code "routing-table-intent"
rg -F "standard-tools" -g "*.cjs" -c  # exact import count per file

# 5) Check for dead code: find exports that are never imported
# Compare entry points from search:structure against rg import counts
rg -F "orchestrator-tool.cjs" -g "*.cjs" -c  # 0 results = dead module

パターン：

• まず search:structure で注目箇所を特定します（インポート数の多いモジュールを監査の優先対象にします）。
• 網羅的な一斉検索（セキュリティ、デッドコード、パターンマッチング）には、rg／Grep を使います。
• 概念の発見（grep すべきだと知らなかったものの特定）には、search:code を使います。
• search:structure のエントリーポイントと rg のインポート数を照合して、デッドコードを見つけます。
• 監査の網羅性を確保するために、ハイブリッド検索だけに頼らないでください。ハイブリッド検索が返すのは順位付けされた上位N件であり、すべての一致箇所ではありません。

シナリオ7：トークン数に制約のあるエージェントのワークフロー

目標：検索品質を保ちながら、プロンプト／コンテキストの肥大化を最小限に抑えます。

# Default: semantic search on (compact ranked output, good for agents)
pnpm search:code "workflow task completion guard"

# For fastest possible response when you know exact terms
HYBRID_EMBEDDINGS=off pnpm search:code "TaskUpdate completed"

# For intent-heavy queries where exact terms are unknown
pnpm search:code "why does the task get stuck after agent finishes"

パターン：

• デフォルトでは HYBRID_EMBEDDINGS=on を使います（コンパクトな順位付け済み出力は、すでにトークン効率に優れています）。
• 正確なキーワード一致で十分で、速度が重要な場合に限り、HYBRID_EMBEDDINGS=off で上書きします。
• ハイブリッド検索の出力は通常、未加工の rg 出力より小さくなります（すべての一致箇所ではなく、順位付けされた上位N件を返すためです）。

再利用可能な検索パターン

• 概念検索："authentication flow refresh token validation"
• 混合検索："TaskUpdate completed status"
• 完全一致検索："TaskUpdate("（速度が重要な場合は rg -F を優先してください）
• 構造検索：大規模な編集の前に pnpm search:structure を使用してください
• ファイルの詳細検索：pnpm search:file <path> <startLine> <endLine>

以下の場合に限り、生の ripgrep（下記）を使用してください：

• 高度な PCRE2 正規表現パターン（先読み／後読み）
• search:code がサポートしていないカスタムのファイルタイプフィルタリング
• 他の CLI ツールとのパイプライン連携

概要

このスキルでは、@vscode/ripgrep npm パッケージを介して ripgrep（rg）を利用できます。このパッケージは、お使いのプラットフォーム（Windows、Linux、macOS）に適したバイナリを自動的にダウンロードします。最新の JavaScript／TypeScript プロジェクトに対応したファイルタイプのサポートも強化されています。

バイナリのソース：@vscode/ripgrep npm パッケージ（クロスプラットフォーム、自動インストール）

• Windows、Linux、macOS のバイナリを自動的に処理します
• 手動でバイナリを管理する必要はありません

任意の設定：bin/.ripgreprc（存在する場合、自動的に使用されます）

用途の使い分け

ツール	最適な用途	トレードオフ
pnpm search:code	概念の発見、ランキングされた結果、エージェントのワークフロー	上位 N 件をランキング表示するため網羅的ではありません。セマンティック検索にはインデックスが必要です
組み込みの Grep ツール	網羅的なパターン検索、監査、正確な件数	すべての一致箇所を返すため、トークン出力が増えます
Bash 経由の生の rg	PCRE2 正規表現、パイプライン連携、.ripgreprc のタイプ	Bash ツールが必要です。生の出力が大きくなります
組み込みの Glob ツール	名前のパターンによるファイル検索	コンテンツ検索には対応していません

監査やセキュリティ検査には：組み込みの Grep を優先してください。ランキングされた上位 N 件ではなく、一致箇所をすべて返します。必要なのはランキングではなく網羅性です。

発見やオンボーディングには：pnpm search:code を優先してください。コンパクトでランキングされた出力、セマンティックな理解、低いトークン消費が特長です。

編集前の正確なシンボル検索には：生の rg -F を優先してください。最速で、結果が決定的です。

クイックスタートコマンド

基本的な検索

# Search for pattern in all files
node .claude/skills/ripgrep/scripts/search.mjs "pattern"

# Search specific file types
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tjs
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tts

# Case-insensitive search
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -i

# Search with context lines
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -C 3

クイック検索のプリセット

# Search JavaScript files (includes .mjs, .cjs)
node .claude/skills/ripgrep/scripts/quick-search.mjs js "pattern"

# Search TypeScript files (includes .mts, .cts)
node .claude/skills/ripgrep/scripts/quick-search.mjs ts "pattern"

# Search all .mjs files specifically
node .claude/skills/ripgrep/scripts/quick-search.mjs mjs "pattern"

# Search .claude directory for hooks
node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "pattern"

# Search .claude directory for skills
node .claude/skills/ripgrep/scripts/quick-search.mjs skills "pattern"

# Search .claude directory for tools
node .claude/skills/ripgrep/scripts/quick-search.mjs tools "pattern"

# Search .claude directory for agents
node .claude/skills/ripgrep/scripts/quick-search.mjs agents "pattern"

# Search all files (no filter)
node .claude/skills/ripgrep/scripts/quick-search.mjs all "pattern"

よく使うパターン

ファイルタイプ検索

# JavaScript files (includes .js, .mjs, .cjs)
rg "function" -tjs

# TypeScript files (includes .ts, .mts, .cts)
rg "interface" -tts

# Config files (.yaml, .yml, .toml, .ini)
rg "port" -tconfig

# Markdown files (includes .md, .mdc)
rg "# Heading" -tmd

高度な正規表現

# Word boundary search
rg "\bfoo\b"

# Case-insensitive
rg "pattern" -i

# Smart case (case-insensitive unless uppercase present)
rg "pattern" -S  # Already default in .ripgreprc

# Multiline search
rg "pattern.*\n.*another" -U

# PCRE2 lookahead/lookbehind
rg -P "foo(?=bar)"        # Positive lookahead
rg -P "foo(?!bar)"        # Negative lookahead
rg -P "(?<=foo)bar"       # Positive lookbehind
rg -P "(?<!foo)bar"       # Negative lookbehind

フィルタリング

# Exclude directories
rg "pattern" -g "!node_modules/**"
rg "pattern" -g "!.git/**"

# Include only specific directories
rg "pattern" -g ".claude/**"

# Exclude specific file types
rg "pattern" -Tjs  # Exclude JavaScript

# Search hidden files
rg "pattern" --hidden

# Search binary files
rg "pattern" -a

コンテキストと出力

# Show 3 lines before and after match
rg "pattern" -C 3

# Show 2 lines before
rg "pattern" -B 2

# Show 2 lines after
rg "pattern" -A 2

# Show only filenames with matches
rg "pattern" -l

# Show count of matches per file
rg "pattern" -c

# Show line numbers (default in .ripgreprc)
rg "pattern" -n

高度な PCRE2 パターン

高度な機能を使うには、-P で PCRE2 モードを有効にします。

先読みと後読み

# Find "error" only when followed by "critical"
rg -P "error(?=.*critical)"

# Find "test" not followed by ".skip"
rg -P "test(?!\.skip)"

# Find words starting with capital after "Dr. "
rg -P "(?<=Dr\. )[A-Z]\w+"

# Find function calls not preceded by "await "
rg -P "(?<!await )\b\w+\("

後方参照

# Find repeated words
rg -P "\b(\w+)\s+\1\b"

# Find matching HTML tags
rg -P "<(\w+)>.*?</\1>"

条件式

# Match IPv4 or IPv6
rg -P "(\d{1,3}\.){3}\d{1,3}|([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}"

他のツールとの連携

fzf との連携（対話型検索）

# Search and interactively select file
rg --files | fzf

# Search pattern and open in editor
rg "pattern" -l | fzf | xargs code

vim との連携

# Set ripgrep as grep program in .vimrc
set grepprg=rg\ --vimgrep\ --smart-case\ --follow

他のコマンドとのパイプライン

# Search and count unique matches
rg "pattern" -o | sort | uniq -c

# Search and replace preview
rg "old" -l | xargs sed -i 's/old/new/g'

パフォーマンスの最適化

大規模なコードベースでのヒント

1. ファイルタイプフィルターを使用する：-tjs はすべてのファイルを検索するより高速です
2. 大きなディレクトリを除外する：-g "!node_modules/**"
3. 可能であればリテラル文字列を使用する：-F "literal"（正規表現を無効にします）
4. 並列検索を有効にする：Ripgrep はデフォルトですべてのコアを使用します
5. .gitignore を使用する：Ripgrep は .gitignore を自動的に尊重します

ベンチマーク

Ripgrep は通常、次のとおりです。

• grep より 10～100 倍高速
• ag（The Silver Searcher）より 5～10 倍高速
• git grep より 3～5 倍高速

カスタム設定

bin/.ripgreprc にある任意の .ripgreprc ファイル（存在する場合）には、次の内容が含まれます。

# Extended file types
--type-add=js:*.mjs
--type-add=js:*.cjs
--type-add=ts:*.mts
--type-add=ts:*.cts
--type-add=md:*.mdc
--type-add=config:*.yaml
--type-add=config:*.yml
--type-add=config:*.toml
--type-add=config:*.ini

# Default options
--smart-case
--follow
--line-number

フレームワーク固有のパターン

.claude ディレクトリの検索

# Find all hooks
rg "PreToolUse\|PostToolUse" .claude/hooks/

# Find all skills
rg "^# " .claude/skills/ -tmd

# Find agent definitions
rg "^name:" .claude/agents/ -tmd

# Find workflow steps
rg "^### Step" .claude/workflows/ -tmd

Agent Studio の一般的な検索

# Find all TaskUpdate calls
rg "TaskUpdate\(" -tjs -tts

# Find all skill invocations
rg "Skill\(\{" -tjs -tts

# Find all memory protocol sections
rg "## Memory Protocol" -tmd

# Find all BLOCKING enforcement comments
rg "BLOCKING|CRITICAL" -C 2

</execution_process>

<best_practices>

1. ファイルタイプフィルターを使用する（-tjs、-tts）と検索が速くなります
2. .gitignore のパターンを尊重する（デフォルトで自動適用）
3. 大文字・小文字を区別しない検索にはスマートケースを使用する（設定でデフォルト）
4. PCRE2 は必要な高度な機能がある場合にのみ有効にする（-P）
5. 大きなディレクトリは除外する（-g "!node_modules/**"）
6. パターンに正規表現が含まれない場合はリテラル検索を使用する（-F）
7. バイナリは @vscode/ripgrep npm パッケージによって自動的に管理されます
8. 一般的な .claude ディレクトリの検索にはクイック検索プリセットを使用する </best_practices>

**プロジェクト内のすべての TaskUpdate 呼び出しを検索する：**

node .claude/skills/ripgrep/scripts/search.mjs "TaskUpdate" -tjs -tts

セキュリティ関連のフックをすべて検索する：

node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "security|SECURITY" -i

PCRE2 で関数定義を検索する：

node .claude/skills/ripgrep/scripts/search.mjs -P "^function\s+\w+\(" -tjs

</usage_example>

バイナリの管理

検索スクリプトでは @vscode/ripgrep npm パッケージを使用しており、次の処理が自動的に行われます。

• 使用しているプラットフォーム（Windows、Linux、macOS）を検出します
• pnpm install 中に適切なバイナリをダウンロードします
• すべてのアーキテクチャ（x64、ARM64 など）に対応します

手動でバイナリを管理する必要はありません。すべて npm パッケージが自動的に処理します。

関連スキル

• grep - Claude Code 組み込みの grep（よりシンプルで、機能は少なめ）
• glob - ファイルパターンの照合

絶対遵守事項

1. 必ず編集タスクの前に最初に pnpm search:structure を実行し、状況を把握してください。ディレクトリ構成やインポートが集中する箇所を理解せずに編集すると、呼び出し箇所を見落としたり、影響範囲について予期せぬ問題が発生したりします。
2. セキュリティ監査には、順位付けされた上位 N 件のハイブリッド検索結果を絶対に使用しないでください。 監査では網羅性が重要です。順位付けされたサンプルではなく、rg または組み込みの Grep を使用して一致箇所をすべて取得してください。
3. コードを編集する前に、rg -F でシンボルのアンカーを必ず正確に検証してください。 意味的な一致だけに基づいて編集すると、名前が似た関数を見落とし、誤ったファイルを編集する原因になります。
4. 自動化またはエージェントのワークフローで、fzf をブロッキング依存関係に絶対にしないでください。 インタラクティブな選択はオペレーター向けの UX に限ります。無人で実行するエージェントのフローは、非インタラクティブかつ再現可能である必要があります。
5. リポジトリ全体の検索では、必ずファイルタイプフィルターまたはパスの glob で範囲を絞ってください。 範囲を絞らない検索は、無関係な一致でコンテキストを埋め尽くし、トークンコストを増加させます。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
search:structure を実行せずに編集タスクを開始する	ディレクトリ構成の知識がないと、誤ったファイルを編集したり、呼び出し箇所を見落としたりします	まず必ず pnpm search:structure を実行し、ディレクトリ階層とインポートが集中する箇所を把握します
セキュリティ監査の網羅性を確保するためにハイブリッド検索を使う	ハイブリッド検索で返されるのは順位付けされた上位 N 件であり、すべての一致ではありません。セキュリティ監査にはすべての事例が必要です	セキュリティの一斉調査には（網羅的な）rg／Grep を使い、概念の発見にのみハイブリッド検索を使います
rg -F でシンボルの正確な位置を確認せずにコードを編集する	セマンティック検索では名前が似たシンボルも一致します。誤った関数を編集しても気づかないままになります	コードを編集する前に rg -F "exact_symbol" を実行し、位置と呼び出し箇所の数を確認します
エージェントの自動化パイプラインで fzf を必須の手順にする	fzf には対話形式の入力が必要です。パイプラインがユーザーの選択待ちで停止すると、エージェントは処理を続行できません	fzf は任意のオペレーター専用ツールにし、エージェントのワークフローでは決定的な rg／search:code を使います
スコープを指定せずにリポジトリ全体を対象とする正規表現検索を実行する	大規模なモノレポでは数千件の一致が返され、トークンのコストが急増し、コンテキストがあふれます	リポジトリ全体を対象とするパターン検索の前に、必ず -g "*.cjs"、-tjs、またはパス引数で範囲を絞ります

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 見つかった問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提とします：メモリに記録されていなければ、起きていないのと同じです。