コードベースメモリ & グラフインテリジェンス (codebase-memory)

コードベースメモリ & グラフインテリジェンス (codebase-memory) は何をしますか？

このスキルは、codebase-memory MCPナレッジグラフを使用してコードの探索、検索、理解を行うためのエンジニアリング標準、運用手順、ツール使用契約を定義します。

---

コア不変条件: インデックスファーストプロトコル

[!CRITICAL] インデックスファースト不変条件: このワークスペースでは、アクティブなファイル編集中のディスクスラッシング、zstdシリアライゼーションのオーバーヘッド、システムスタッターを防ぐために、バックグラウンド監視による再インデックスは恒久的に無効化されています（auto_watch = false）。

したがって、エージェントはコードナレッジグラフに対する検索を実行する前に、必ずインデックスの鮮度を確認するか、オンデマンド再インデックス（index_repository）をトリガーしなければなりません。

シンボルの検索、モジュールの理解、バグの調査、リファクタリングの準備を任された場合は常に、検索呼び出しを行う前にインデックスファーストゲートを実行してください。

---

ツール階層: グラフファースト、グレップセカンド

コードの発見、ナビゲーション、レビューを行う際は、以下の優先順位階層に厳密に従ってください:

flowchart TD
    Task[コード発見 / 調査タスク] --> Freshness{インデックスは新鮮か?}
    Freshness -->|いいえ / 不明 / 編集後| Sync[index_repository mode: 'fast' または 'moderate']
    Freshness -->|はい| Strategy{クエリタイプ}
    Sync --> Strategy

    Strategy -->|シンボル / 関数 / インターフェース| SearchGraph[search_graph BM25 または semantic_query]
    Strategy -->|呼び出し元 / 呼び出し先 / 依存関係| TracePath[trace_path callers / callees]
    Strategy -->|変更の影響範囲| DetectChanges[detect_changes diff to impact set]
    Strategy -->|正確なソースコード| GetSnippet[get_code_snippet 正確な行]
    Strategy -->|システムレイヤーとハブモジュール| GetArch[get_architecture 高中心性ノード]
    Strategy -->|リテラル文字列 / 非コード / アセット| GrepFallback[search_code または run_command grep]

1. search_graph > テキストgrep: camelCase分割、ラベルブースト（関数+10、ルート+8、インターフェース+5）、ベクトル埋め込みによるBM25ランク構造検索。
2. trace_path > 手動ファイルホッピング: 呼び出し元と呼び出し先のグラフを瞬時にマルチホップ解決。
3. get_code_snippet > 大規模ファイルでのview_file: エージェントコンテキストを肥大化させることなく、シンボルの正確な宣言と本文を開始行/終了行と呼び出し元カウントとともに取得。
4. detect_changes > 手動差分検査: git diff（since: "HEAD~1"、base_branch: "main"）をその推移的な影響範囲に直接マッピング。
5. grepフォールバック: 以下の場合にのみ search_code または run_command（git grep、rg）を使用:
   • マークダウン（.md）、設定（.json）、スタイルシート（.css）内のリテラルテキスト。
   • index_status で parse_partial の下に明示的にフラグが立てられた行範囲。
   • .cbmignore により設計上除外されたファイル。

---

標準操作ワークフロー

ステップ 1: インデックス同期ゲート（必須の最初のアクション）

検索クエリを発行する前に、プロジェクト名を特定し、グラフが最近のファイルシステム編集を反映していることを確認してください。

1. プロジェクト名を特定: プロジェクト識別子が不明な場合は、list_projects を呼び出します:

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   （このワークスペースでは、派生プロジェクト名は "D-Scripts-aminwebsite" です。）

