llm-tldr: 「認証はどこ？」に100msで答えるセマンティック検索の精度と限界

大規模なコードベースで「認証機能ってどこに実装されてるんだっけ？」と探したことはありませんか？grepやfindでは関数名がわからないと見つけられず、IDEのシンボル検索も完全一致が前提です。

llm-tldr は、自然言語クエリでコードを検索できるセマンティック検索機能を持つコード解析ツールです。「認証機能」「PDF生成」といった曖昧なキーワードでも、実際の振る舞いから関数を見つけ出します。本記事では、269ファイルのNext.jsプロジェクトで実際に試した結果から、その精度と限界を報告します。

llm-tldrとは？

llm-tldrは、LLM （大規模言語モデル）にコードベースの情報を効率的に提供するためのツールです。コード全体をそのまま渡すのではなく、構造化された情報だけを抽出することで、95%のトークン削減と155倍の高速化を実現します。

主な機能:

5層のコード解析アーキテクチャ: AST、コールグラフ、制御フロー、データフロー、プログラム依存の5つのレイヤーで解析
セマンティック検索: 自然言語クエリで関数を検索（本記事の焦点）
16言語対応: TypeScript 、Python 、JavaScript、Go、Rust、Javaなど
MCP統合: Claude Code / Claude Desktopとの連携（MCP ）

公式が主張する性能指標

指標	生コード	TLDR	改善率
関数コンテキストのトークン数	21,000	175	99%削減
コードベース概要のトークン数	104,000	12,000	89%削減
クエリのレイテンシ	30秒	100ms	300倍高速

これらの数値が実際のプロジェクトでどこまで再現できるのか、検証していきます。

セマンティック検索の仕組み

llm-tldrのセマンティック検索は、各関数を以下の情報とともに1024次元ベクトルにエンコードします：

シグネチャ + docstring（L1: AST）
呼び出し関係（L2: コールグラフ）
複雑度メトリクス（L3: 制御フロー）
データフローパターン（L4: データフロー）
依存関係（L5: プログラム依存）
コードの最初の約10行

埋め込みモデルにはbge-large-en-v1.5 （1.3GB）を使用し、ベクトル検索にはFAISS （Facebook AI Similarity Search）を採用しています。

grepとの違い

従来のgrepやripgrepは文字列マッチングなので、関数名やコメントに「authentication」が含まれていないと見つけられません。llm-tldrは実際の振る舞い（どんな関数を呼んでいるか、どんなデータを扱っているか）からベクトル化するため、コメントや変数名に依存しません。

検証環境

実際のプロジェクトで試した環境は以下の通りです：

プロジェクト: system-planner（TypeScript/Next.js プロジェクト）
規模: 269ファイル、517エッジ（関数間の呼び出し関係）
言語構成: TypeScript 257ファイル、JavaScript 12ファイル
llm-tldrバージョン: 1.5.2

セットアップ: 最初の罠

公式ドキュメント通りに進めると、最初の罠にハマります。

罠1: セマンティックインデックスが作成されない

1
2
# 公式ドキュメント通りに実行
tldr warm .

結果: 0 code units となり、セマンティックインデックスが作成されませんでした。

原因:

埋め込みモデル（bge-large-en-v1.5、1.3GB）のダウンロードが必要
言語指定（--lang）が必須

解決方法:

1
2
# 言語を明示的に指定
tldr semantic index . --lang typescript

初回実行時は1.3GBのモデルダウンロードが走るため、数分かかります。その後、516個のコードユニットがインデックス化されました。

罠2: パスエイリアスが解決されない

Next.jsプロジェクトでよく使われる@/lib/...のようなパスエイリアスは、llm-tldrが正しく解決できません。

1
2
# インポート元を検索
tldr importers "@/lib/supabase/server" .

結果: "importers": []（空）

これは、tsconfig.jsonのpaths設定をllm-tldrが読み込んでいないためです。現時点では回避策がなく、絶対パスでの検索が必要です。

セマンティック検索の実力検証

実際に3つのクエリで精度を確認しました。

検証1: 認証機能の検索

1
tldr semantic search "authentication and login" --path . --k 5

結果:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[
  {
    "name": "LoginForm",
    "file": "components/auth/LoginForm.tsx",
    "score": 0.6509
  },
  {
    "name": "LoginPage",
    "file": "app/auth/login/page.tsx",
    "score": 0.6506
  },
  {
    "name": "UpdatePasswordForm",
    "file": "components/auth/UpdatePasswordForm.tsx",
    "score": 0.6165
  }
]

評価: ✅ 期待通り。ログイン関連のコンポーネントが上位にランクインしました。スコア0.65前後は、セマンティック検索としては妥当な類似度です。

検証2: 日本語クエリの精度

1
tldr semantic search "Supabaseへのデータベース接続" --path . --k 5

結果: データベース関連のスクリプトが適切に検出されました。

評価: ✅ 日本語クエリも有効。bge-large-en-v1.5は英語モデルですが、多言語クエリにも対応しています。

検証3: 機能横断的な検索

1
tldr semantic search "PDF generation and export" --path . --k 5

結果:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
  {
    "name": "generateEstimatePDF",
    "file": "lib/utils/pdf-generator.ts",
    "score": 0.6862
  },
  {
    "name": "convertMarkdownToDocx",
    "file": "lib/utils/specification-export.ts",
    "score": 0.6582
  }
]

評価: ✅ 期待以上。PDF生成だけでなく、関連するドキュメント変換機能も検出しました。これは、データフローやコールグラフの情報が効いている証拠です。

