ハンドブックの生成

handbook generate --source <repo> --work <workdir> [options]

これはコストのかかる唯一のコマンドです。このページの内容はすべて、その支出を抑えつつ、 より多くの成果を得るためのものです。

安く始めて、あとからアップグレードする

handbook analyze --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK --phase 2a --detail deep --resume

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

この順序で進めれば、これから捨てることになるスケルトンの上に深いカードの費用を払うことは 決してありません。

--detail brief と deep の比較

エージェントがハンドブックを使うなら deep の価値があります。 関数ごとのノートこそが、 ステージページを住所録に変えるものだからです。brief が適しているのは、最初の 1 回目、 非常に大きなリポジトリ、あるいは主に構造だけが欲しい場合です。

混在も可能です。まず全体を brief で生成し、その後 --source を最も重要なサブディレクトリに 向けて --phase 2a --detail deep --resume を再実行します。

--synth-mode oneshot と doctor の比較

oneshot は 1 パスでスケルトンを合成します。高速かつ安価で、たいていは妥当な結果になります。

doctor はアクター・クリティック方式の修復ループを実行します。最大 3 件の構造変更を提案し、 3 人の批評者(エンジニア、アーキテクト、読者)がレビューし、生き残った提案を実際のグラフに 対して機械的に検証し、適用して再割り当てし、これを繰り返します。

--strategy file と member の比較

file(デフォルト) — LLM がスケルトンを合成し、ソースファイルが葉の単位になります。 大規模リポジトリにもスケールします。特に理由がなければこちらを使ってください。

member — skeleton.yaml を書くのは あなた です。個々の関数とメソッドがあなたの 定義したステージに分類され、ファイルレベルの成果物はそこから導出されます。

metadata:
  version: 1
  archetype: HTTP API server
stages:
  - id: stage-1
    title: Request intake
    description: Accepting connections, parsing requests, and routing them.
    parent: null
    children: []
    crosscut: false
  - id: stage-2
    title: Business logic
    description: What the service actually does with a validated request.
    parent: null
    children: []
    crosscut: false
  - id: crosscut-1
    title: Configuration and logging
    description: Cross-cutting infrastructure used by every stage.
    parent: null
    children: []
    crosscut: true

handbook generate --source $REPO --work $WORK --strategy member --skeleton skeleton.yaml

member はすべての関数を分類するためコストは高くなりますが、より締まった文章が得られ、 組織化が決定的に導出されるため Phase 2c は無料になります。

フェーズを個別に実行する

--phase 1        # just the graph (same as `handbook analyze`)
--phase 2a       # just the cards
--phase 2b       # just skeleton + assignment
--phase 2c       # just the grouping
--phase 3        # just narration + registers
--phase 2        # 2a + 2b + 2c
--phase 2c,3     # a comma list

各フェーズは自分の上流の成果物だけを読むため、これは常に安全です。よくあるパターンは次のとおりです。

再開とキャッシュ

• --resume は、要求された詳細度で完全なカードがすでに存在するファイルをスキップします。 カードは完成するたびに書き出されるため、Ctrl-C はいつでも安全です。
• --llm-cache は生の応答を <work>/phase3/cache 以下に、モデル・プロンプト・オプションを キーとしてキャッシュします。試行錯誤中の再実行はほぼ無料になります。
• --refresh は Phase 3 のキャッシュを無視します。プロンプトの入力を変更したのにキャッシュキーが それに気づかない場合 — たとえば skeleton.yaml を手で編集した後 — に使ってください。

--refresh はその実行に限り --llm-cache を無効にします。これは意図的な仕様です。

動作を観察する

handbook generate --source $REPO --work $WORK -v

[scan] auto root=/Users/me/code/api
[scan] typescript: 284 files
[2a] batch 12/36 · 96 cards
[2b] 9 stages; 0 files unassigned
[3] narrating stage-4 (2 children)

実行が完了すると、トークン使用量は run-manifest.json に記録されます。

結果が間違っているとき

詳しくはトラブルシューティングを参照してください。