codebase-management

SocratiCode の管理

SocratiCode のコードベースのインデックス作成、ファイル監視、コードグラフ、コンテキストアーティファクトを設定、インデックス化、管理します。

初回セットアップ

1. インフラストラクチャを確認：codebase_health — Docker、Qdrant、Ollama／埋め込みプロバイダー、埋め込みモデルを検証します
2. インデックス作成を開始：codebase_index — バックグラウンドで実行され、すぐに戻ります
3. 進捗を確認：codebase_status — 100％完了するまで約60秒ごとに呼び出します
   • これにより MCP 接続も維持されます（アイドル状態の接続を切断するホストもあります）
4. 完了：インデックス作成後、グラフが自動的に構築されます。デフォルトのウォッチャーモードでは、ファイルウォッチャーが自動的に起動します。これで検索できます。

初回使用時には、SocratiCode が Docker イメージを自動的に取得し、コンテナーを起動して、埋め込みモデルをダウンロードします（初回のみ約5分）。

増分更新とファイル監視

デフォルトの SOCRATICODE_WATCHER=auto モードでは、ファイルウォッチャーによってインデックスが自動的に最新の状態に保たれます。

• codebase_watch { action: "start" } — ウォッチャーを起動します（最初に追いつき更新を実行します）
• codebase_watch { action: "stop" } — ウォッチャーを停止します
• codebase_watch { action: "status" } — 監視対象のプロジェクトを一覧表示します（プロセス間を含む）
• codebase_update — 手動で増分更新を実行します（変更されたファイルのみ、同期実行）。ウォッチャーが有効な場合、通常は不要です。

コードインデックスのスナップショットを意図的に作成するには、チェックアウトを使用するすべての MCP プロセスで SOCRATICODE_WATCHER=off と SOCRATICODE_AUTO_RESUME=off を設定します。検索ツールとグラフツールは既存のインデックスとグラフを引き続き読み取ります。更新が必要なときだけ codebase_update と codebase_graph_build を実行してください。明示的な codebase_watch { action: "start" } を引き続き利用できるようにするには、代わりにウォッチャーモード manual を使用します。ステータスが無効を示すウォッチャーを再起動しようとしないでください。

SOCRATICODE_WATCHER=git では、アクティブなインデックス済みチェックアウトは、チェックアウトされた ref／HEAD の変更時に更新されます。10秒ごと、および検索／ステータス／グラフのリクエスト時に確認されます。ネイティブのファイルウォッチャーは起動しません。保留中または失敗した更新の結果は最新ではありません。Git が更新をトリガーしますが、未コミットの編集を含め、作業ツリーがインデックス化されます。ref／HEAD を変更しないファイル保存には codebase_update を使用してください。Git モードを選択しても、初回のインデックスは作成されません。SOCRATICODE_AUTO_RESUME=off によって抑制されるのは起動時の追いつき更新であり、その後の Git による更新ではありません。Git の診断を回避するためにウォッチャーを起動してはいけません。

インデックスの管理

• codebase_stop — 進行中のインデックス作成を安全に一時停止します。現在のバッチを完了してチェックポイントを保存します。すべての進捗が保持されます。codebase_index で再開できます。
• codebase_remove — インデックス全体を削除します（破壊的操作）。ウォッチャーを安全に停止し、インデックス作成をキャンセルして、グラフの構築が完了するまで待機します。
• codebase_prune — 保存された ID を一覧表示します。削除するには、ID の完全一致、新しい確認トークン、共有ストアの確認が必要です。パスが存在しないことは参考情報であり、候補の決定には使用しません。
• codebase_list_projects — インデックス済みのすべてのプロジェクトを、メタデータ、グラフ情報、アーティファクトのステータスとともに一覧表示します。

コードグラフの管理

依存関係グラフはインデックス作成後に自動的に構築されます。ウォッチャーモード manual および off では、グラフのクエリは既存のグラフを読み取りますが、グラフがない場合、副作用として作成するのではなく、明示的な構築を求めます。

