出力のレンダリング
Markdown、HTML サイト、単一の自己完結ページ、エージェント用ロケータインデックス、llms.txt — すべて決定的で、何度でも無料で再実行できます。
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]LLM なし。ネットワークなし。決定的。 同じモデルを入力すればバイト単位で同一のファイルが 出力されます — だからこそ CI に組み込み、コミットごとに実行するのに向いています。
5 つの出力
常に書き出されます。
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)ステージページには、ステージの要約、サブステージへのリンク、そしてそのファイル群が載ります — グループ化と順序は Phase 2c が決めたとおりで、各ファイルは ファイルカード として レンダリングされます: 目的、役割、ライフサイクル、呼び出しの事実、そして deep カードの場合は 関数ごとのノートです。
知っておく価値のある挙動が 2 つあります。
- 古くなったページはクリーンアップされます。 ステージ ID は生成のたびに変わります。 各レンダリングはまず前回のレンダリングのページを削除するので、名前が変わったステージが ゴーストページを残して、スキルのパッケージャに拾われることはありません。
- ステージごとの状態レジスタセクションは冪等です — マーカーの下に追記されるのは、 マーカーが存在しないときだけです。再レンダリングしても重複が積み重なることはありません。
ソースへのリンク
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainハンドブック内のすべてのファイルパスが、実際のファイルへのリンクになります。ハンドブックが
生成元のコードを参照し続けるようにしたい場合は、main の代わりにタグやコミット SHA を
指定してください。
このフラグを付けない場合、出力には外部 URL が一切含まれません。 これはプライベートな コードベースにとって正しいデフォルトです。
タイトルと言語
handbook render --work $WORK --title "Payments Service — Engineering Handbook"ナレーションの言語は生成時に固定され(--narrate-lang)、phase3/narration.json に
保存されます。レンダラーはそこから言語を読み取ります — すべてのラベル、見出し、テーブルの
ヘッダーがそれに合わせてローカライズされます。構造はどちらの言語でも同一 なので、
出力を読むツールはどちらの言語なのかを知る必要がありません。
再レンダリングを習慣に
レンダリングは無料かつ決定的なので、CI に組み込みましょう:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .CI 統合を参照してください。
HTML サイトの公開
出力は相対リンクのみで外部アセットを持たない静的ディレクトリなので、どんな静的ホストでも 動作します:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlエージェントが見つけられるよう、サイトのルートで llms.txt を配信してください。