pma-d2

D2 図の作成

慣用的な .d2 ソースファイルを生成します。図を宣言的なテキストで記述し、公式の d2 CLI で SVG／PNG／PDF／GIF にレンダリングします。出力は人間が読みやすく、差分を確認でき、D2 を埋め込める場所（GitHub、Notion、VS Code、ドキュメントサイト、Oxide の play.d2lang.com）に埋め込めます。

このエントリーファイルは小さく保ちます。現在の図に合うリファレンスパックのみを読み込みます。

常時適用されるルール

1. 出力は .d2 テキストのみです。 このスキルはレンダラーを呼び出しません。ユーザーが d2 input.d2 out.svg を実行するか、play.d2lang.com を開きます。ソースを読んで品質を確認できるようにしてください。
2. 巧妙な D2 より慣用的な D2 を優先します。 名前が自然に読める場合は、ID とラベルの組み合わせより宣言的なノード名（api -> db）を優先します。自然な名前が不自然になる場合や重複する場合にのみ、label: を使います。
3. 概念に合ったシェイプを使います。 データベースには shape: cylinder、キューには shape: queue、アクターには shape: person を指定します。すべてを rectangle にするのは避けてください。全カタログは references/shapes.md にあります。
4. 方向は最初に宣言します。 ルート（必要であれば各コンテナー）に direction: down | right | up | left を設定します。レイアウトの方向はコミュニケーション上の選択であり、偶然のデフォルトではありません。
5. 装飾ではなく、意味を伝えるエッジスタイルを使います。 非同期／弱い依存関係には stroke-dash、ストリームには animated: true、重要度／障害経路の表現には stroke の色を使います。カタログは references/connections.md にあります。
6. 近さではなく、コンテナーでグループ化します。 ノードが同じドメイン（サブシステム、クラウド、境界づけられたコンテキスト）に属する場合は、コンテナーマップにネストします。コンテナーは D2 標準のグループ化機能です。手動配置の代わりに使ってください。
7. 図ひとつにつき概念ひとつにします。 図がふたつの質問に答える場合は、layers: またはふたつのファイルに分割します。詰め込みすぎないでください。
8. 繰り返しにはクラスを使います。 2 つ以上のノードでスタイルを共有する場合は、classes: {} でクラスを定義し、.class: name またはグロブで適用します。
9. シェイプを独自に作らないでください。 shape: の値はすべて references/shapes.md にあるものを使います。D2 はタイプミスがあると暗黙に rectangle にフォールバックします。これは最悪の失敗です。見た目は正しくても、実際には正しくありません。
10. コミットできる状態のソースにします。 ファイル末尾に改行を入れ、インデントは 2 スペースにし、行末の空白をなくします。コメントでは実装方法ではなく意図を説明します。D2 は Git と相性がよいため、その特性を保ってください。

基本的なワークフロー

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

種類	D2 のプリミティブ	使用する場面
アーキテクチャ／フロー	デフォルト（ノード＋コネクション）	システム、パイプライン、依存関係グラフ
シーケンス	shape: sequence_diagram	プロトコルのやり取り、API 呼び出しフロー、タイミング
ERD／スキーマ	テーブルごとに shape: sql_table	データモデル、外部キー
UML クラス	クラスごとに shape: class	オブジェクト指向設計、型の関係
グリッド／マトリックス	grid-rows／grid-columns	表形式のレイアウト、比較マトリックス、k8s クラスタービュー
マルチボード	layers:／scenarios:／steps:	変更前後、詳細への掘り下げ、アニメーション

各種類の詳細は references/special-diagrams.md と references/composition.md にあります。

ステップ 2：レイアウトエンジンを選ぶ

• dagre（デフォルト、無料、同梱）：DAG 向け。ほとんどのアーキテクチャ図に適しています。
• elk（無料、v0.7 以降同梱）：ネストされた階層や直交ルーティングをすっきり表現できます。複数のコンテナーを含む図で試す価値があります。
• tala（有料、別個のバイナリ）：複雑で密度の高い図に最適です。インストールが必要な場合は、ユーザーに必要なものがわかるよう、ファイルヘッダーに記載します。

ファイルごとに vars.d2-config.layout-engine で一度だけ選択します。手動の位置指定でエンジンに無理をさせないでください。D2 に x,y はありません。

ステップ 3：構造を下書きする

1. まずトップレベルのコンテナーを検討し、存在するシステム／ドメインを決めます。
2. 適切な shape: を指定して、各コンテナー内にノードを追加します。
3. コネクションを追加します。まず方向を決め、トポロジーが適切になってからラベルを付けます。
4. classes: を適用して繰り返しをまとめます。
5. ファイルの先頭に vars.d2-config ブロック（テーマ、レイアウトエンジン）を追加します。

ステップ 4：スタイルの確認

• すべての接続を確認します。スタイル（実線／破線／アニメーション／色）は、隣接する接続と意味的に区別されていますか？
• すべてのノードを確認します。shape: とクラスには情報が含まれていますか？
• 意味を伝えない装飾（装飾的な色、過剰な影）を取り除きます。

ステップ 5：検証と引き渡し

