c4-diagramming

C4 ダイアグラム作成

構造アーキテクチャを可視化するための C4 モデルです。アーティファクトのピラミッドに対応する 4 つのズームレベルでダイアグラムを生成します。

C4 とピラミッドの対応

C4 レベル	ピラミッドレイヤー	パス
レベル 1：システムコンテキスト	L1（概要）	01-summary/system-context.md
レベル 2：コンテナー	L2（分析）	02-analysis/structural-views/container.md
レベル 3：コンポーネント	L2（分析）	02-analysis/structural-views/components.md
レベル 4：コード	L3（詳細資料）	03-dossiers/code-level-detail.md

C4 は構造を表現するうえで最も自然に適合します。4 段階の階層は、ほとんど変換することなく 3 つのピラミッドレイヤーに対応し、レベル 2 と 3 はそれぞれ別個の L2 分析ファイルに対応します。

コミュニケーションの確認

記法を選んだりレイアウトを整えたりする前に、対象読者と、読者が完了すべき作業を明確にしてください。その作業に答える C4 レベルを 1 つ選びます。キャンバスを埋めるためだけに、システムコンテキスト、コンテナー、コンポーネント、コードの主張を混在させないでください。1 つのビューでは、抽象化レベル、要素の語彙、境界の扱い、関係の意味を一貫させてください。構造的に妥当な C4 モデルであっても、読者に目的を推測させる、レベルを混在させる、重要な経路を隠す、あるいは対象読者を圧倒するといった場合は、コミュニケーションの成果物として適切でないことがあります。

実際の対象読者向けにダイアグラムを作成、修正、レビューする際は、references/technical-diagram-communication.md を読み込んでください。そのレビュー記録を使って、説明の流れ／読み順、視覚的な階層、ラベルと凡例、情報のノイズ比、色に依存しない意味、アクセシビリティへの引き継ぎ、不確実性、レビューの証拠を確認してください。アクセシビリティの完全な適合性は引き続き web-accessibility が担い、アーキテクチャ上の決定は引き続き software-architecture が担います。

レビューの証拠

対象読者と問い、C4 のレベルと範囲、主要な主張、既知の不確実性、対象レンダラー、アクセシブルなテキストまたは表形式の代替情報を記録してください。ソースモデルとレンダリング後の成果物の両方をレビューします。構文／モデルバリデーターに合格して証明されるのは構造的な妥当性のみです。そのダイアグラムが意図した主張を伝えていることまでは証明されません。

作成形式

Mermaid（簡易ダイアグラムの既定）

Markdown に埋め込む単一のダイアグラムが必要な場合に使用します。C4 と Mermaid の互換性に関する注意事項は、以下の GitHub のレンダリング制約セクションを参照してください。

Structurizr DSL（長期運用プロジェクトに推奨）

Structurizr DSL は、Simon Brown が作成した C4 モデルのリファレンス実装であり、「モデルをコードとして扱う」方式を採用しています。アーキテクチャモデル全体を 1 つの DSL ファイルで定義し、すべての C4 レベルをそこから生成します。これにより、手書きの Mermaid では保証できない、ダイアグラム間の構造的一貫性を確保できます。

workspace {
    model {
        user = person "Customer"
        system = softwareSystem "Your System" {
            webapp = container "Web Application" "TypeScript, React"
            api = container "API" "Go"
            db = container "Database" "PostgreSQL"
            user -> webapp "Uses"
            webapp -> api "Makes API calls"
            api -> db "Reads/writes"
        }
    }
    views {
        systemContext system { include * autolayout lr }
        container system { include * autolayout lr }
        component api { include * autolayout lr }
        theme default
    }
}

主な機能：

• !adrs docs/adr — Architecture Decision Records（adr-tools、MADR、log4brains）をワークスペースにインポートし、C4 ダイアグラムと並べてレンダリングします
• !docs docs/arc42 — arc42 のドキュメントを Markdown／AsciiDoc としてインポートします
• Structurizr Lite（Docker）— http://localhost:8081 でローカルプレビューできます
• CI コマンド：validate、inspect、export（PlantUML、Mermaid、静的サイト）

