walkthrough

コードベースのウォークスルー生成ツール

新しい開発者が機能やシステムの仕組みをすばやく把握するためのメンタルモデルを得られるよう、クリック可能な Mermaid 図を含むインタラクティブな HTML ファイルを生成します。目標は、すばやくオンボーディングできるようにすることです。コードリファレンスではなく、概念とつながりを大まかに示すマップを作成します。各ウォークスルーは 2 分以内で読める内容にしてください。

重要：このスキルが起動されたら、必ず walkthrough-*.html ファイルを生成してください。テキストだけで応答してはいけません。必ずインタラクティブな HTML を出力してください。

常にダークモードにしてください。 すべてのウォークスルーでは、純粋な黒の背景（#000000）、白いテキスト、紫のアクセントを使用します。ライトモードのウォークスルーは生成しないでください。<html> タグには必ず style="color-scheme: dark" を含めてください。

ワークフロー

ステップ 1：対象範囲を把握する

ユーザーが何について説明を求めているのかを明確にします。

• 特定の機能の流れ（例：「キャンバスの描画はどのように動作しますか」）
• データフロー（例：「コンポーザブルからコンポーネントへ状態はどのように流れますか」）
• アーキテクチャの概要（例：「機能はどのように整理されていますか」）
• リクエストのライフサイクル（例：「ユーザーが描画をクリックすると何が起きますか」）
• データベーススキーマ（例：「テーブルとリレーションシップについて説明してください」）
• データモデル（例：「ユーザーデータはどのように構成されていますか」）

トピックが指定されていない $walkthrough の場合は、プロジェクト全体の概要を示すウォークスルーを生成します。主要なモジュール、それらのつながり、全体的なアーキテクチャを示してください。

初めて使う人のためのメンタルモデルとしてウォークスルーを構成してください。「重要な概念は何か、そしてそれらはどのようにつながっているか」を考えます。

依頼が曖昧な場合（単独の $walkthrough のみの場合を除く）は、確認の質問を 1 つしてください。それ以外は、そのまま進めてください。

ステップ 2：並列のサブエージェントでコードベースを調査する

生成前に、必ず実際のソースファイルを読んでください。 コードパスを捏造してはいけません。

Task ツールを使って、調査をサブエージェントに委任してください。 これにより、HTML 生成にメインコンテキストを使えるようになり、調査フェーズを並列化できます。

2a. 調査対象を特定する

まず自分で簡単な Glob/Grep を（最大 1～2 回）実行し、関連するディレクトリとファイル群を特定します。その後、調査タスクを互いに独立した 2～4 件に分割します。

2b. Explore サブエージェントを並列で起動する

1 回のメッセージで複数のエージェントを並列に起動するには、Task と subagent_type: "Explore" を使います。各エージェントには 1 つの領域を調査させ、コードを大量に貼り付けるのではなく、それぞれの役割とつながりを報告させてください。

各サブエージェントには、次の項目を含む構造化されたレポートを返すよう、対象を絞った指示を出してください。

• その要素が何をするのか（目的）と、なぜ存在するのか（システム内での役割）
• 他の要素とのつながり（インポート、呼び出し、データフロー）
• 推奨するノード ID（camelCase）と、わかりやすいラベル（例：「描画操作」。「useDrawingInteraction()」ではない）
• 主なファイルパス
• コードスニペット（必須、1～5 行）

各サブエージェントには、次のようなノードのリスト形式でレポートを作成するよう指示してください。

NODE: drawingInteraction
  label: Drawing Interaction
  file: app/features/tools/useDrawingInteraction.ts
  purpose: Converts pointer events into shape data. This is the bridge between raw mouse input and the element model.
  connects_to: canvasRenderer (feeds shape data), toolState (reads active tool)
  key_snippet:
    const element = createElement(tool, startPoint, currentPoint)
    lang: typescript

すべてのノードにコードスニペットを必ず含めてください。 重要な関数呼び出し、型定義、設定行、主要なアルゴリズムなど、最も有用な部分を 1 つ選びます（1～5 行）。これにより、概念的な説明に加えて、開発者が具体的な手がかりを得られます。

「描画ツール」のウォークスルーをサブエージェントに分割する例：

Subagent 1: "Explore user input handling"
→ Read tool selection, pointer event handling
→ Report: purpose of each piece, how they connect

Subagent 2: "Explore rendering pipeline"
→ Read canvas rendering, scene management
→ Report: what renders elements, how it gets triggered

Subagent 3: "Explore element model and state"
→ Read element types, state management
→ Report: how elements are stored, what shape they have

