architecture-diagram

アーキテクチャ図

コードベースのコンポーネント間の高レベルな関係を示す Mermaid のフローチャートを生成します。

使用する場面

• プラグインやモジュールの相互関係を可視化する
• システム構造を理解するためのオンボーディング
• PR レビュー用のアーキテクチャを文書化する
• 「このシステムはどのように連携しているのか？」に答える

使用しない場面

• インポートレベルの結合関係（cartograph:dependency-graph を使用）
• 実行時の呼び出し経路（cartograph:call-chain を使用）

ワークフロー

ステップ 1：コードベースを調査する

コードベースエクスプローラーエージェントに、対象範囲を分析するよう指示します。

Agent(cartograph:codebase-explorer)
Prompt: Explore [scope] and return a structural model.
Focus on packages, modules, and their relationships
for an architecture diagram.

対象範囲が指定されていない場合は、プロジェクトのルートを使用します。

ステップ 2：Mermaid 構文を生成する

構造モデルを Mermaid のフローチャートに変換します。

アーキテクチャ図のルール：

• 階層型システムには flowchart TD（上から下）を使用します
• パイプライン／フロー型システムには flowchart LR（左から右）を使用します
• 関連するモジュールは、パッケージごとにサブグラフでグループ化します
• 関係性を表す、説明的なエッジラベルを使用します
• ノード数は最大 15～20 個に制限します（小さなモジュールはまとめます）
• コンポーネントの種類を区別するために図形を使います：
  • モジュール／パッケージには [Rectangle]
  • エントリーポイント／コマンドには ([Stadium])
  • データストアには [(Database)]
  • 判断ポイントには {Diamond}

出力例：

flowchart TD
    subgraph sanctum[Sanctum Plugin]
        commit[Commit Messages]
        pr[PR Preparation]
        workspace[Workspace Review]
    end

    subgraph leyline[Leyline Plugin]
        git[Git Platform]
        patterns[Error Patterns]
    end

    commit --> git
    pr --> workspace
    pr --> git
    workspace --> patterns

ステップ 3：MCP 経由でレンダリングする

Mermaid Chart MCP を呼び出してレンダリングします。

mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram
  prompt: "Architecture diagram of [scope]"
  mermaidCode: [generated syntax]
  diagramType: "flowchart"
  clientName: "claude-code"

レンダリングに失敗した場合は、エラーメッセージに基づいて Mermaid 構文を修正し、再試行します（再試行は最大 2 回）。

ステップ 4：結果を提示する

レンダリングした図を、何を示しているかの簡単な説明（2～3 文）とともにユーザーに提示します。

終了条件

• 関連するモジュールをグループ化する subgraph ブロックを少なくとも 1 つ含む Mermaid の flowchart 構文が生成されている
• mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram が呼び出され、エラーなく完了している（または初回の失敗後に再試行し、その結果が報告されている）
• 図のノード数が 3～20 個である（スキルのルールに準拠）
• 図が何を示しているかを説明する 2～3 文が、レンダリング結果とともに表示されている
• MCP によるレンダリングが 2 回の再試行後も失敗した場合、エラーを明示したうえで Mermaid 構文がコードブロックとして提示されている