• codebase_graph_build — 手動で再構築します（バックグラウンドで非同期実行）。codebase_graph_status で進捗を確認します。
• codebase_graph_remove — グラフを削除します（次回の codebase_index 実行時に自動再構築されます）
• codebase_graph_status — 構築の進捗またはグラフの準備状況を確認します

コンテキストアーティファクトのセットアップ

コード以外のナレッジをインデックス化するには、プロジェクトのルートに .socraticodecontextartifacts.json を作成します。

{
  "artifacts": [
    {
      "name": "database-schema",
      "path": "./docs/schema.sql",
      "description": "PostgreSQL schema — all tables, indexes, constraints, foreign keys."
    }
  ]
}

対応しているタイプ：SQL スキーマ、OpenAPI／Protobuf API 仕様、Terraform／CloudFormation 設定、Kubernetes マニフェスト、アーキテクチャドキュメント、環境設定など、テキストベースのファイルやディレクトリ。

• codebase_context_index — すべてのアーティファクトを手動でインデックス化／再インデックス化します（通常は自動的に開始されます）
• codebase_context_remove — インデックス化されたすべてのアーティファクトを削除します（インデックス作成中は実行できません）

トラブルシューティング

問題	解決方法
Docker を利用できない	https://docker.com から Docker Desktop をインストールし、起動していることを確認してください
macOS／Windows でインデックス作成が遅い	Docker では GPU を利用できません。Metal／CUDA による高速化には、https://ollama.com/download から Ollama をネイティブインストールしてください。または、クラウド埋め込みを使用してください。
代わりにクラウド埋め込みを使用したい	EMBEDDING_PROVIDER=openai と OPENAI_API_KEY、または EMBEDDING_PROVIDER=google と GOOGLE_API_KEY を設定してください
検索結果が見つからない	codebase_status を確認してください。プロジェクトがインデックス化されていない可能性があります。codebase_index を実行してください。
結果が古い	codebase_status を確認してください。codebase_update を実行してください。ウォッチャーは、ステータスに無効と表示されていない場合にのみ起動してください。
インデックス作成が中断された	もう一度 codebase_index を実行してください。最後のチェックポイントから自動的に再開します。
別のプロセスがインデックスを作成中	codebase_status はプロセス間のインデックス作成を検出します。完了を待つか、codebase_stop を使用してください。

主な環境変数

変数	デフォルト	説明
QDRANT_MODE	managed	managed（Docker）または external（リモート／クラウド Qdrant）
QDRANT_URL	—	リモート Qdrant の完全な URL（例：https://xyz.cloud.qdrant.io:6333）
QDRANT_API_KEY	—	リモート Qdrant の API キー
EMBEDDING_PROVIDER	ollama	ollama、openai、または google
OPENAI_API_KEY	—	EMBEDDING_PROVIDER=openai の場合に必須
GOOGLE_API_KEY	—	EMBEDDING_PROVIDER=google の場合に必須
OLLAMA_MODE	auto	auto（ネイティブを検出し、失敗した場合は Docker にフォールバック）、docker、external
EMBEDDING_MODEL	nomic-embed-text	モデル名（プロバイダー固有）
SEARCH_DEFAULT_LIMIT	10	codebase_search のデフォルト結果数（1～50）
SEARCH_MIN_SCORE	0.10	デフォルトの最小 RRF スコアしきい値（0～1）
MAX_FILE_SIZE_MB	5	インデックス化するファイルの最大サイズ（MB）。有限の数値をすべて指定する必要があります
EXTRA_EXTENSIONS	—	インデックス化する追加のファイル拡張子（例：.tpl,.blade,.hbs）
SOCRATICODE_WATCHER	auto	auto、manual（明示的な起動のみ）、off（ウォッチャーなし）、または git（ref／HEAD の変更をトリガーに更新し、ネイティブウォッチャーは使用しない）
SOCRATICODE_AUTO_RESUME	—	all は保存済みのすべてのプロジェクトを再開し、off は起動時の追いつき処理と中断されたインデックス作成の復旧を無効にします

各ツールのすべてのパラメーターについては、references/tool-reference.md を参照してください。