ステージ、カード、レジスタ、作業ディレクトリ、ケース、スキル、プラン — このプロジェクトが特定の意味で使うすべての言葉を、一度だけ定義します。

Handbooks は、いくつかのありふれた言葉を特定の意味で使います。これらを正しく押さえておくと、他のすべてのページが短くなります。

成果物

コールグラフ (call graph)

Phase 1 の出力。コード内のすべての関数とメソッドに加え、それらの間のすべての呼び出しエッジが、どのように解決されたかで型付けされて含まれます。パーサーが生成するものであり、モデルが生成することは決してありません。

<work>/phase1/graph.json にあります。下流のすべてがこれを読み、何もソースを再パースしません。

スキャンカバレッジ (scan coverage)

Phase 1 の誠実さのもう半分。アナライザが事実へ変換できなかったファイルの一覧で、 1 つずつ理由が付きます — unreadable（読み取りが失敗した）、unparsable（文法が例外を投げた）、partial（パースはできたが構文エラーを含むため、その事実は本物でも不完全）。

前の 2 つはグラフの scannedFiles からも取り除かれるため、パーサーが一度も開いていないファイルを下流が記述することはありません。一覧が空であることは「すべてパースできた」という主張です。ファイルが存在しないことは、主張ではありません。 <work>/phase1/scan-coverage.json にあります。

カード (card)

ソースファイルごとに 1 つ。「このファイルは何のためにあるのか?」に 3 つのフィールド — purpose、role、lifecycle — で答えます。さらに --detail deep では、120–300 語のウォークスルーと関数ごとのノートが付きます。

カードの構造的な半分はグラフに由来し、文章の半分は LLM に由来します。文章が失敗しても、カードは空の説明のまま存在し続けます。<work>/phase2/cards/<path>.json にあります。

カードの role は閉じた語彙から選ばれます: entrypoint, orchestration, domain_logic, io_transport, data_model, config, util, test, generated, other。モデルが発明したそれ以外の値は other に収束します — 創造的な回答によって集合が広がることはありません。

ステージ (stage)

ハンドブックの 1 章。ステージは id、タイトル、説明、任意の親、そしてライフサイクルのどの段階にも属さないインフラのための crosscut フラグを持ちます。

ステージは実行ライフサイクルの順に並びます。アルファベット順でもディレクトリ順でもありません — ハンドブックは、システムが実際に動く順序で読めるようになっています。

スケルトン (skeleton)

ステージの順序付きリスト: 物語の背骨です。LLM が合成する（--strategy file）か、 あなたが書きます（--strategy member）。<work>/phase2/skeleton.yaml にあります。

割り当て (assignment)

各ファイルがどのステージに属するか。すべてのファイルはちょうど 1 つのプライマリステージを持ち、加えて関わりのある他のステージを列挙できます。<work>/phase2/assignment.json にあります。

編成 (organization)

ステージ内で、ファイルをコールグラフのトポロジー順に並べ、タイトル付きの 2–8 個のサブグループにまとめたもの。<work>/phase2/organization.yaml にあります。

ナレーション (narration)

文章です: ステージごとの要約が 1 つずつと、システム概要。ボトムアップ — 子が親より先 — に書かれるため、親ステージの要約は子が何を言っているかを知ったうえで書けます。 <work>/phase3/narration.json にあります。

レジスタ (register)

ステージを横断して流れる状態のひとかけら: コネクションプール、フィーチャーフラグ、リトライバジェット、認証トークンなど。各レジスタは id、平易な言葉によるセマンティクス 1 行、そしてそれに触れるステージの一覧を持ちます。

レジスタはファンアウトする変更にとって唯一最も有用な成果物です。「どのステージがこの状態に触れるか」こそ、散らばった変更が発する問いそのものだからです。 <work>/phase3/registers.json にあります。

ディレクトリ

作業ディレクトリ (work directory)（`--work`）

パイプラインのすべての成果物が置かれる場所。ドキュメント化するリポジトリごとに 1 つです。

<work>/
  phase1/   graph.json · functions.csv · graph.dot · dropped-calls.json · scan-coverage.json
  phase2/   cards/ · skeleton.yaml · assignment.json · organization.yaml · strategy.json
  phase3/   narration.json · registers.json · cache/
  handbook/ the rendered output, once you run `render`
  run-manifest.json

削除して再生成しても安全で、ハンドブックをバージョン管理下に置きたければコミットしても安全です。生成によってこの外側が変更されることはありません。

ハンドブックディレクトリ (handbook directory)

「レンダリングされた」出力 — markdown、そして任意で HTML、エージェント索引、llms.txt。デフォルトは <work>/handbook です。

スキルディレクトリ (skill directory)（`skill` の `--out`）

パッケージ化されたエージェント SKILL: SKILL.md と references/。自己完結で共有可能。ソースコードを埋め込むことは決してありません。

ケースディレクトリ (case directory)（`resync` の `--case`）

変更を記述するために resync に渡すもの:

<case>/
  edited/       the changed source tree             REQUIRED
  plan.md       what the change was                 optional — sharpens scope
  change.diff   unified diff vs the previous tree   optional — widens scope

コマンド一覧 — 各 1 行

コマンド	1 行で	LLM?
`analyze`	ソース → コールグラフ	❌
`generate`	コールグラフ → カード、ステージ、文章、レジスタ	✅
`render`	作業ディレクトリ → markdown / HTML / エージェント索引 / llms.txt	❌
`skill`	レンダリング済みハンドブック → エージェント SKILL パッケージ	❌
`validate`	SKILL の構造と鮮度をチェック	❌
`plan`	変更リクエスト + ハンドブック → バイト一致の編集プラン	✅
`apply`	編集プラン → 実際の編集、バックアップ付き	❌
`rollback`	バックアップ → 復元されたソースツリー	❌
`resync`	変更されたコード → インクリメンタルに更新されたハンドブック	✅
`studio`	上記すべてを、ブラウザで	✅
`config`	何が設定されていて、それがどこから来たか	❌

フェーズ

Phase	生成物	LLM?
`1`	コールグラフ	❌
`2a`	スキャンしたファイルごとのカード	✅
`2b`	スケルトン + 割り当て	✅
`2c`	編成	✅
`3`	ナレーション + レジスタ	✅

--phase は all、1、2（2a+2b+2c の意味）、任意の単一フェーズ、または 2c,3 のようなカンマ区切りリストを受け付けます。

2 つの戦略

	`file`（デフォルト）	`member`
スケルトン	LLM が合成	あなたが `skeleton.yaml` を書く
末端の単位	ソースファイル 1 つ	関数またはメソッド 1 つ
向いているのは	まだ知らないリポジトリ	形をすでに知っているリポジトリ
コスト	低い	高い — すべてのメンバーを分類する

混同しやすい 2 つの言葉

忠実度ティア (fidelity tier) — その言語の「解析」がどれほど良いか。full（手書きのアダプタ）または generic（設定駆動のエンジン）。アダプタごとに宣言され、言語ごとに記録され、ハンドブックの概要で開示されます。解析忠実度を参照してください。

詳細度 (detail) — 「文章」がどれほど深いか。brief（purpose、role、lifecycle）または deep（加えてウォークスルーと関数ごとのノート）。--detail で設定します。

両者は独立です: generic ティアの言語でも deep なカードを持てます。深くなるのは文章であって、呼び出しの事実が確かになるわけではありません。

用語集

成果物