はじめての本格的なハンドブック
一度も読んだことのないリポジトリから、適用できる変更プランまでの 8 ステップ — 安価なチェックポイントを適切な場所に配置しています。
これは実際のリポジトリを使った一連の流れの全体です。順番どおりに進められるように書かれており、 無料のチェックを高価なものより先に置いているのは意図的です。
alias handbook="node $(pwd)/packages/cli/dist/main.js"
export REPO=~/code/myrepo
export WORK=work/myrepoステップ 1 — 飛び込む前に見る
handbook analyze --source $REPO --work $WORK{
"language": "multi",
"files": 412,
"functions": 3187,
"edgesKept": 9042,
"edgesDropped": 611,
"filesUnparsed": 3
}これは無料で、あなたのスモークテストです。 LLM なし、キーなし、トークンなし。
先へ進む前にこの数値を読んでください
filesが予想よりはるかに少ない? 1 つの言語がまるごとスキップされているか、ソースルートが間違っています。-vでスキャンログを確認してください。 -filesがはるかに多い?node_modulesやvendor、あるいは ビルドディレクトリを解析しています。よくあるものは自動でスキップされます。そうでない場合は、リポジトリの ルートではなく本当のソースルートに--sourceを向けてください。 -edgesDroppedがedgesKeptに比べて 非常に大きい? 動的言語では正常です。phase1/dropped-calls.jsonを見てください — 解決できなかった呼び出しは すべてそこで分類されており、隠されてはいません。 -filesUnparsedが 0 ではない? それらのファイルはphase1/scan-coverage.jsonに理由付きで名指しされています。unreadableとunparsableのものは何も生まず、ページも得られないため、 いま作るハンドブックにはちょうどそこに穴が空きます — 文章にお金を払う前に直す価値があります。
上記の問題はいま直してください。ここでのすべての問題は、後でより高くつく問題になります。
ステップ 2 — ハンドブックを生成する
これがトークンを消費するステップです。中規模のリポジトリなら数分を見込んでください。
まずは安く始めます:
handbook generate --source $REPO --work $WORKこれは --detail brief と --synth-mode oneshot です: ファイルごとの短いカードと、
シングルパスのスケルトン。ハンドブックの「形」が正しいかどうかを確かめる最速の方法です。
$WORK/phase2/skeleton.yaml を見てください。ステージの一覧はあなたのシステムらしく
見えますか? そうであれば、アップグレードします:
handbook generate --source $REPO --work $WORK \
--phase 2a --detail deep --resume--phase 2a --resume はカードだけを深掘りし、すでに完全なカードを持つファイルは
スキップします。検証済みのスケルトンはそのまま保たれます。
スケルトンが「間違っている」場合は、代わりにアクター–クリティックのループで 2b を再実行します:
handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor再開可能、中断可能、キャッシュあり
カードは完成した順に書き込まれます。Ctrl-C は安全です。--resume
は止まったところから再開し、--llm-cache は再実行をほぼ無料にし、run-manifest.json
には最後に成功したランのトークンコストが記録されます。
ステップ 3 — レンダリングする
handbook render --work $WORK --title "MyRepo Handbook" \
--html --html-single --agent-site --llms-txtLLM なし。 好きなだけ実行してください — CI でも、コミットごとでも。
--source-base-url https://github.com/me/myrepo/blob/main を加えると、ハンドブック内の
すべてのファイルパスが実ファイルへのリンクになります。指定しなければ、出力に外部 URL は
一切含まれません — プライベートなコードベースでは重要な性質です。
$WORK/handbook/html/overview.html を開いて読んでください。ハンドブックの出来を判断するのは
この瞬間です。
ステップ 4 — エージェント向けにパッケージングする
handbook skill --handbook $WORK/handbook --out skills/myrepo \
--name myrepo --project "MyRepo" \
--work $WORK --source $REPO \
--agent-dir $WORK/handbook/agent--work と --source を一緒に渡すと coverage.json が生成されます: ファイルごとの
コンテンツハッシュです。これがあることで、ハンドブックのドリフトは後から検出可能になります
— 黙って間違ったままになるのではなく。
--agent-dir はエージェントインデックスとその事実テーブルを同梱し、SKILL のルーティング
プロトコルに grep レシピを与えます — エージェントは、文章を読んで推測する代わりに、
シンボル名を 1 つのコマンドで path:startLine-endLine に変えられます。
ステップ 5 — 検証する
handbook validate --skill skills/myrepo --source $REPO構造、frontmatter の契約、索引 ↔ ステージページの整合性をチェックし、ソースを再ハッシュして
遅れをとったページを報告します。失敗時は終了コード 2 なので、CI に入れるべきはこの
コマンドです。
ステップ 6 — 実際の変更を計画する
handbook plan --source $REPO --handbook skills/myrepo/references \
--request "Retry failed uploads three times before giving up" \
--out plan.md読み取り専用のエージェントループです: 一覧を取り、読み、grep します — 書き込みツールは
そもそも存在しません — ハンドブックでルーティングし、実ソースに照らして検証し、plan.md を
書きます。
プランを読んでください。本当に読んでください。末尾には機械可読な宣言ブロックがあります:
### EDIT 1
- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper
```old
response = self._client.put(url, data)
```
```new
response = self._retry(lambda: self._client.put(url, data), attempts=3)
```
```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```諦めたプランナーは非ゼロで終了します
使えるプランを作れなかった場合 — ファイル内容を捏造し続けた、ターンを使い切った、など — は、スクリプトが
そのまま apply に流し込んでしまうような謝罪文を plan.md に書く代わりに、大きな音を立てて失敗します。
ステップ 7 — 適用する。戻り道を確保して
handbook apply --source $REPO --plan plan.md --dry-run # verify only, never writes
handbook apply --source $REPO --plan plan.md # for realドライランは、その精神において省略可能ではありません。現在のファイル内容に対してすべての アンカーを解決し、どの編集が着地するのかを正確に教えてくれます。
適用するとバックアップディレクトリが表示されます。必要になる前に、どこかへコピーして おいてください:
handbook rollback --backup $REPO/.handbook-patches/2026-08-08T14-05-11-204Zロールバックは、パッチの「後」に変更されたファイルを、--force を渡さない限り拒否します —
復元すればその作業を黙って破壊してしまうからです。4 つの安全ルールすべては
変更の適用 を参照してください。
ステップ 8 — ハンドブックを前進させる
コードは動きました。再生成せず、resync してください。
ケースとは、あなたが組み立てるディレクトリです:
cases/upload-retry/
edited/ copy of the repo after the change (required)
plan.md the plan from step 6 (optional — sharpens scope)
change.diff unified diff of the change (optional — widens scope)mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
handbook resync --case cases/upload-retry --work $WORKresync は編集後のツリーを再解析し、新旧のグラフを差分比較して、変わったものだけを
再生成します。$WORK/handbook 配下のレンダリング済み出力は自動的に更新されます。
手元にエンドポイントがない? --no-llm は構造的な事実を更新し、文章については最新のふりを
させる代わりに「古い」と印を付けます。
リポジトリが非常に大きい場合
| 症状 | 対処 |
|---|---|
| ファイルが数千ある | まず --detail brief から。後で --phase 2a --detail deep --resume で選んだフェーズを深掘りします。 |
| ランが遅い | --read-workers / --assign-workers / --narrate-workers を上げます。いずれも --llm-concurrency の範囲内で。 |
| レート制限 | --llm-concurrency を下げます。--llm-retries と --llm-retry-backoff を上げます。 |
| 巨大な生成ファイル | --max-chars-per-file 20000 がファイルごとの送信量を切り詰めます。 |
| 1 つのサブシステムだけが対象 | そのサブディレクトリに --source を向けます。グラフはスキャンしたものから構築されます。 |
| 反復しながらの再実行 | --llm-cache、そして意図的にキャッシュを無視したいときは --refresh。 |
詳しくは コストとパフォーマンス を参照してください。