code-tree 仕様・開発意図・期待効果 — LLMコンテキスト最適化ツール
code-treeの設計思想とツール仕様、コンテキスト圧縮とトークンコスト削減の実装方針、MCP統合による運用フロー
概要
code-tree は、コードベースを走査して「構造化された要約コンテキスト」を生成する Rust 製のツールです。生成されたデータは .ctree/ ディレクトリに保存され、LLM（大規模言語モデル）との連携において、木構造、シンボル、依存関係、差分情報など、扱いやすい形式で整理されます。
CLI ツール (ctree) および MCP サーバ (ctree-mcp) として利用可能であり、エディタやエージェントから直接統合できます。
開発の意図
当初の設計：プログラミング言語からの出発
code-tree は最初、Rust/Go/Python 等のプログラミング言語のソースコードを静的解析し、シンボルを抽出するツールとして設計されました。しかし実運用の中で、以下の課題が浮かび上がりました：
- ドキュメント形式の扱い: Hugo ベースのブログやドキュメントプロジェクトでは、Markdown コンテンツが project の大部分を占める。これをコンテキストから除外すると、プロジェクト全体の理解が不完全になる
- テンプレートの構造化: HTML テンプレート（Hugo/Jinja）の構造変更がコンテキストに反映されない
この経験から、code-tree を Markdown・HTML テンプレートへと拡張しました。詳細は「HTML テンプレート・Markdown スキャナーの構築」を参照。
コンテキスト圧縮の必要性
大規模プロジェクトでは、毎回全ソースコードを読み込む方法は現実的ではありません。
- トークンコストの増大: 巨大なリポジトリであっても、LLM に渡す情報を必要最小限かつ再現可能な形で構造化する必要がある
- トークンの無駄遣い: 毎回フルスキャン結果を送信するのではなく、差分リビジョン（
snapshots/rev/*.txt）とハッシュ参照を活用して効率化を図る - 運用の一貫性: エディタやエージェントとの連携において、
ctree_checkを中心とした定常運用が可能な統一的なツール群を提供する
ノイズと揺れの抑制
チーム開発環境では、出力の再現性が重要です。
sw（strong width）やww（weak width）などの生成パラメータを固定することで、出力の揺れを抑える- ハッシュベースの参照により、コンテキストウィンドウを節約しつつ、必要な情報にドリルダウンできる
主要な仕様
対応言語
各言語がモジュール化された設計になっており、必要に応じて言語サポートを追加できます。現在は、開発で実際に使用する言語から段階的に実装を進めています。
想定対応言語: Go, Rust, Python, TypeScript, JavaScript, C#, Dart, Lua, Awk, Shell (sh/bash/zsh), Kotlin, Swift, Markdown
各言語はモジュール化されているため、パターン定義とスキャンロジックの追加で容易に拡張可能です。
スコープ設計
各ファイルを以下の 3 段階に分類し、優先順位（strong > weak > symbol_only）に従って処理します。
- strong: 詳細な要約を生成。関数定義、クラス定義、モジュール構造など、プロジェクト全体の骨組みに関わるシンボル
- weak: 簡略化された要約を生成。ユーティリティ関数、ヘルパーメソッド、設定ファイルなど、参照用のシンボル
- symbol_only: 存在情報と主要なシンボルのみを抽出。依存パッケージ、テストコード、生成済みコードなど
出力構造 (.ctree/)
| ファイル | 用途 |
|---|---|
tree_annotated_<lang>.txt | アノテーション付きのディレクトリツリー |
symbols_<lang>.jsonl | 抽出された全シンボルのリスト（JSON Lines形式） |
depends_<lang>.jsonl | ファイル・モジュール間の依存関係 |
text_store_<lang>.jsonl | ハッシュ参照用のテキストストア |
strong_summary_<lang>.txt | strong スコープのみのテキスト要約 |
weak_summary_<lang>.txt | weak スコープを含むテキスト要約 |
ctree_ctx_<lang>.txt | LLM 入力用に最適化された最終コンテキスト |
差分管理と履歴
.ctree/snapshots/rev/ に 0001.txt 形式でコンパクトな差分を保存します。
- シンボルは
path|kind|nameを元に短縮ハッシュ化され、継続的に追跡される - 各リビジョンには「追加（+S）」「削除（-S）」「依存関係の追加（+D）」「削除（-D）」が記録される
- diff マージジョンなしで、変更点を O(k log n) で検索可能（k: 変更数、n: 総シンボル数）
設定管理
.ctree.toml による設定をサポート。優先順位は「CLI 引数 > .ctree.toml > デフォルト値」となります。
[ctree]
strong = ["src/main.rs", "src/lib.rs", "src/*/mod.rs"]
weak = ["src/**/*.rs", "tests/**/*.rs"]
symbol_only = ["vendor/**/*"]
[output]
template = "markdown" # Markdown形式で統一
出力は Markdown に統一化され、Obsidian など様々なツールで直接閲覧・編集が可能です。
MCP ツールセット
| ツール | 機能 |
|---|---|
ctree_init | 設定テンプレートの作成 |
ctree_generate | コンテキストの生成・更新 |
ctree_reset | 履歴のリセットと再生成 |
ctree_check | 生成、差分確認、関連テキスト取得の一括実行 |
ctree_get_baseline | ベースラインの参照 |
ctree_get_revs | 差分履歴の取得 |
ctree_get_text | ハッシュ指定による特定テキストのオンデマンド取得 |
期待される導入効果
トークン消費の最適化（設計上の期待）
必要最小限のインデックス化された情報のみを渡すことで、コストと処理速度の向上を期待しています。
- 初期コンテキスト:
.ctree/ctree_ctx_<lang>.txtでプロジェクト全体の骨組みを圧縮 - 詳細情報: ハッシュ参照で必要なシンボルのみをオンデマンド取得
- 差分情報: 前回スナップショット以降の変更のみを渡す
検証状況: 新規セッションで差分チェックを実行させた際、差分ベースの作業意図理解が正確であることを確認しています。詳細なトークンコスト削減の定量的検証はこれからです。
同期コストの低減
「最新の状態のみを追う」運用が可能になり、対話ごとのコンテキスト再送が不要になります。
- rev ファイルの差分から「何が変わったのか」を即座に把握
- 関連シンボルのハッシュだけを指定すれば、詳細情報を動的に取得
可視化とレビューの効率化
変更点が構造的に把握しやすくなり、調査の起点が明確になります。
tree_annotated_<lang>.txtでプロジェクト構造を一覧化symbols_<lang>.jsonlで全シンボルをインデックス化し、grep/jq で高速検索
推奨される運用フロー
ステップ 1: 初期化
ctree_init --config .ctree.toml
プロジェクト固有の設定（strong/weak スコープ定義）を初期化。
ステップ 2: ベースライン生成
ctree generate --config .ctree.toml
.ctree/ ディレクトリに初期コンテキストを生成。この状態を revision 0000 として記録。
ステップ 3: 日常運用
ctree_check --config .ctree.toml
ctree_check は以下を一括実行：
- ソースコード更新の検出
.ctree/を再生成- 新しい rev ファイル（0001.txt など）を生成
- LLM に渡す最終コンテキストを出力
ステップ 4: LLM との連携
LLM には以下を基本コンテキストとして渡します：
# Project Structure
<ctree_ctx_<lang>.txt の内容>
# Recent Changes (rev 0010)
<snapshots/rev/0010.txt の内容>
詳細情報が必要な場合、ハッシュを指定します：
MCP call: ctree_get_text(hashes=["abc123", "def456"])
設計思想
出力を「常に重い全文」にするのではなく、「軽量な索引 + 必要時のオンデマンド取得」に寄せることで、大規模開発における LLM 連携の実効性を高めています。
「望遠鏡（Telescope）」デザイン
ハッシュのみを記録し、必要に応じて詳細なテキストを取得する設計は、特に LLM エージェントとの相性が抜群です。
- 低倍率（全体図）:
tree_annotated_<lang>.txtでプロジェクト構造を俯瞰 - 中倍率（モジュール単位）:
symbols_<lang>.jsonlをSerenaと連携させ、シンボル検索から構造理解へドリルダウン - 高倍率（コード詳細）:
text_store_<lang>.jsonlで特定シンボルの実装を参照
モノレポ向けのボリューム制御
DDD + Clean Architecture で機能ごとにモジュール化された構成（features/{module}/{domain,infra,presentation} など）では、作業中のモジュールに対して注釈密度を上げ（--sw: strong width）、依存先を低密度にする（--ww: weak width）プロファイル設定が有効です。
実装例:
# 作業対象のモジュール（詳細な要約）
strong = ["features/payment/**/*.rs"]
# 依存関連（簡略化）
weak = ["features/*/domain/**/*.rs", "features/*/infra/**/*.rs"]
# テストなど（シンボル参照のみ）
symbol_only = ["tests/**/*.rs"]
この設定により、モノレポ規模でも以下のようにコンテキストボリュームを動的にコントロール可能になります：
ctree generate --config .ctree.toml --sw 20 --ww 5
作業中のモジュール（payment など）は詳細な依存関係と実装を含める一方、他のモジュールの domain/infra は骨組みのみを渡すことで、トークンコストを抑えながら必要な情報を確保できます。
現在の実装状況
- 言語サポート: モジュール化設計により、必要な言語から段階的に実装可能
- 差分管理: rev ファイル形式による差分追跡の実装は完了。新規セッションでの作業意図理解が正確であることを確認
- トークンコスト削減: 理論的には有効な設計だが、定量的な検証はこれからです
まとめ
code-tree は「コンテキスト圧縮」という観点から LLM エージェントの実効性を向上させるツールです。大規模プロジェクトでも、軽量で再現可能なコンテキスト管理が可能になり、トークンコストの削減と開発効率の向上を同時に実現します。