symdex-code-search

SymDex コード検索

ファイルを広範囲に閲覧する前に SymDex を使用してください。 ファイル全体をスキャンする代わりに、エージェントが必要とするコードだけを取得してトークンを節約できます。 SymDex は現在、Python、Go、Kotlin、Dart、Swift、HTML、CSS、Shell、Vue／Svelte のスクリプトブロック、Markdown の見出しと対応するフェンス付きコードブロックを含む、21 の言語サーフェスに対応しています。

現在の SymDex スナップショット

• パッケージバージョン：0.1.26
• 最新の公開タグ：v0.1.26
• MCP ツールサーフェス：21 ツール
• 言語カバレッジ：Android／Kotlin、Flutter／Dart、iOS／Swift、HTML、CSS 系スタイルシート、Shell、Vue／Svelte のスクリプトブロック、Markdown の見出し、対応するフェンス付きコードブロックを含む、21 の言語サーフェス
• ルート抽出：Python、JavaScript／TypeScript、Spring／Kotlin、Laravel、Gin スタイルの Go、ASP.NET、Rails／Sinatra、Phoenix、Actix
• 検索出力：トークン節約量を示す CLI の 1 行フッターと、MCP の roi、roi_summary、roi_agent_hint
• 品質出力：MCP の結果と CLI JSON には、信頼度、鮮度、パーサーモード、言語サーフェス、生成ファイルのヒント、埋め込みの利用可否を含む quality が含まれます
• コンテキストパック：CLI の symdex pack と MCP の build_context_pack は、より広範な機能に関する質問向けに、トークン予算に合わせた根拠のバンドルを作成します
• セマンティックバックエンド：ローカルの sentence-transformers、Voyage、OpenAI 互換の /embeddings、Gemini、互換プロキシ
• ホスト型埋め込みのサポート：SYMDEX_EMBED_RPM と symdex index --lazy を使用すると、構造インデックスをフォアグラウンドで作成し、埋め込みをバックグラウンドで補完できます
• 埋め込みなしモード：symdex index --no-embed は、セマンティック埋め込み処理を完全にスキップします
• 監視の動作：デフォルトではメモリ使用量を抑えた構造の更新を行います。セマンティック埋め込みを継続的に更新する必要がある場合にのみ、symdex watch --embed を使用してください
• 状態モデル：デフォルトではグローバルな ~/.symdex を使用し、オプションで registry.json を含むワークスペースローカルの ./.symdex も使用できます
• Markdown のサポート：.md、.markdown、.mdx の見出しと対応するフェンス付きコードブロックが、ソースファイルとともにインデックス化されます

まず始める

1. SymDex CLI が新しいリリースを報告した場合は、長時間のセッションを始める前にアップグレードすることをおすすめします。
2. リポジトリ ID を確認してください。
3. リポジトリ ID がすでにわかっている場合は、スコープを指定するすべてのツール呼び出しで repo を渡してください。
4. リポジトリ ID がわからない場合は、list_repos を呼び出し、現在のワークツリーに該当するものを選んでください。
5. get_index_status(repo) で鮮度を確認してください。
6. 現在のワークツリーがインデックス化されていない場合は、index_folder(path=".") を呼び出してください。
7. ワークスペースにすでに .symdex がある場合は、それを意図されたローカルの SymDex 状態として扱い、再利用してください。
8. タスクの残りの作業では、返された repo ID を再利用してください。

SymDex が利用できない場合、またはインデックス化に失敗した場合は、その旨を明確に伝え、必要な場合に限って通常のファイル読み取りに切り替えてください。

基本ルール

• まず検索してください。
• repo がわかっている場合は、常に渡してください。
• 機能の仕組み、ドキュメント、API、バグ調査などの幅広い質問では、多数の個別検索を行う前に build_context_pack を使用してください。
• ファイル全体を読むより、get_symbol または get_file_outline を優先してください。
• 手作業で追跡する前に、コールグラフとルートのツールを使用してください。
• 大きな編集の後、またはワークツリーを切り替えた後は、get_index_status を再確認してください。
• ファイル全体を読むのは、編集時、未対応または生成されたコンテンツをレビューする場合、あるいは SymDex で答えが得られない場合に限ってください。
• コンテキストを広く読み込むのではなく、取得時のトークン数を抑えることを優先してください。
• 検索ツールが roi、roi_summary、または roi_agent_hint を返した場合は、トークンのおおよその節約量を回答で簡潔に伝えてください。
• 結果に基づいて推論する前に quality を確認してください。鮮度が高く、パーサーに基づいた信頼度の高い根拠を優先し、根拠が古い、生成されたもの、フォールバックテキスト、または埋め込みがない場合はユーザーに伝えてください。
• リポジトリがワークスペースローカルの SymDex 状態（./.symdex）を使用している場合は、同じインデックスが自動検出されるよう、そのワークスペース内で作業してください。
• symdex watch はデフォルトでメモリ使用量が少ないものとして扱ってください。ファイル変更時にセマンティック埋め込みを更新する必要がある場合に限り、--embed を指定してください。
• リクエスト制限が厳しいリモート埋め込みプロバイダーでは、長時間のフォアグラウンド埋め込み処理でエージェントのセッションを止める代わりに、symdex index --lazy を優先し、SYMDEX_EMBED_RPM を設定してください。

ツールの選択

