D2ダイアグラム
D2ソースを書き、SVGにレンダリングし、レンダリング結果を見て、見つけた問題を修正する — これをループで繰り返し、図がデリバリー可能な状態になるまで続けます。見たことのない図は、まだ完成していない図です。
リファレンスファイル — オンデマンドで読み込む
| ファイル | 読むタイミング |
|---|---|
references/d2-language.md | 非自明なD2を書くとき — 構文、シェイプ、コンテナ、クラス、変数、そしてコンパイルは通るがレンダリングが崩れるサイレントな落とし穴 |
references/layout-engines.md | レイアウトの選択やデバッグ: TALA vs ELK vs dagre、ライセンス、シード、エンジンごとの動作の違い |
references/diagram-patterns.md | 図の種類と構造の選択 — アーキテクチャ、シーケンス、ERD、グリッド、C4;テーマ、アイコン、ダークモード、GitHubへの埋め込み |
ステップ0 — ツールチェーン確認
最初のレンダリング前にセッションごとに一度実行します(scripts/はこのスキル自身のディレクトリを指します — Claude Codeでは${CLAUDE_SKILL_DIR}がそれに解決されます):
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ 続行します。d2: MISSING→ ユーザーに伝え、その後scripts/setup.sh(フラグなし)を実行してHomebrew経由でインストールするか、印刷されたインストールコマンドを表示します。盲目的にレンダリングしないでください — このスキルの他の部分はd2なしでは機能しません。tala: not installedまたはunlicensed→ 問題ありません。ELKが自動的にフォールバックされ、良好なレイアウトを生成します。図がソフトウェアアーキテクチャ図(TALAが有意に優れている場合)で、かつユーザーが出力品質にこだわっていると思われる場合にのみ、TALAについて一度だけ言及します。しつこくしないでください。
ステップ1 — 書く前に計画する
最初に3つのことを決定します:
- メッセージ。 読者が5秒で何を結論づけるべきか? 図は何かを主張します — 「ここでリクエストが分岐する」、「このサービスがボトルネックである」、「これらの2つのパスは決して交わらない」。主張を述べられないなら、ラベル付きの箱のコレクションを描こうとしているだけです。
- 種類。 アーキテクチャ/トポロジ → プレーンなシェイプとコンテナ。時間経過に伴う相互作用 →
sequence_diagram。データモデル →sql_table。厳密な整列(マトリックス、ダッシュボード、凡例が多い) → グリッド。種類ごとの構造ガイダンスについてはreferences/diagram-patterns.mdを参照してください。 - 規模。 5~15ノードは読みやすい;15~25はコンテナによるクラスタリングが必要;約25を超えると、複数の図に分割するか
layersを使用します。壁画よりも2つ目の図を優先します。
実際のシステムの技術図には、実際の名前を使用します — ユーザーのコードベースや説明に基づいた、実際のサービス名、実際のテーブル名、実際のイベント名。コードが利用可能ならgrepします。Service A -> Service Bは読者の信頼を損ないます。
ステップ2 — D2を書く
自明でない図を書く前には、必ずreferences/d2-language.mdを読んでください。壊れた出力の90%を防ぐルール:
- キーを接続し、ラベルを接続しない。
api: API Gatewayの後、api -> dbと書き、決してAPI Gateway -> dbと書かないでください — 後者は静かに重複シェイプを作成します。 #または;を含むラベルは引用符で囲む — 引用符なしの#はラベルの途中でコメントを開始し、引用符なしの;は行を2つのシェイプに分割します。どちらもエラーなくコンパイルされます。句読点を含むラベルはすべて引用符で囲むのが安全な習慣です。- スタイルは
classes:で定義し、ノードごとのスタイルは避ける — 1つの定義をclass:で適用します。個々のノードにstyle.fillを適用しないでください。ハードコードされた塗りつぶしはテーマと競合し、ダークモードのレンダリングを壊します。 - ほとんどのアーキテクチャフローでは
direction: rightを設定する(左から右への読み取りが自然)。すべてのエンジンがルートレベルの方向を尊重します。TALAはさらにコンテナごとのdirectionをサポートします。 - ソースは、出力先の近くに
{name}.d2として保存します(デフォルト: プロジェクトの./diagrams/)。
ステップ3 — レンダリング
常にバンドルされたスクリプトを通してレンダリングします — レイアウトエンジンを選択し、透かし入り出力を防止し、最初に検証します:
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--pngはoutput.pngも書き出します — ステップ4で必要です(Readツールはラスター画像を表示しますが、SVGは表示しません)。- スクリプトは
engine:(実際にレンダリングしたもの)とfallback:(TALAが使用されなかった場合の理由)を出力します。ユーザーがエンジンについて尋ねた場合、または明示的にTALAを希望した場合にのみ、一行のメモをユーザーに伝えてください。 - 便利なフラグ:
--theme N、--dark-theme 200(SVGは読者のカラースキームに応答します)、--sketch、--pad N、--seed N(TALAの再試行)、--engine tala|elk|dagre(強制)、--allow-watermark(TALA評価用)。 - 失敗した場合、スクリプトはd2のコンパイルエラーを
file:line:col形式で出力します — その場所のソースを修正して再実行します。エラーが不明瞭な場合は、references/d2-language.mdの落とし穴セクションを確認してください。
ユーザーが明示的に承諾しない限り、透かし入りのTALA出力をデリバリー用にレンダリングしないでください。スクリプトはELKにフォールバックすることでこれを強制します。
ステップ4 — 見る、そして修正する(必須ではない)
.d2ソースは、レンダリングが実際にどのように配置されたかについては何も語りません — レイアウトはエンジンの判断であり、あなたの判断ではありません。ReadツールでPNGを開き、2つのパスで監査します:
パス1 — 主張を伝えているか?
- 目の動きがストーリーの開始点に入り、終了点で抜けるか?
- フロー方向は一貫しているか(不自然に折り返したり、下から上に読んだりしていないか)?
- コンテナのグループ分けは、計画した論理グループと一致しているか?
- 最も重要な要素が視覚的に目立っているか、それとも埋もれているか?
パス2 — レイアウトの欠陥(自動レイアウトエンジンはこれらすべてを生成します):
- エッジラベルがエッジから大きく離れたり、どのエッジを説明しているか曖昧だったりする
- エッジが並行して重なり合ったり、ノードやコンテナを横切ったり、馬鹿げた迂回をしたりする
- テキストが切り詰められたり、シェイプ/アイコンと衝突したりする
- ある領域が混雑し、別の領域が空いている;コンテナがその内容よりも大幅に大きい
- ノードが小さすぎてラベルが支配的、またはノードサイズが極端に不統一
- ユーザーに見せたときに謝って説明しなければならないようなもの
D2のレバーで修正し、ピクセル単位で調整しない(自動レイアウトでは入力値を変更し、座標は変更しません): directionを変更する;コンテナでグループ化または再グループ化する;エッジラベルを短くする(長いラベルはELKで最も流れやすい);平行エッジを1つのラベル付きエッジにマージする;nearを使って凡例/タイトルをフロー外に移動する;過負荷な図をlayersに分割する;--padを調整する;TALAでは--seed Nで再試行する(2~3のシードを試す — レイアウトは大きく異なります);最後の手段として、この図の形状に合わせてエンジンを切り替える(references/layout-engines.md参照)。
再レンダリング、再確認、繰り返し。2~4のレンダリングサイクルを見積もってください — 最初のレンダリングが両方のパスをクリアすることは稀です。完了とは: 両方のパスがクリーンで、画像内に謝罪や説明を必要とするものがない状態です。
ステップ5 — デリバリー
- 最終的な
.svg(および.d2ソース)のパスを確認します — 常にユーザーに両方を提供します;.d2は編集可能なアーティファクトです。 - 図がGitHubのREADMEやドキュメントサイトに置かれる場合は、ダークモード対応のバリアントを提供します:
--dark-theme 200で再レンダリングします(読者のカラースキームに従う単一のSVG)。PNG/<picture>埋め込みのパターンはreferences/diagram-patterns.mdにあります。 - ユーザーが自分で図を反復的に改善する場合は、ブラウザでのライブプレビュー用に
d2 --watch input.d2を紹介します。
トラブルシューティング
| 症状 | 原因 / 修正 |
|---|---|
d2: command not found | scripts/setup.shを実行します(ガイド付きインストール) |
D2_LAYOUT "tala" is not bundled | TALAがPATHにありません — スクリプトが自動的にELKにフォールバックします;ユーザーが希望する場合のみTALAをインストールします |
出力にUNLICENSEDテキストがある | ライセンスなしのTALA — レンダリングスクリプトが自動的にELKで再レンダリングします;ライセンスキーはTSTRUCT_TOKENまたは~/.config/tstruct/auth.jsonに設定します |
| PNGエクスポートに失敗し、SVGは正常 | 最初のPNGレンダリングはヘッドレスブラウザをダウンロードします;一度再試行します。ブロックされた場合(オフライン/CI)、SVGをデリバリーし、利用可能なSVGラスタライザで変換して検査します |
--layout talaでのコンパイルエラーがELKでは正常にレンダリングされる | d2/TALAのバージョンのずれ — スクリプトが自動的にフォールバックします;両方のアップデートを提案します |
| 出力からアイコンが欠落している | アイコンのURLが403/404を返しました — アイコンを削除するか、icons.terrastruct.comから別のアイコンを選びます;アイコンは早めにテストします |