自分でファイルを読まないでください。 サブエージェントに調査させます。あなたの役割は、調査を指揮し、その結果をまとめて HTML に反映することです。

2c. サブエージェントの結果を統合する（これ以上ファイルを読み込まない）

すべてのサブエージェントから結果が返されたら、必要な情報はすべてそろっています。これ以上ファイルを読んだり、サブエージェントを起動したりしないでください。 そのままステップ 3〜4 に進みます。

サブエージェントの調査結果を次の項目にまとめます。

1. ノード一覧 — ID、平易な英語のラベル、主なファイル、1〜2文の説明、コードスニペット＋言語
2. エッジ一覧 — 接続するノードと、平易な動詞ラベル（「triggers」「feeds into」「produces」）
3. サブグラフのグループ分け — わかりやすいラベルを付けた2〜4グループ（「User Input」「Processing」「Output」など）

ノードは合計5〜12個にしてください（最低5個は厳守し、5個未満にしないでください）。 各ノードは関数ではなく、概念を表します。関連する関数は1つのノードにまとめてください。ノードが12個を超える場合は、関連するものを統合してください。サブエージェントの結果が5個未満の場合は、関連する概念を追加するか、広範なノードをより細かく分割して、5個以上にしてください。

サブエージェントのレポートにノードの情報が不足している場合は、自分でファイルを読まず、そのノードを除外してください。ただし、ノード数が最低5個になるようにしてください。

ステップ3：図の種類を選ぶ

トピックに応じてMermaidの図の種類を選びます。

トピック	図の種類	Mermaid構文
機能フロー、リクエストのライフサイクル、アーキテクチャ	フローチャート	graph TD / graph LR
データベーススキーマ、テーブルの関係、データモデル	ER図	erDiagram
混合（APIフロー＋DBスキーマ）	両方 — 2つの図を横並びまたは縦に配置	フローチャート＋ER

図のサイズ：2〜4個のサブグラフにグループ化した5〜12個のノードにしてください。これにより、図をひと目で把握しやすくなります。

フローチャート（graph TD / graph LR）

方向：階層的なフローにはgraph TD（上から下）、連続するパイプラインにはgraph LR（左から右）を使用します。

ノードの種類（カテゴリごとにスタイルを設定）：

種類	スタイル	用途
component	Purple-500	Vueコンポーネント、ページ
composable	Purple-600	コンポーザブル、フック
utility	Purple-700	ユーティリティ、ヘルパー、純粋関数
external	Gray-600	ライブラリ、ブラウザーAPI、外部サービス
event	Purple-200	イベント、ユーザー操作、トリガー
data	Purple-600	ストア、状態、データ構造

サブグラフ：関連するノードを、わかりやすいメンタルモデルのラベル（例：「User Input」「Core Logic」「Visual Output」）を付けた2〜4個のサブグラフにまとめます。技術的なレイヤー名は使わないでください。

ノードID：詳細データに対応する、説明的なキャメルケースのIDを使用します（例：drawingInteraction、canvasRenderer）。

Mermaidのノードラベル：関数名やファイル名ではなく、「Drawing Interaction」「Canvas Rendering」のような平易な英語のラベルを使用します。

エッジ：平易な動詞のラベル（「triggers」「feeds into」「reads」「produces」「watches」）を付けます。APIメソッド名は使わないでください。

ER図（erDiagram）

データベース関連の説明には、スキーマ設計、テーブルの関係、マイグレーション、データモデルなどにER図を使用します。

構文：

