Unfold — コードベース可視化ツール は何をしますか？
1 枚の自己完結型 HTML ページを生成します。概要図を起点に、レベルごとにシステムの各部分へ展開していきます。エンジン (assets/template.html) が描画、レイアウト、ズーム、トレース、編集を担当します。あなたの役割はコードを理解し、図のデータ (JSON) を書くことです。プロジェクトを何も知らない読者が、最後には説明できるようになります。
各レベルでは、「何が入力され、何が起こり、何が出力されるか」の 3 つの質問に答えます。
品質基準
- 正確であること。 すべてのノードとエッジは、実際に確認したコードに基づいています。
sourceにはその場所 (path/file.py:symbol) を記述します。すべてのノードにconfidenceをread、peeked、inferredのいずれかでマークします。推測されたものはユーザーにリスト表示されます。 - コードベースに合わせること。 プロジェクト自身の語彙（モジュール名、トピック名、ルート名をそのまま）と、各部分に合った図タイプ（ステップ 4 参照）を使用します。
- 控えめにすること。 ラベルは 2〜4 語、キャプションは 1 行、ノートは 1〜3 文とし、それ以上は書きません。詳細は 1 クリックまたは 1 ホバー先にあり、キャンバス上には置きません。
- ゼロからナビゲート可能であること。
meta.summaryはシステムの目的を 1 文で表します。短いmeta.glossaryはプロジェクトの専門用語を定義します。ノートは、ホバーヒントとして機能する文で始まります。
ワークフロー
1. リクエストを組み立てる
意図が最優先です: マップの目的です。スコープ、深さ、レベルタイプ、ツアー、メディア、用語集を設定します。references/intents.md に各意図のデフォルトがあります。
- プロンプトで既に意図が示されている場合は、質問しないでください。「このプロジェクトを案内してください」は 学習 です。「リトライロジックはどのように動作しますか？」は 説明 です。「この PR は何を変更しますか？」は レビュー です。「金曜日にこれを発表します」は デモンストレーション です。
- それ以外の場合は、スキャン前に 1 つ質問します。選択肢は以下の通りです：コードベースを学習する、自分の作業をデモする、特定の詳細を説明する、変更をレビューする、または その他（文書化や引き継ぎ、1 つのパスをデバッグ、リファクタリングの計画、データフローの監査）。
- その後、最大 2 つのフォローアップ質問をします。
references/intents.mdからその意図に合わせて選びます。会話ですでに答えが出ているものはスキップします。 - 回答を
meta.intentとmeta.audienceとして記録します。 既存のページを拡張する場合は、再度質問せずにそのmeta.intentを再利用します。
次に、会話から、または同じ短いバッチで、以下を確定させます:
- scope: どのリポジトリまたはその一部か
- audience: 新人開発者、レビューア、マネージャー、またはトーク
- focus: 最も重要な部分（最も深く掘り下げる部分）
- confidentiality: ページは共有されるため、特に指示がない限り、ホスト名、シークレット、顧客名、未発表の計画は除外します
コードがない場合は、ユーザーの説明から作業します。部分、フロー、数値を発明してはいけません。
2. コードベースを段階的に、予算内で読む
大規模なリポジトリはコンテキストに収まらず、ファイル全体にざっと目を通すのは無駄です。段階的に読み、図の根拠が得られたらすぐに止めます。
| 段階 | コマンド | 得られるもの | コスト |
|---|---|---|---|
| マップ | python scripts/scan_repo.py REPO [--section NAME] | 言語、レイアウト、マニフェスト、エントリーポイント、I/O シグナル（file:line 付き）、パート間のインポート、最初に読むべき リスト | 小 (--budget で制限) |
| 形状 | python scripts/scan_repo.py REPO --outline [PREFIX] | すべてのクラスと関数（シグネチャと最初の docstring 行を含む、本体なし） | 中 (--budget で制限) |
| 証拠 | python scripts/peek.py REPO file:line file:symbol ... | 各参照の周辺行のみ（マージ済み、固定の行数・トークン予算内） | 小 (呼び出しごと) |
| 深掘り | ファイル全体を読む | ユーザーの注目領域にある、コアロジックを持つ 3〜8 ファイルのみ | 大 |
段階の進め方:
- README、ドキュメント、マップから始めます。
- 重要なフォルダには Outline を使用します。大規模なリポジトリでは、全体に対してではなく、トップレベルのパートごとに実行します。
- 描画予定のすべての I/O シグナルとエントリーポイント、およびすべてのプロセスレベルの背後にある関数に対して
peekを使用します。 - ロジックが本当に複雑な場合にのみ、ファイル全体を読みます。
- 証拠リスト（ノード →
file:symbol）を継続的に保持します。これがsourceフィールドになります。 - スキャンは正規表現ベースです。動的な配線を見逃したり、文字列内のパターンなど偽陽性を報告することがあります。描画前に
peekで確認します。
トークン予算。 すべてのコマンドはコスト（≈N トークン）で終了します。マップに必要な分だけを使用します:
- アウトラインを取得する前にファイル全体を読まないでください。
file:symbolをピークし、広い行範囲は避け、参照を 1 回のpeek呼び出しにまとめます。 - カットリストは
… N more; rerun with --section Xで終わります。図に必要な場合のみ取得します。大規模なリポジトリでは、--outline PREFIXで一度に 1 パートずつアウトラインを作成します。 - 描画予定のすべてのノードに
sourceが設定されたら、読み取りを停止します。 unfold.py checkとoutlineで確認します。JSON やページを再読み取りしないでください。diagram.jsonを小さな編集で修正します。全体を再出力しないでください。
コスト、スキャンキャッシュ、スキップされるもの: references/reading-code.md（トークン予算）。
3. システム境界を確定する
入力（リクエスト、サブスクライブされたトピック、CLI 引数、読み取りファイル、センサー、設定）と出力（レスポンス、パブリッシュされたトピック、書き込みファイル、コマンド、DB 書き込み）をリストアップします。すべてのアーキテクチャレベルとプロセスレベルで、`