はじめに
クイックスタート
ツールチェーン全体を約 30 秒でエンドツーエンドに実行します — オフラインで、API キーなし、トークン消費ゼロ。
Handbooks が何をするものかを理解する最短の方法は、実際に動くところを見ることです。 これはすべてのパイプライン — 解析、生成、レンダリング、パッケージング、検証 — を、 同梱のサンプルプロジェクトに対して、同梱のモック LLM サーバーで実行します。
API キー不要。ネットワーク不要。トークン消費ゼロ。
ステップ 1 — 実行する
git clone <this repo> && cd handbooks
pnpm install
pnpm build
pnpm demoステップ 2 — 出力された内容を読む
== build ==
== start mock LLM (offline; prose will be placeholder text) ==
== 1. analyze (no LLM) ==
{ "language": "multi", "files": 5, "functions": 23, "edgesKept": 31, "edgesDropped": 4, "filesUnparsed": 0 }
== 2. generate (phases 2+3) ==
{ "phasesRun": ["2a","2b","2c","3"], "nCards": 5, "nStages": 4, "nRegisters": 2 }
== 3. render markdown + HTML site + agent index + llms.txt ==
== 4. package as an agent SKILL (with the agent locator pages) ==
== 5. validate the SKILL ==
validate: OK文章が意味不明なのは想定どおりです
モック LLM はプレースホルダーテキストを返します。構造は完全に本物です — ステージ、ファイルの割り当て、 呼び出しの事実、行範囲、レジスタの表、すべてのリンク。偽物なのは文だけです。これこそが、このプロジェクトの 土台となる分離です: 事実はパーサーから、文章はモデルから。
ステップ 3 — 結果を開く
open examples/work/demo/handbook/overview.md # the markdown handbook
open examples/work/demo/handbook/html/overview.html # the multi-page HTML site
open examples/work/demo/handbook/handbook.html # the whole thing in one file
open examples/work/demo/skill/SKILL.md # the agent SKILL package特に見ておく価値があるもの:
| これを開いて | 注目すべき点 |
|---|---|
handbook/overview.md | コールグラフから生成された mermaid のステージマップ |
handbook/index.md | すべてのステージが入れ子で並び、それぞれに段落が付いている |
handbook/register.md | ステージ横断の状態と、それぞれに触れるステージ |
handbook/agent/index.md | エージェントインデックス — 検索レシピ、ステージ表、カバレッジ。まるごと読むもの |
handbook/agent/symbols.tsv | すべてのシンボル → path:startLine-endLine。文章のページが決して持たなかったものです |
skill/references/coverage.json | ファイルごとのコンテンツハッシュ。これがドリフトのシグナルです |
work/demo/phase1/dropped-calls.json | アナライザーが解決できなかった呼び出し。推測せず、分類したうえで保持されます |
work/demo/phase1/scan-coverage.json | アナライザーが読み取り、あるいは完全にパースできなかったファイル。ここが [] なら 5 ファイルすべてパースできています |
ステップ 4 — 内部をのぞく
パイプラインが生成したものはすべて、作業ディレクトリ内のプレーンな JSON と YAML です:
ls examples/work/demo/
# phase1/ phase2/ phase3/ handbook/ skill/ run-manifest.json
cat examples/work/demo/phase1/graph.json | head -40
cat examples/work/demo/phase2/skeleton.yaml
cat examples/work/demo/run-manifest.json # model, phases, timings, token usageこれらはすべて、読み込み時にスキーマ検証されます。手で編集して不正な状態にしても、 次のコマンドがどのファイルがなぜ不正かを教えてくれます — 後段へは伝播しません。
その他のデモ
pnpm demo:self # this repo as its own input, against the mock LLM
pnpm demo:self:real # same, but against the real endpoint from .env
pnpm mock-llm # just the mock server, on port 8099読んで面白いのは pnpm demo:self のほうです: 11 個の実在する TypeScript パッケージを
解析するため、生成されるステージ構造は、本物のコードベースの本物のマップになります。
いま何が起きたのか
analyzeが、tree-sitter で読み取れたすべてのファイルを解析して型付きコールグラフを 構築し、読み取れなかったものをphase1/scan-coverage.jsonに書き出しました。LLM 不使用。generateが、ファイルごとにカードを書き、ステージのスケルトンを合成し、 すべてのファイルをステージに割り当て、グループ化して並べ、それからボトムアップで ナレーションを書き、ステージ横断の状態レジスタを抽出しました。renderが、それを markdown、HTML サイト、自己完結の 1 ページ、エージェント用 ロケーターインデックス、llms.txtに変換しました。LLM 不使用。skillが、ファイルごとのコンテンツハッシュを持つエージェント SKILL として 再パッケージしました。LLM 不使用。validateが、構造、フロントマターの契約、索引 ↔ ステージページのリンク、 ハッシュの鮮度を検査しました。LLM 不使用。
デモはここで終わりです。残りの半分 — plan → apply → rollback → resync — は、
初めてのハンドブックと
変更の計画で扱います。