references/validation.md の事前チェックを実行します。ユーザーには以下を伝えます。

• 出力パス（デフォルトは docs/architecture/<name>.d2）。
• レンダリングコマンド：d2 <name>.d2 <name>.svg（または必要な出力先）。
• 選択したレイアウトエンジンと、別途インストールが必要かどうか。
• URL で参照しているアイコン（必要に応じて社内にコピーできるように）。

大規模な図のセクションごとの作成

1. vars と direction のヘッダー、およびコンテナーを 1 つ記述します。
2. 編集ごとにコンテナーを 1 つ追加します。子 ID が重複する場合は、コンテナー名を先頭に付けます。
3. コンテナーをまたぐエッジではドット付きパス（aws.api -> gcp.auth）を使います。エッジを出力する前にパスの存在を確認します。
4. 図が約 60 ノードを超えたら、layers: または @file インポートで構成する別々の .d2 ファイルに分割します（references/composition.md）。

出力

• ファイル：デフォルトでは docs/architecture/<name>.d2、またはユーザーが指定したパス。
• レンダリング（ユーザーが実行）：
  • d2 name.d2 → name.svg（デフォルト）
  • d2 name.d2 name.png / name.pdf / name.gif
  • d2 --watch name.d2 → localhost でライブプレビュー
  • d2 --theme <id> --dark-theme <id> name.d2 → テーマの組み合わせ
• ウェブプレビュー：https://play.d2lang.com/ に貼り付けると、D2 をインストールせずにすぐレンダリングできます。
• 埋め込み：MDX、GitHub README（リポジトリに SVG を含める）、ドキュメントサイト（ビルド時にライブレンダリング）、CI パイプラインについては references/integration.md を参照してください。

リファレンスパック

• references/syntax.md 基本文法：識別子、ラベル、マップ、コメント、エスケープ、D2 に多数ある省略記法のルール。
• references/shapes.md すべての組み込みシェイプの図による説明、データの意味、「使用する場面」のガイダンス。
• references/connections.md エッジ演算子（->、<-、<->、--）、連結、矢印の先端、ラベル、意味を伝えるスタイルのパターン。
• references/containers.md ネスト、_ による親参照、ドット付きパス、コンテナーとシェイプの違い、フラット化する場合とネストする場合。
• references/classes.md classes: ブロック、.class: による適用、複数クラスの配列、glob ベースの一括適用。
• references/styles.md スタイルキーの完全なカタログ（fill、stroke、stroke-dash、shadow、3d、multiple、animated、fill-pattern、border-radius、font-size、bold／italic／underline、opacity）。
• references/layouts.md 方向、グリッドレイアウト、dagre と elk と tala のトレードオフ、タイトルや凡例の near: 配置。
• references/special-diagrams.md シーケンス図（アクター、スパン、注釈、グループ）、ERD の sql_table、UML の class、Markdown／コード／LaTeX ブロック。
• references/composition.md layers:（独立したボード）、scenarios:（継承と上書き）、steps:（アニメーション）、@file インポート、...@file による展開。
• references/vars.md vars: ブロック、${var} による置換、d2-config（theme-id、dark-theme-id、sketch、pad、center、layout-engine）、デザイントークン用のネストされた vars。
• references/templates.md コピーして使えるスターターファイル：3 層ウェブアプリ、マイクロサービス、データパイプライン、CI/CD、シーケンス（OAuth）、ERD、k8s クラスター（グリッド）。
• references/design.md コンセプトからパターンへのマッピング、同型性テスト、D2 が ReactFlow／Mermaid／Excalidraw より適している場合と、適していない場合。
• references/validation.md 事前チェックの手順とチェックリスト、よくある D2 のミス（シェイプが警告なくフォールバックする、コンテナパスの不足、ラベルとコメントの衝突）。
• references/render.md CLI フラグ、ウォッチモード、プレイグラウンド、アイコンカタログ（terrastruct icons、svgrepo）、テーマギャラリー。
• references/integration.md MDX／Docusaurus／Nextra への埋め込み、リポジトリに含めた SVG を使った GitHub README への埋め込み、ドキュメントサイトのビルドパイプライン、コミット前のレンダリング。

クイックルーティング

• D2 構文に慣れていない場合：syntax.md + shapes.md + connections.md を読み込みます。
• アーキテクチャ／システム図：shapes.md + containers.md + layouts.md + templates.md。
• シーケンス図／SQL／UML：special-diagrams.md + templates.md。
• スタイルの調整：classes.md + styles.md。
• 複数ボードのストーリー（変更前／変更後、ドリルダウン、アニメーション）：composition.md。
• テーマ設定／構成：vars.md + render.md。
• 提出前：validation.md。
• レンダリングや埋め込み方法をユーザーに説明する場合：render.md + integration.md。

ワークフロー制御に /pma も使用するプロジェクトでは、まず /pma を読み込み、図が必要な場合にのみ /pma-d2 を読み込みます。カスタムの React ノードコンポーネントを使った、ブラウザー内で操作できる図が必要なプロジェクトでは、代わりに /pma-draw を使用してください。D2 は静的画像をレンダリングします。