erDiagram
    USERS {
        string id PK
        string email UK
        string name
        timestamp created_at
    }
    TEAMS {
        string id PK
        string name
        string owner_id FK
    }
    TEAM_MEMBERS {
        string team_id FK
        string user_id FK
        string role
    }
    USERS ||--o{ TEAM_MEMBERS : "joins"
    TEAMS ||--o{ TEAM_MEMBERS : "has"
    USERS ||--o{ TEAMS : "owns"

リレーションシップのカーディナリティ：

構文	意味
||--o{	1対多
||--||	1対1
}o--o{	多対多
||--o|	1対0または1

カラムのマーカー：PK（主キー）、FK（外部キー）、UK（一意キー）。

ER図のクリックハンドラー：ER図のエンティティは、Mermaidのclickコールバックを標準ではサポートしていません。代わりに、レンダリング後にquerySelectorAll('.entityLabel')を使ってクリックリスナーを手動で追加してください。パターンについてはhtml-patterns.mdを参照してください。

ステップ 4：HTML ファイルを生成する

references/html-patterns.md のパターンに従って、自己完結型の HTML ファイルを 1 つ作成します。

ファイルの場所：プロジェクトのルートに walkthrough-{topic}.html として書き込みます（例：walkthrough-canvas-drawing.html）。トピックのスラッグにはケバブケースを使用します。

アーキテクチャ：HTML では <script type="module">（ネイティブ ES モジュール）を使用します。Babel は使用しません。つまり、次のとおりです。

• テンプレートリテラル（バッククォート）は問題なく使用できます。複数行の文字列には自由に使ってください。
• Shiki は ESM 経由でインポートされ、起動時にコードをハイライトします。
• React/ReactDOM は UMD グローバルとして読み込まれ、window.React / window.ReactDOM 経由でアクセスします。
• JSX は使用せず、すべてのコンポーネントのレンダリングに React.createElement() を使用します。

必須要素：

1. ウォークスルーの範囲を説明するタイトルとサブタイトル
2. TL;DR サマリー — 図の上に表示カードとしてレンダリングする 2〜3 文の要約です。新しく参加した開発者が最初にこれを読み、その後に図を確認できるようにします。
3. クリック可能なノードを含む Mermaid フローチャート（5〜12 ノード）
4. 次の内容を表示するノード詳細パネル：1〜2 文の説明、ファイルパス、コードスニペット
5. ノードの種類ごとの色分けを示す凡例

ノード詳細データ — 各ノードには、次の内容を含めます。

nodeId: {
  title: "Drawing Interaction",
  description: "Converts pointer events into shape data. This is the bridge between raw mouse input and the element model.",
  files: ["app/features/tools/useDrawingInteraction.ts"],
  code: `const element = createElement(tool, startPoint, currentPoint)`,
  lang: "typescript",
}

重要な点：

• description = 平易な文章による 1〜2 文の説明です。「これは何か？」「なぜ存在するのか？」に答えます。「内部でどのように動作するか」ではありません。
• code = 必須（1〜5 行）。最も役立つ部分を選びます（上記のステップ 2b のスニペットに関するガイダンスを参照）。
• lang = すべてのノードで必須 — 必ず明示的に設定します（例："typescript"、"javascript"、"vue"、"json"、"css"）。デフォルトでは "typescript" を使用します。lang フィールドを省略しないでください。
• files = "path" または "path:lines" 形式の文字列を含む配列です。

ファイルを書き込んだ後、ユーザーのブラウザーで開きます。

open walkthrough-{topic}.html    # macOS

Mermaid の規約

クリックのバインド

Mermaid のコールバック構文を使用して、ノードをインタラクティブにします。

click nodeId nodeClickHandler "View details"

ここで nodeClickHandler は、HTML 内で定義するグローバル JS 関数です。

サブグラフの命名

わかりやすいメンタルモデルのラベルを使用します。

subgraph user_input["User Input"]
subgraph core_logic["Core Logic"]
subgraph visual_output["Visual Output"]

エッジのラベル

一般的な動詞を使用します。

A -->|"triggers"| B
A -.->|"watches"| C
A ==>|"produces"| D

直接呼び出しには -->、リアクティブ／監視関係には -.->、イベント／発行には ==> を使用します。

品質チェックリスト

完了前に、次の点を確認します。

• 図に5〜12 個のノードがある（最低 5 個は厳守。数えて確認する）
• すべてのノードラベルが平易な英語である（関数シグネチャやファイル名は含めない）
• ノードの説明が 2 文を超えていない
• すべてのノードにコードスニペットがある（1〜5 行）。スニペットのないノードがない
• すべてのノードで lang が明示的に設定されている（例：lang: "typescript"）。例外なし
• TL;DR サマリーがあり、3 文以内である
• すべてのノードがコードベース内の実在するファイルに対応している
• コードスニペットが実際のコードであり、捏造されたものではない
• ファイルパスが正しく、プロジェクトのルートからの相対パスである
• フローチャートが実際のコードフローを正確に表している
• どのノードをクリックしても詳細パネルが表示される
• 図が Mermaid の構文エラーなしでレンダリングされる
• HTML ファイルがブラウザーで正しく開く
• サブグラフのラベルがわかりやすい（「Composable Layer」ではなく「User Input」）
• エッジのラベルが一般的な動詞である（「handlePointerDown()」ではなく「triggers」）
• <html> タグに style="color-scheme: dark" が含まれている
• フローチャートの場合：DIAGRAM 内のすべてのノードに click nodeId nodeClickHandler "View details" のバインドがある
• ER 図の場合：レンダリング後に .entityLabel のクリックハンドラーがアタッチされている（Mermaid の click 構文は ER 図では機能しない）

参考資料

• references/html-patterns.md — HTML テンプレート、CSS、JavaScript のパターン一式