コールグラフ展開機能

1
tldr semantic search "chat message handling" --path . --k 3 --expand

--expandオプションを付けると、関数の呼び出し関係（calls, called_by, related）も含めて結果を表示します。リファクタリング時の影響範囲分析に便利です。

動作しなかった機能

期待していたが、正常に動作しなかった機能もあります。

失敗1: Impact分析

1
tldr impact fetchVendors .

結果: Function 'fetchVendors' not found in call graph

原因推測:

関数名の完全一致が必要？
コールグラフのインデックスが完全でない可能性
TypeScript特有の問題（型定義との関連）

失敗2: アーキテクチャ分析

1
tldr arch .

結果: すべての項目が空

1
2
3
4
5
6
{
  "entry_layer": [],
  "leaf_layer": [],
  "middle_layer_count": 0,
  "circular_dependencies": []
}

原因推測: Next.jsプロジェクト特有の構造（App Router、Server Components等）に未対応の可能性があります。

パフォーマンス: デーモンモードの威力

llm-tldrには、バックグラウンドでデーモンを起動するモードがあります。

1
tldr daemon start

効果:

クエリが100msに高速化（公式値通り）
インメモリキャッシュにより、2回目以降の検索が爆速
Unix Socket経由で通信

実際に試したところ、初回クエリは約2秒、2回目以降は100ms前後でした。これは公式の「155倍高速化」に近い数値です。

実用性の評価

Serenaとの比較（結論だけ）

Serena はLSP（Language Server Protocol）ベースで、型情報や参照解決を使った「正確な編集・リファクタリング」に強いツールです。一方でllm-tldrは、Tree-sitter による静的解析 + ベクトル検索で「名前がわからない機能を探す」ことに強みがあります。

この2つは競合というより役割分担で、個人的には次の使い分けが現実的だと思いました。

Serena: 名前がわかっているシンボルを正確に辿る / 安全にリネームする
llm-tldr: 「認証ってどこ？」のような自然言語で当たりを付ける / 初見コードベースを俯瞰する

✅ 非常に有効なケース

大規模コードベースの探索
- 初見のプロジェクトで「認証はどこ？」「PDF生成は？」といった機能探しに最適
- 従来のgrepやfindより直感的
リファクタリング前の影響調査
- コールグラフで関数間の依存関係を把握
- --expandオプションで変更の影響範囲を特定
LLMへのコンテキスト提供
- 95%のトークン削減により、大規模プロジェクトでもコンテキストウィンドウに収まる
- 構造化されたJSON出力でLLMが理解しやすい

🤔 限定的に有効なケース

デバッグ
- tldr sliceによるプログラムスライスは理論上有効だが、今回未検証
- データフロー分析（tldr dfg）も同様
アーキテクチャ分析
- tldr archが正常動作すれば有用だが、今回は結果が得られず

❌ 不向きなケース

単一ファイルの簡単な編集
- オーバーヘッドが大きい
- IDEの機能で十分
リアルタイム性が求められる場面
- インデックス更新が必要（20ファイル変更ごと）
- 継続的な通知設定（Git hook等）が必要

初期コストの現実

llm-tldrを導入する際の初期コストは無視できません。

必要なリソース

ディスク容量: 1.3GB（bge-large-en-v1.5モデル）+ インデックスファイル
初回セットアップ時間:
- モデルダウンロード: 数分（回線速度に依存）
- インデックス作成: 中規模プロジェクト（269ファイル）で約2分
メモリ: デーモンモード使用時は常駐プロセスとして数百MB

継続的なメンテナンス

インデックスは自動更新されないため、以下のいずれかの方法でメンテナンスが必要です：

方法1: Git Hook（推奨）

.git/hooks/post-commitに追加:

1
2
#!/bin/bash
git diff --name-only HEAD~1 | xargs -I{} tldr daemon notify {} --project .

20ファイル変更後、デーモンが自動でセマンティックインデックスを再構築します。

方法2: 手動更新

1
tldr warm .  # フルリビルド

MCP統合: Claude Codeとの連携

llm-tldrはMCP（Model Context Protocol）サーバーとして動作し、Claude Code / Claude Desktopと統合できます。

Claude Codeでの設定

.claude/settings.json:

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    }
  }
}

これにより、Claudeが自動的にllm-tldrを使用してコードベースを理解できます。実際に試したところ、Claudeが「このプロジェクトの認証機能はどこですか？」という質問に対して、llm-tldrのセマンティック検索結果を元に回答してくれました。

まとめ: 2時間試してわかったこと

llm-tldrのセマンティック検索は、期待以上に自然言語クエリが機能するという点で非常に印象的でした。特に以下のケースでは実用的です：

推奨する利用シーン:

10万行以上の大規模プロジェクト
マイクロサービスアーキテクチャ
レガシーコードの分析
AI支援開発（Claude Code等との統合）

注意すべき点:

初期セットアップコスト（1.3GBダウンロード）は避けられない
一部機能（arch、impact）が期待通り動かないケースがある
パスエイリアスの解決に課題がある
インデックス更新にGit hook等の設定が必要

個人的には、「コードベース探索の体験を変える」ツールとして、大規模プロジェクトでの導入価値は十分にあると感じました。特にClaude Codeとの組み合わせは、AI支援開発の新しい可能性を感じさせます。

興味のある方は、まず小規模なプロジェクトで試してみることをお勧めします。

Fragments of verbose memory

冗長な記憶の断片 - Web技術のメモをほぼ毎日更新