Communityライティング&編集github.com

ultraindex — リポジトリ全体をAI分析対応の百科事典化

巨大なコードベースでもコンテキストウィンドウを圧迫せずに、AIがナビゲート可能な百科事典(コード+ドキュメント)を構築・分析・検索できるスキル。決定論的エンジンと人手による分析を分離し、引用検証つきの高信頼分析を実現する。

ultraindex — リポジトリ全体をAI分析対応の百科事典化 とは?

ultraindexは、大規模なリポジトリ全体をAIエージェントがナビゲート可能な百科事典(encyclopedia)に変換するスキルです。従来の手法ではコンテキストウィンドウが不足しがちな巨大コードベースでも、決定論的エンジン(`node scripts/ultraindex.mjs`)が機械的なスキャン、リンクグラフの構築、百科事典のレイアウトを担当し、ユーザーは分析・理解に集中できます。 このスキルはClaude CodeなどのAIエージェントで利用することを想定しており、エンジン部分は`npm install`不要・APIキー不要・ネットワーク不要で完全に決定論的に動作します。オプションでOllamaなどのローカル埋め込みベースのセマンティック検索にも対応します。 核となる設計思想は「コードビュー」と「分析ビュー」の分離で、エンジンが管理するコード関連領域(`ui:gen`)は自動生成され、人間(またはAIの分析)が記述するビジネスロジック領域(`ui:human`)は再ビルド時にも保持されます。分析は必ず実ソースコードの引用(`[file:line]`形式)に基づき、`check`コマンドがすべての引用が解決可能か検証するため、推測や誤った情報を排除します。 ワーキングフローは状況に応じてルーティングされ、インデックス未存在時→ビルド→エンリッチ、インデックス存在時→ナビゲーション、高信頼要求時→検証ゲート、セマンティック検索時→埋め込みセットアップという明確な分岐を持ちます。また、`status`コマンドでエンリッチ待ちモジュールの作業キューを出力し、大規模リポジトリではサブエージェントによる並列エンリッチも可能です。

対応~Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraindex

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ultraindex — リポジトリ全体のAI分析対応百科事典を構築・ナビゲートする

巨大なリポジトリでは、コンテキストウィンドウが重要情報に到達する前に埋まってしまいます。 ultraindex はこれを役割分担で解決します。決定論的で依存関係ゼロのエンジン(node scripts/ultraindex.mjs <command> — npm install不要、APIキー不要、全機能は --help で確認)が機械的な処理(プロジェクトスキャン、リンクグラフ構築、百科事典のレイアウト)を担当し、あなたが理解(根拠のある引用つき分析)を行い、その後リポジトリを直接読む代わりに結果をナビゲートします。

重要なルール:

  1. エンジンはコードビューとグラフ(ui:gen 領域)を所有します — ビルドのたびに再生成されるため、手動編集は禁止です。
  2. あなたはビジネスビュー(ui:human 領域)を所有します。build は再ビルドやリネーム時にあなたの文章を保持します。
  3. 証拠に基づいて分析し、記憶に頼らないでください。 分析は dossier が表示する実際のソースからのみ記述し、[file:line] 形式で引用し、check は解決できない引用があると失敗します — 推測はしないでください。
  4. 最小限だけ読み込んでください。 一度に1エントリ(または1つの dossier)だけを読む — これが意図されたパターンであり、モジュール単位のエンリッチメント用サブエージェントが正確に行う方法です。graph.json や encyclopedia/ ディレクトリ全体をまとめてコンテキストに読み込まないでください — それでは目的が損なわれます。

ほとんどのコマンドは --json を受け付けます — 結果を散文として読むのではなく、結果に基づいて分岐する場合は常にそちらを優先してください。

状況に応じたルーティング

現在の状況を以下の順序で判断し、該当するリファレンスを読んで詳細なワークフローを確認してください:

  1. インデックスがまだ存在しない — リポジトリルートに .ultraindex/ または docs/ultraindex/ がなく、その中に graph.json もない場合。まずビルドし、次にトップモジュールをエンリッチ:references/generate.md を参照。

  2. インデックスは存在する — まず鮮度を確認 node scripts/ultraindex.mjs check --out <index-dir> --json を実行。もし古いか壊れていると報告されたら、build を再実行(あなたの文章は保持されます)してから続行。タスクに関係ないファイルだけが変更された場合は、その旨を記録して続行しても構いません。

  3. ユーザーにタスクや質問がある(「Xはどこ?」「Zはどう動く?」「どのファイルを変更すべき?」) — インデックスをナビゲートし、それが指すファイルだけを開き、検証済みの引用で回答を裏付ける:references/navigate.md を参照。

  4. 回答が高信頼性を要求する場合(監査、セキュリティ、正当性が重要な主張)、またはユーザーが回答の検証/判断を依頼した場合 — check --answer がパス(引用が解決)した後、セマンティック検証ゲートに進み、各引用箇所が単に存在するだけでなく、その主張を支持していることを証明する:references/verify.md を参照。

  5. ユーザーがインデックス化/分析/ドキュメント化を依頼した場合、または status --json が未エンリッチのハブを示しており予算がある場合 — ステータス駆動のエンリッチメントループ(dossier → 引用つき分析を記述 → check)を実行。大規模リポジトリでは並列化可能:ホストがサブエージェントをサポートしていれば、キューからモジュールごとに1つのサブエージェントを割り当てる。references/generate.md を参照。

  6. 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、package exports マップ)、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の仮想ファイルシステムは対象外(ワークスペース名は解決される)。
  • 未解決のエッジは通常、リポジトリ自体に壊れたインポートや古いドキュメントリンクがあることを意味します — それは隠蔽するのではなく報告すべき発見事項です。

関連スキル