2. ステータスを確認するか、インデックスを更新: セッション中にファイルが作成または変更された場合は、index_repository を呼び出します:

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • モード選択:
     • mode: "fast": インクリメンタルパース、フィルタリングされたファイル、セマンティックベクトル埋め込みなし。アクティブな開発に高速で軽量。
     • mode: "moderate": 自然言語概念ブリッジングのためのインクリメンタルパース + ベクトル類似性埋め込み。
   • カバレッジ検査: レスポンスで以下を確認:
     • parse_partial: 特定の行範囲でパースエラーが発生したファイル。
     • skipped: 完全にスキップされたファイル（例: バイナリまたは特大ファイル）。

---

ステップ 2: シンボルと構造の発見 (search_graph)

関数、インターフェース、型、コンポーネント、ルート定義を見つけます。

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• 自然言語発見: キーワード/BM25検索には query を使用（例: "theme toggle transition"、"locale routing"）。
• 正確な名前パターン: 正規表現フィルタリングには name_pattern を使用（例: ".*Provider.*"、".*Skeleton.*"）。
• セマンティック概念検索: 語彙のギャップを埋めるには semantic_query: ["i18n", "language", "switch"]（文字列の配列が必要）を使用。
• 切り捨て処理 (has_more): レスポンスが "has_more": true を返した場合は、"offset": <現在のオフセット + 制限> を追加してページネーションします。

---

ステップ 3: 関係トレースと影響範囲

依存関係を検査せずに関数やインターフェースを変更しないでください。

1. 呼び出し元と呼び出し先をトレース (trace_path):

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound": この関数に依存するすべての呼び出し元を特定（影響範囲）。
   • direction: "outbound": このシンボルによって呼び出される下流の関数を特定。
   • direction: "both": 完全な双方向呼び出しチェーン。

2. git差分影響セットをマッピング (detect_changes): 変更をコミットまたは確定する前に、影響範囲を評価します:

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

ステップ 4: 外科的なコード取得 (get_code_snippet)

view_file でファイル全体を表示してコンテキストを消費する代わりに、正確なシンボル実装を取得します:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

レスポンスには以下が含まれます:

• 正確な start_line と end_line
• シンボルのクリーンなソースコード
• 直接の呼び出し元と呼び出し先のカウント

---

ステップ 5: 高レベルアーキテクチャ探索 (get_architecture)

新しいサブシステムに取り組む際や、システムトポロジを理解する際:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

トップアーキテクチャのハブコンポーネント、中心的な依存関係、レイヤー階層を特定します。

---

MCP遅延ツールリファレンスマトリックス

機能	ツール名	必須パラメータ	主要なオプションパラメータ
ステータス確認	index_status	project	N/A
インデックス起動	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
プロジェクト一覧	list_projects	なし	N/A
シンボル検索	search_graph	project	query, name_pattern, semantic_query, limit, offset
呼び出しチェーントレース	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
ソース取得	get_code_snippet	project, qualified_name	include_neighbors
影響範囲	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
アーキテクチャ	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
リテラルテキスト	search_code	project, query	file_pattern, case_sensitive, limit

---

ガードレールと一般的なアンチパターン

アンチパターン	正しい運用標準
インデックス鮮度を確認せずに検索する	バックグラウンドの自動監視が無効化されているため、常に最初に index_repository(mode: "fast") を呼び出すか、index_status で確認する。
関数定義を見つけるために grep を使用する	シンボル名で search_graph を呼び出す。修飾名、正確なファイルパス、行範囲、呼び出し元カウントが返される。
1つの関数を見るためにファイルの1000行を読む	シンボルの qualified_name で get_code_snippet を呼び出す。
呼び出し元を見つけるためにすべてのファイルを手動で読む	direction: "inbound" で trace_path を呼び出す。
グラフが100%完全であると想定する	グラフはベストエフォート。index_status が parse_partial の下にファイルをリストしている場合、それらの特定のフラグ行範囲に対してテキストgrepを使用する。
auto_watch を有効にする	auto_watch を決して有効にしない。ピークインタラクティブな開発パフォーマンスを維持するために false に保つ。