必要なこと	ツール
現在のワークツリーをインデックス化する	index_folder
リポジトリを明示的に登録してインデックス化する	index_repo
名前で関数、クラス、メソッドを検索する	search_symbols
意図や動作からコードを検索する	semantic_search
文字列または正規表現に一致する箇所を検索する	search_text
クエリに沿ったエビデンスのセットを作成する	build_context_pack
1 つのシンボルのソースコードを正確に読む	get_symbol
ファイルを読む前に概要を取得する	get_file_outline
リポジトリのマップまたは概要を取得する	get_repo_outline または get_file_tree
あるシンボルを呼び出す箇所を追跡する	get_callers
あるシンボルが呼び出す対象を追跡する	get_callees
HTTP ルートを検索する	search_routes
リポジトリの最新状態を確認する	get_index_status
コードのメトリクスと言語の内訳を取得する	get_repo_stats
インデックスの一覧を表示する	list_repos
削除済みワークツリーのインデックスをクリーンアップする	gc_stale_indexes

典型的なフロー

1. リポジトリ ID と最新状態を確認します。
2. 必要に応じて index_folder でインデックス化します。
3. 機能、API、ドキュメント、バグ調査に関する幅広い質問では、build_context_pack から始めます。
4. 対象が絞られた検索では、search_symbols、semantic_search、または search_text から始めます。
5. get_symbol または get_file_outline で対象を絞り込みます。
6. コードの理解について主張する前に、返された項目の quality フィールドを確認します。
7. より詳しく分析するには、get_callers、get_callees、search_routes、または get_repo_stats を使用します。
8. SymDex で十分に正確な回答が得られない場合に限り、ファイルを直接読み取ります。

判断ガイド

• 「X はどこで定義されていますか？」 -> search_symbols
• 「これは何をしますか？」 -> semantic_search、続いて get_symbol
• 「この機能はどのように動作しますか？」 -> build_context_pack
• 「この API をドキュメント化する前に根拠を集める」 -> include=["routes", "docs", "tests"] を指定して build_context_pack
• 「これを使っているのは誰ですか？」 -> get_callers
• 「これは何を呼び出しますか？」 -> get_callees
• 「エンドポイントはどこですか？」 -> search_routes
• 「まずファイル構成を見せてください」 -> get_file_outline
• 「リポジトリ全体の概要を教えてください」 -> get_repo_outline または get_repo_stats
• 「インデックスは最新ですか？」 -> get_index_status

適切なトリガーフレーズ

• 「JWT を検証する関数を探してください」
• 「このルートハンドラーを呼び出しているのは誰ですか？」
• 「このファイルの概要を見せてください」
• 「Webhook ペイロードを解析するコードを検索してください」
• 「/api/checkout の HTTP ルートを探してください」
• 「何かを編集する前に、リポジトリの概要を教えてください」
• 「このバグの原因と思われるコードパスを探してください」
• 「呼び出し元と呼び出し先を通して、このロジックに一貫性があるか確認してください」
• 「この機能のコンテキストパックを作成してください」

バグとロジックの調査

SymDex はエビデンスの取得に使用し、それ自体を証明として扱わないでください。

1. 症状、ルート、関数、またはテキストの手掛かりから始めます。
2. バグが複数のシンボル、ルート、ドキュメント、またはテストにまたがる場合は、build_context_pack を使用します。
3. 正確なシンボル、ルート、呼び出し元のチェーン、呼び出し先のチェーン、関連ドキュメントを取得します。
4. quality.index_fresh、quality.confidence、quality.parser_mode、quality.is_generated、quality.has_embeddings を確認します。
5. エビデンスの質が低い場合は、バグだと主張する前に不足している情報を伝えます。
6. バグの仮説を示す際は、その根拠となる具体的なシンボル、ファイル、ルート、または呼び出し関係を明示します。

編集

コードを編集する必要がある場合は、次の手順に従います。

1. SymDex を使って、対象のシンボルまたはファイルの場所を正確に特定します。
2. そのファイルまたはシンボルの範囲だけを読みます。
3. 必要最小限の変更を加えます。

ウォッチとセマンティック検索

• symdex watch はデフォルトで、ローカルの埋め込みモデルを読み込まずに構造インデックスを更新します。
• セマンティック検索を常に最新の状態に保つ必要があるタスクの場合にのみ、symdex watch --embed を使用します。
• semantic_search に埋め込みがない場合は、search_symbols または search_text に切り替えるか、symdex[local]、Voyage、OpenAI互換、Gemini、またはその他のホスト型埋め込みバックエンドを有効にしてから再インデックスします。
• ホスト型モデルのレイテンシや RPM 制限により埋め込みに時間がかかる可能性がある場合は、symdex index --lazy を使用します。
• ワークスペースローカルの状態では、ウォッチャーのメタデータが ./.symdex に保存されるため、コマンドはそのワークスペースから実行するか、一致する --state-dir を指定してください。

必要な場合にのみ通常のブラウジングを使用する

• SymDex を利用できない。
• リポジトリがインデックス化されておらず、現在の環境ではインデックス化できない。
• 対象のファイルタイプがサポート対象外、または生成されたものである。
• シンボルレベルの応答では得られない周辺コンテキストが必要である。

出力チェックリスト

• リポジトリ ID を確認または特定した
• インデックスの鮮度を確認した
• 広範囲なファイル読み取りの前に SymDex ツールを選択した
• 複数ファイルにまたがる広範な質問ではコンテキストパックを使用した
• 可能な場合はファイル全体を読む前に、正確なシンボルまたはファイルの概要を使用した
• ロジックやバグに関する主張の前に品質メタデータを確認した
• SymDex で適切に回答できない場合にのみ、ファイルを直接読み取った