ブループリント アーキテクチャ図
エンジニアリングシートのように描かれたシステム：グリッド入りのブループリント（または明るい「ホワイトプリント」）、すべてのコンポーネントは種類ごとにラベル付きの形状で表示、リクエストは矢印、イベントは破線矢印、グループは破線のゾーン、凡例とタイトルブロックが付きます。あなた（またはユーザー）がシステムを diagram.json として記述すると、スクリプトが dagre（バンドル済み、インストール不要）でレイアウトし、以下を描画します：
out/index.html：すべての接続に沿ってドットが移動し、イベント線が流れる図。ディスクから開けばウィンドウに合わせて拡大縮小します。out/diagram.svg：動きのない同じ図。ドキュメント、Wiki、スライド向け。out/diagram.png：2倍サイズの静止画。ヘッドレスChromeから生成し、画像が必要なあらゆる場所に使えます。
必要なもの
- Node.js 18 以上。ビルドには他に何も必要ありません。
- PNG出力用のChrome、Chromium、またはEdge。スクリプトは通常の場所で自動検出します。見つからない場合は
CHROME_PATHを設定してください。 - 図を開いたりエクスポートする際のインターネット接続（Google FontsからJetBrains Monoフォントを取得するため。取得できない場合はシステムの等幅フォントにフォールバックします）。
このスキルのフォルダは <skill> です。つまり、このSKILL.mdがあるフォルダです。
手順
1. システムを特定する
ユーザーがシステムを説明した場合は、その言葉を使ってください。リポジトリを読むように依頼された場合は、何かを描く前に証拠を収集し、見つけたものだけを描いてください：
- デプロイ可能なもの：
docker-compose*.ymlのサービス、KubernetesのDeployment、Helmチャート、Procfile、サーバーレス設定（serverless.yml、vercel.json、wrangler.toml）、Terraformリソース、およびmonorepo内のアプリ（apps/、services/、packages/*で起動スクリプトがあるもの）。 - データストアとブローカー：イメージおよびマネージドリソース（postgres、mysql、mongo、redis、kafka、rabbitmq、sqs、s3）、および
DATABASE_URL、REDIS_URL、KAFKA_BROKERS、バケット名などの接続設定。 - 接続：他のサービスを指すHTTPクライアントとベースURL、gRPCスタブ、キュー producer/consumer（トピック名とキュー名）、
depends_on、サードパーティ（Stripe、LLM API、メールプロバイダ）への外部呼び出し。 - 呼び出し元：Webアプリ、モバイルアプリ、CLI、cronジョブ、webhook。
ノードは5〜20個に保ってください。レプリカや小さなヘルパーは所属するサービスに統合し、詰め込みすぎず複数のシート（"sheet": "02 / 03"）に分割してください。推測したものは必ず明記し、そのことをユーザーに伝えてください。
2. diagram.json を書く
{
"title": "Order service · v2",
"subtitle": "System architecture · from /services and docker-compose.yml · 21 Oct 2026",
"sheet": "01 / 01",
"direction": "LR",
"theme": "blueprint",
"groups": [{ "id": "core", "label": "Order platform" }],
"nodes": [
{
"id": "gateway",
"label": "API gateway",
"sub": "auth · rate limit",
"kind": "service"
},
{
"id": "orders",
"label": "Order service",
"sub": "v2 · Go · 6 pods",
"kind": "service",
"group": "core",
"focus": true
},
{
"id": "db",
"label": "Postgres",
"sub": "orders · stock",
"kind": "database"
},
{
"id": "bus",
"label": "Event bus",
"sub": "Kafka · 3 topics",
"kind": "queue"
}
],
"edges": [
{ "from": "gateway", "to": "orders", "label": "POST /orders" },
{ "from": "orders", "to": "db", "label": "SQL" },
{ "from": "orders", "to": "bus", "label": "order.created", "async": true }
]
}
| フィールド | 説明 | 制限 |
|---|---|---|
title | システムまたはビューの名前（必須）。タイトルブロックにも入ります。 | 60 |
subtitle | 図が示す内容と出典、日付 | 100 |
sheet | タイトルブロック内のシート番号（例："02 / 03"、デフォルトは 01 / 01） | – |
direction | LR 左から右（デフォルト、リクエストフローに適する）または TB 上から下（パイプライン） | – |
theme | blueprint（ダークブルー、デフォルト）、whiteprint（明るい）、または色指定：{ "paper", "line", "accent", "dim" } を16進数で | – |
groups | ノードを囲むゾーン：{ "id", "label" } | – |
nodes[].id | 英字、数字、-、_。エッジがこれを参照します（必須） | – |
nodes[].label | ノード上の名前（必須） | 28 |
nodes[].sub | 2行目：言語、ランタイム、規模、保持するデータなど | 36 |
nodes[].kind | 形状：service（デフォルト）、client、database、queue、cache、storage、function、external（サードパーティ、破線） | – |
nodes[].group | グループID | – |
nodes[].focus | true にするとアクセントカラーで描画：図の中心となるもの | – |
edges[] | { "from", "to" } ノードID、データや制御の流れる方向に | – |
edges[].label | プロトコル、エンドポイント、トピック、動詞：HTTPS、POST /orders、order.created | 24 |
edges[].async | true にするとイベント、キュー、fire-and-forget（破線、流れる） | – |
ヒント：
- エッジのラベルには実際にやり取りされるもの（エンドポイント、トピック、テーブル、動詞）を付けましょう。何も付加価値がない場合だけラベルを省略してください。
- エッジはリクエストの向き（呼び出し元→呼び出し先）とイベントの向き（producer→queue→consumer）に合わせてください。
focusは最大1ノードにしてください。- 最大40ノードまで許可されていますが、約20を超えると図が読みにくくなります。
3. ビルドして確認する
node <skill>/scripts/build.mjs diagram.json out
ファイルをチェックし、すべての問題を一度にリストアップします（存在しないノードへのエッジ、制限超過のラベルなど）。その後、out/index.html と out/diagram.svg を書き出します。out/index.html を開いて以下を確認してください：
- 手順1のすべてのノードが含まれていること、見つけなかったものが入っていないこと
- エッジが正しい向きで、ラベルが読めること
- グループに正しいノードが含まれていること
レイアウトが絡まっている場合は、別の direction を試すか、nodes と edges の順序を変更してください。レイアウトはその順序に従います。
4. PNGをエクスポートする
node <skill>/scripts/export-png.mjs out/index.html
描画サイズの2倍で out/diagram.png を書き出します。実際のサイズにするには --scale=1 を追加してください。
5. 成果物を渡す
ユーザーに out/index.html（アニメーション版）、out/diagram.svg、out/diagram.png、そして diagram.json を渡します。これにより、システム変更時に図を更新できます。JSONを編集して手順3と4を再度実行するだけです。図をリポジトリに含める場合は、docs/architecture/ フォルダにJSONとSVGを置くのが良いでしょう。SVGはGitHubやほとんどのWikiでレンダリングされます。
トラブルシューティング
build: fix diagram.json first：各行がノードまたはエッジと変更すべき内容を示しています。- PNGの手順でChromeが見つからないと言われる：
CHROME_PATHを設定するか、out/index.htmlを開いてスクリーンショットを撮ってください。 - テキストが異なる等幅フォントで表示される：ページがGoogle Fontsにアクセスできませんでした。JetBrains Mono（無料）をインストールしてオフラインでも同じフォントにしてください。
- エッジが頻繁に交差する：
directionを切り替えるか、交差しているノードをnodesの中で前後に移動するか、システムを2つのシートに分割してください。
ファイル
scripts/build.mjs：diagram.jsonをチェックし、レイアウトしてHTMLとSVGを描画します。依存関係のインストールは不要です。scripts/export-png.mjs：ヘッドレスChromeでPNGを保存します。vendor/dagre.esm.js：dagreグラフレイアウトライブラリ（MITライセンス）。バンドル済みでインストール不要。ライセンスはvendor/LICENSE-dagre.txtにあります。examples/order-service/（ブループリント、左から右）およびexamples/rag-pipeline/（ホワイトプリント、上から下）：完成したdiagram.jsonファイル。Lookbk上のプレビューはこれらから描画されています。NOTICE.md：このスキルが使用するサードパーティソフトウェアとフォント。