ultraindex — リポジトリ全体のAI分析対応百科事典を構築・ナビゲートする
巨大なリポジトリでは、コンテキストウィンドウが重要情報に到達する前に埋まってしまいます。
ultraindex はこれを役割分担で解決します。決定論的で依存関係ゼロのエンジン(node scripts/ultraindex.mjs <command> — npm install不要、APIキー不要、全機能は --help で確認)が機械的な処理(プロジェクトスキャン、リンクグラフ構築、百科事典のレイアウト)を担当し、あなたが理解(根拠のある引用つき分析)を行い、その後リポジトリを直接読む代わりに結果をナビゲートします。
重要なルール:
- エンジンはコードビューとグラフ(
ui:gen領域)を所有します — ビルドのたびに再生成されるため、手動編集は禁止です。- あなたはビジネスビュー(
ui:human領域)を所有します。buildは再ビルドやリネーム時にあなたの文章を保持します。- 証拠に基づいて分析し、記憶に頼らないでください。 分析は
dossierが表示する実際のソースからのみ記述し、[file:line]形式で引用し、checkは解決できない引用があると失敗します — 推測はしないでください。- 最小限だけ読み込んでください。 一度に1エントリ(または1つの
dossier)だけを読む — これが意図されたパターンであり、モジュール単位のエンリッチメント用サブエージェントが正確に行う方法です。graph.jsonやencyclopedia/ディレクトリ全体をまとめてコンテキストに読み込まないでください — それでは目的が損なわれます。
ほとんどのコマンドは --json を受け付けます — 結果を散文として読むのではなく、結果に基づいて分岐する場合は常にそちらを優先してください。
状況に応じたルーティング
現在の状況を以下の順序で判断し、該当するリファレンスを読んで詳細なワークフローを確認してください:
-
インデックスがまだ存在しない — リポジトリルートに
.ultraindex/またはdocs/ultraindex/がなく、その中にgraph.jsonもない場合。まずビルドし、次にトップモジュールをエンリッチ:references/generate.md を参照。 -
インデックスは存在する — まず鮮度を確認
node scripts/ultraindex.mjs check --out <index-dir> --jsonを実行。もし古いか壊れていると報告されたら、buildを再実行(あなたの文章は保持されます)してから続行。タスクに関係ないファイルだけが変更された場合は、その旨を記録して続行しても構いません。 -
ユーザーにタスクや質問がある(「Xはどこ?」「Zはどう動く?」「どのファイルを変更すべき?」) — インデックスをナビゲートし、それが指すファイルだけを開き、検証済みの引用で回答を裏付ける:references/navigate.md を参照。
-
回答が高信頼性を要求する場合(監査、セキュリティ、正当性が重要な主張)、またはユーザーが回答の検証/判断を依頼した場合 —
check --answerがパス(引用が解決)した後、セマンティック検証ゲートに進み、各引用箇所が単に存在するだけでなく、その主張を支持していることを証明する:references/verify.md を参照。 -
ユーザーがインデックス化/分析/ドキュメント化を依頼した場合、または
status --jsonが未エンリッチのハブを示しており予算がある場合 — ステータス駆動のエンリッチメントループ(dossier → 引用つき分析を記述 → check)を実行。大規模リポジトリでは並列化可能:ホストがサブエージェントをサポートしていれば、キューからモジュールごとに1つのサブエージェントを割り当てる。references/generate.md を参照。 -
findがよく見落とす場合、またはユーザーがセマンティック/より良い検索を望む場合 — オプションの埋め込みレイヤーをセットアップ(docker compose、embed、ハイブリッドfind):references/semantic.md を参照。
典型的な初回訪問は 1 → 5 → 3 の連鎖、再来訪は通常 2 → 3、高信頼回答は → 4 が追加されます。
コマンド早見表
build --repo <dir> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid]— インデックスをスキャンして(再)書き込みます。冪等で、エンリッチ済みの文章は保持されます。インクリメンタル(変更のないファイルの抽出結果は再利用);--max-filesによる切り捨て時は警告。--out docs/ultraindexでコミット・PRレビュー可能なインデックスに。map [--module <slug>] [--json]— INDEX.md(または1エントリ、もしくはモジュールテーブル)を表示。find "<query>" [--k <n>]— モジュールをランク付けし、開くべき正確なファイルを表示。デフォルトは単語重要度(IDF)による語彙検索、vectors.json が存在する場合はハイブリッド(+ セマンティック)。neighbors <file|module> [--depth <n>]— その要素にリンクするもの、またはその要素からリンクされるものを表示。symbols "<name>" [--json]— シンボルが定義されている場所(ファイル:行、種類、所有モジュール)と、それを参照するファイルを表示。識別子のサブトークンによるあいまい検索。impact <file|module> [--depth <n>] [--json]— 逆依存関係クロージャ:ターゲットをインポートまたは使用しているすべてのもの。「これを変更したら何が壊れるか」。status— エンリッチメントの作業キューを、エンリッチすべき正確な順序で表示。dossier <slug>— モジュールの根拠パケット(実際のソース + 近隣モジュール;ドキュメント/設定のみのモジュール、例:rootはコードなし — 代わりにREADME/設定を引用してエンリッチ)。ask "<question>"— 根拠のある証拠をまとめて質問に回答。check [--answer <file>] [--semantic]— 鮮度+整合性+根拠付け(引用が解決可能か)。非ゼロ終了 ⇒ 古い、壊れている、または根拠不足。--semanticはさらに検証ゲートも実行(引用箇所が主張を反駁する場合、または完全に判断されて支持がない場合に失敗);生のverdicts[]から判定を再集約し、判定されたすべての引用箇所をライブリポジトリから再読込み — 改ざんされた要約や変化したソースは失敗し、絶対にパスしません。verify --answer <file> [--apply <verdicts.json>] [--max-verify <n>]—check --answerの上位に位置する高信頼ゲート:主張↔引用のワークリストを出力し、敵対的な支持チェックを実施、その後--applyで判定結果を合格/不合格に集約。references/verify.md を参照。embed [--force]— セマンティックfind用の vectors.json をビルド/リフレッシュ(プロバイダーが必要 — references/semantic.md を参照)。
スコープに関する注記
- キー不要、ネットワーク不要、決定論的(オプションのセマンティックレイヤーは唯一の例外で、プロバイダーがない場合は語彙検索に劣化)。変更のないリポジトリの2回のビルドは、
manifest.jsonのbuiltAt証明タイムスタンプを除いてバイト単位で同一;vectors.jsonも除外(浮動小数点数はプロバイダーに依存)。 - AST正確なシンボル — JS/TS/TSX、Python、Go、Rust、Java、C、C++、C#、Ruby、PHP向けのコミット済み tree-sitter 文法を使用。真のネスト、正確な種類、構造的エクスポートを実現。その他の言語は正規表現抽出にフォールバック(検索は可能)。文法のwasmはバンドルに同梱されているため、スキル使用時に
npm installは不要(インストール自体は ~17 MiB のwasmとやや重め)。 - インポートエッジ — JS/TS(tsconfig
paths、packageexportsマップ)、Python、Go(マルチモジュール+replace)、Rust(mod/use)、Java(パッケージ)、C/C++(#include "...")、Ruby(require_relative/require)、PHP(composer PSR-4+相対require)、C#(using→namespace)。さらに、あるファイルがインポートせずに別のファイルの一意のエクスポートシンボルを参照している場合の保守的なコード間useエッジもサポート。残りの言語はインポートエッジなし。Yarn PnPの仮想ファイルシステムは対象外(ワークスペース名は解決される)。 - 未解決のエッジは通常、リポジトリ自体に壊れたインポートや古いドキュメントリンクがあることを意味します — それは隠蔽するのではなく報告すべき発見事項です。