ツールの比較、DSL のレシピ集、C4-PlantUML の代替手段、統一されたリポジトリ規約については、references/architecture-as-code-ecosystem.md の完全なリファレンスを参照してください。

内容

• references/c4-to-pyramid-mapping.md — コンテキスト→L1、コンテナー／コンポーネント→L2、コード→L3（Mermaid + Structurizr DSL のパス）
• c4-to-flowchart.md — GitHub 互換のフローチャートに変換するための Mermaid パターン集
• references/architecture-as-code-ecosystem.md — Structurizr DSL、C4-PlantUML、docToolChain、統一されたリポジトリ規約、ツール比較表
• references/ci-pipeline-templates.md — Structurizr の検証、エクスポート、デプロイ向けの GitHub Actions、GitLab CI、ForgeJo（Gitea Actions、Woodpecker）パイプラインテンプレート

GitHub のレンダリング上の制約

GitHub の組み込み Mermaid レンダラーには、C4 プラグイン（@mermaid-js/mermaid）がバンドルされていません。C4Context、C4Container、または C4Component 構文を使用する ````mermaid` ブロックは、GitHub 上では図ではなく生のコードとしてレンダリングされます。これは、Issue、PR の説明、ディスカッションのコメント、Markdown ファイルに影響します。

回避策： GitHub の Markdown に埋め込む前に、C4 図を標準の flowchart 構文に変換してください。

• Person() → ラベル付きの [rect] ノード
• System() / System_Ext() → サブグラフの内側または外側にある [rect]
• Container() → 技術スタックのラベル付きの [rect]
• Db() → [(cylinder shape)]
• System_Boundary{} / Container_Boundary{} → subgraph ... end
• Rel() → -- label --> または -.->
• UpdateLayoutConfig() は削除し、代わりに flowchart LR または TB ディレクティブを使用

変換表の全容と具体例については、利用可能な場合、付属の mermaid-diagrams スキルから c4-to-flowchart.md を読み込んでください。

DIAGRAMS/ ディレクトリ内の .mmd ファイルも、mmdc または GitHub 上でレンダリングする必要がある場合は、標準のフローチャート構文を使用してください。C4 プラグイン構文を使用したファイルをレンダリングできるのは、そのプラグインがバンドルされたツール（例：Mermaid Live Editor、C4 拡張設定を使用した mmdc）だけです。C4 構文の .mmd ファイルをリポジトリにコミットすると、GitHub のファイルプレビューでは生のテキストとして表示されます。標準構文に変換するか、先に PNG にレンダリングしてください。

提出済みの機能リクエスト

C4 Mermaid プラグインのバンドルを求める GitHub Community の機能リクエストが https://github.com/orgs/community/discussions/197898 に提出されました（クローズ済み — Apps, API and Webhooks のディスカッションテンプレートを使用して、Web UI から提出する必要があります）。これが実装されれば、GitHub でのレンダリングに以下のフローチャート変換は不要になります。

公式リファレンス

• Simon Brown、「The C4 Model」 — https://c4model.com/
• GroktoPlan C4 Diagrams（具体例） — https://github.com/groktopus/groktoplan/blob/main/TECHNICAL_ARCHITECTURE.md

移植性

このスキルは、特定のホストに依存しないよう意図的に設計されています。ここに記載されたリファレンス、テンプレート、スクリプトの読み込みには、エージェントの通常の仕組みを使用してください。特定のプロファイルシステム、タスクオーケストレーター、メモリサービス、または応答引き継ぎ形式を前提としないでください。

使用しない場合

• C4 レベルやモデルの判断を必要としない Mermaid の文法、レンダラーとの互換性、レイアウト、エクスポートのトラブルシューティングには mermaid-diagrams を使用してください。
• アーキテクチャ上の推進要因、トレードオフ、決定、適合性のエビデンスには software-architecture を使用してください。このスキルは、それらの決定を視覚化するものであり、決定自体を担うものではありません。
• WCAG/ARIA への完全な準拠作業や支援技術に関するエビデンスには web-accessibility を使用してください。このスキルでは、図に特化したアクセシビリティチェックと代替手段を提供します。