Handbooks とは？
一つのコードベースから二冊のハンドブックを生成——チームが読む物語形式のドキュメントサイトと、コーディングエージェントがルーティングに使う位置インデックス。同じ解析済みの地図から作られ、コードの変化に追随します。
一つのコードベースから、二冊のハンドブックへ。
Handbooks は同じコードの地図を二通りに書き出します。読者がまったく異なるからです：
📖 人間向けハンドブック
ステージごとに語られるドキュメントサイト——検索・テーマ・ディープリンク——コードから生成され、file:// から直接開けます。あなたが読む一冊です。
🤖 AI 向けハンドブック
機械向けの位置インデックス：ファイル→ステージのルーティング表、関数ごとの呼び出し事実、llms.txt、インストール可能な SKILL パッケージ。コーディングエージェントが読む一冊です。
土台は同じ事実——パーサーが構築したコールグラフ——なので、二冊が食い違うことはありません。 一冊は物語と探索のために、もう一冊はルーティングと陳腐化検出のために最適化されています。
問題を率直に述べると
リポジトリがあります。頭の中に収めるには大きすぎ、コンテキストウィンドウに収めるにも 大きすぎます。
コーディングエージェントに「失敗したアップロードを 3 回リトライして」と頼むと、 エージェントは見つけた 1 つのアップロード関数を自信満々にパッチします — そして、 リトライポリシーの定数、バッチワーカー内のミラー実装、試行回数を数えるメトリクス、 旧挙動をアサートするテストを見落とします。
これは推論の失敗ではありません。ルーティングの失敗です。エージェントは一度も マップを見ていないのです。
一文で言えば
Handbooks は本物のパーサーでコードを読み、そのマップを構築し、要約ではなく ロケーションインデックスとしてエージェントに渡します — そしてコードが動いても マップを最新に保ちます。
読み進める前にまず動かす
動かなければ、この先の説明に意味はありません。所要時間は約 30 秒、トークン消費はゼロ、 API キーも不要です:
git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demopnpm demo は、同梱のサンプルプロジェクトに対し、同梱のモック LLM サーバーを使って
ツールチェーン全体を実行します。完了すると、レンダリング済みのハンドブック、HTML
サイト、エージェント用ロケーターインデックス、検証済みの SKILL パッケージがディスク上に
揃っています。
土台となる 3 つのアイデア
1. 事実はモデルではなくパーサーから
Handbooks は tree-sitter ですべてのソースファイルを
解析し、型付きコールグラフを構築します: 関数、メソッド、self・属性・パラメータ・
インポートを通じて解決された呼び出しエッジ、あなたのコードの外へ出ていく呼び出し、
そして解決できなかった呼び出し — 最後のものは専用のファイルに隔離され、決して推測で
補われません。
そもそも読めなかった、あるいは解析できなかったファイルも同じように隔離されます。欠落は 列挙できるものであって、黙って消えるものではありません。
このレイヤーは LLM に一切触れません。 2 回実行すれば、2 回とも同じグラフが得られます。
2. 文章は事実の上に重ねられ、そうと分かるようにラベル付けされる
人間が読む部分は LLM が書きます: このファイルは何のためにあるか、このサブシステムは どうつながっているか、どの状態がどのステージ間を流れるか。文章は常にグラフに アンカーされ、生成に失敗した場合でも構造はそのまま出荷されます — 説明が空のままで。
でっち上げられた一文より、欠けている一文のほうがましです。
3. マップは読むためではなく、ルーティングのために作られる
出力はコードの要約ではありません。「この変更はどのファイル・関数・状態に触れなければ ならないか？」に答えるインデックスです — 散在していて見つけにくいものも含めて。 プランナーはそのインデックスでルーティングし、見つけたすべてのアドレスで実際のソースを 読み、機械的に適用できるほどバイト精度の高い編集プランを出力します。
1 回の実行で得られるもの
| 出力 | 対象 |
|---|---|
| Markdown ハンドブック — 概要、ステージ索引、ステージごとに 1 ページ、状態レジスタの表 | 人間 |
複数ページの HTML サイト — 固定 TOC、パンくずリスト、テーマ切り替え、file:// でも動作 | 人間 |
| メールでも送れる、自己完結型の HTML 1 ページ | 人間 |
エージェント索引 — シンボル → path:line-line、ファイル表と呼び出し表、grep レシピ | エージェント |
llms.txt + llms-full.txt | エージェント |
| ファイルごとのコンテンツハッシュ付き SKILL パッケージ — ドリフトを検出可能にします | エージェント |
誰のためのものか
| あなたは… | 得られるのは… |
|---|---|
| 20 万行のサービスを引き継いだばかりのエンジニア | 実際に読み通せるステージごとのウォークスルーと、共有できる HTML サイト |
| 大きなリポジトリでコーディングエージェントを使う人 | エージェントに「どこにあるか」を推測させない SKILL パッケージ |
| メンバーをオンボーディングするチームリード | 腐る代わりに再生成されるドキュメント |
| 多言語のモノレポを保守する人 | 18 言語を一度に解析し、言語ごとの解析忠実度を開示 |
必要なもの
- Node.js ≥ 20.11 と pnpm。 インストールに必要なのはこれだけです。ネイティブ
コンパイルも、Python も、
node-gypも不要 — パーサーは WebAssembly です。 - OpenAI 互換のエンドポイントが LLM フェーズに必要です。ホステッドの OpenAI、
Azure、vLLM、Ollama、LiteLLM、社内プロキシ —
/v1/chat/completionsを話せるものなら 何でも。あなたのマシン上で動くモデルでも構いません。 - 何も要りません — 最初に実行すべきコマンドである
handbook analyzeには。
コードは外に出ますか？
Phase 1 は完全にローカルです。Phase 2 と 3 は、あなたが設定したエンドポイントに ファイル内容を送信します —
それは localhost でも構いません。それ以外は何も外に出ず、 --max-chars-per-file が 1
ファイルあたりの送信量に上限を設けます。 信頼モデルを参照してください。