architecture-diagram

アーキテクチャ図ジェネレーター

完全に編集可能なスタンドアロンの .svg ファイルを生成します。実際のベクターアイコン（AWS／Azure／GCP の公式アーキテクチャアイコン、またはそれ以外のすべてに使える手描きの汎用アイコンセット）、決定論的なゾーン対応レイアウト、直交接続ルーティング、実際の <text> ラベルを備えています。deliver --emit drawio を指定すると、自己完結型で編集可能な .drawio mxGraph ファイルも生成されます。SVG 出力にはラスター画像も <use> による複製も使われません。draw.io 出力では、ローカルのベクターアイコンデータを持つ個別に編集可能なセルを使用し、リモート画像、外部 URL、プロバイダーのステンシルに依存しません。

使用する場面

状況	このスキルを使いますか？
「AWS／Azure／GCP のアーキテクチャを描いて」	はい
「ドキュメント用のシステムトポロジー図」	はい
「後でこの図を Figma で編集したい」	はい — ラスター出力の代替手段との大きな違いです
マルチクラウドまたはハイブリッド（クラウド＋オンプレミス）図	はい — ノードごとに provider: を自由に組み合わせられます
インタラクティブ、クリック操作、またはアニメーション付きの図	いいえ — static-web-artifacts-builder を使ってください
手描き風／ホワイトボード風のスケッチ	いいえ — tldraw を使ってください
データチャート、プロット、またはダッシュボード	いいえ — chart-clarity を使ってください
既存のアーキテクチャのレビューまたは批評	いいえ — architecture-reviewer を使ってください
コンポーネントや接続のない、単一フレームのコンセプトイラスト	いいえ — concept-to-image を使ってください

前提条件

チェックアウト内のこのスキルのディレクトリ（skills/architecture-diagram）から、次のコマンドを実行してください。

• pyyaml がインストールされた python3（利用できない場合は uv run --with pyyaml python3 -m engine ... を使ってください）。

• クラウドプロバイダーのアイコンを使うには、マシンごとに一度ネットワーク経由で取得する必要があります。 アイコンはこのスキルにバンドルされていません。各プロバイダーは図での使用条件を公開しているため、architecture-diagram はアイコン素材を再配布するのではなく、ソースと利用条件をローカルキャッシュに記録します。図で特定のプロバイダーのアイコンを初めて使うときは、次を実行してください。

  python3 -m engine.fetch_icons --provider aws    # ~5s, 1037 icons
  python3 -m engine.fetch_icons --provider gcp    # ~5s, 297 icons
  python3 -m engine.fetch_icons --provider azure  # ~60s, 704 icons
  # or: --provider all
  

  これにより、特定の jgraph/drawio コミットに固定されたローカルキャッシュが作成されます（デフォルトは ~/.cache/armory/cloud-icons、--cache-dir または $XDG_CACHE_HOME で変更できます）。出力は再現可能です。レンダリングされた各クラウドアイコンは、マニフェストの SHA-256 ダイジェストと照合して検証されます。icon/digest-mismatch が発生した場合は安全のため処理が失敗し、python3 -m engine.fetch_icons --provider <provider> --force でプロバイダーのキャッシュを再構築する必要があります。以降のレンダリングでは検証済みのキャッシュを再利用するため、プロバイダーごとの初回取得後にネットワークは不要です。provider: generic の場合は取得が不要で、references/icons-generic.md にあるバンドル済みの手描きアイコンセットを使用します。

ワークフロー

1. ユーザーのリクエストを解析します：コンポーネント（説明を含む）、包含階層（ゾーン — VPC／リージョン／リソースグループ／サブネット）、接続（指定されている場合は意味タイプ）、クラウドプロバイダー。
2. サービスをアイコンに対応付けます。 各クラウドコンポーネントについて、プロバイダーに合った references/services-aws.yaml、references/services-azure.yaml、または references/services-gcp.yaml を読み込みます。クラウド以外の場合は references/icons-generic.md を読み込み、そのノードの service フィールドに使用する正確なスラッグを確認します。該当するプロバイダーのアイコンセットにサービスのアイコンが本当にない場合（各表にプロバイダーごとの記載があります）は、最も近いカテゴリを選ぶか、service を未設定のままにします。レンダラーは誤ったアイコンではなく、ラベル付きのプレースホルダーにフォールバックします。
3. 使用する各プロバイダーのアイコンキャッシュが温まっていることを確認します（「前提条件」を参照）。provider: generic の場合はこの手順をスキップします。
4. 仕様を作成します — references/spec-format.md に従った小さな YAML ファイルを用意します：title、direction（LR／TB）、zones（ネストする場合は parent を指定）、nodes（id、label、service、zone、color）、edges（id、from、to、label、type）。
5. 成果物を書き込まずに検証します：

   python3 -m engine validate spec.yaml --quality showcase --json
   

   レシートには、仕様と候補成果物の正確な SHA-256 ダイジェスト、検証件数、品質プロファイル、構成ステータス、コード化された診断情報が含まれます。validate は出力パスに一切触れません。 sources が宣言されている場合は、--verify-sources を追加します。仕様のチェックアウトから取得したローカル Git コミット、blob、両端を含む行範囲に対して、フェイルクローズ方式で検証します。origin リモートが必要ですが、ソースの内容をコピーしたり、リモートサービスに接続したりすることはありません。 エージェントがレビュー用に出力されたノードの正確なボックス、ゾーンの所属とボックス、経路設定されたエッジのウェイポイント、エッジラベルの矩形を必要とする場合は、--json の代わりに --layout-json を使用します。このオプションでも SVG 出力は書き込みません。
6. クリーンな候補のみを納品します：

   python3 -m engine deliver spec.yaml -o diagram.svg --quality showcase --emit drawio --json
   

   deliver は正確な仕様と候補 SVG をターゲットの隣にステージングし、すべてのチェックが通った場合に限り、要求されたすべての出力をアトミックに置き換えます。--emit drawio を指定すると diagram.drawio も納品されます。JSON レシートのトップレベルにある artifacts リストには、確定した各ファイルのパス、SHA-256、バイト数が記録されます。--verify-sources を指定すると、diagram.svg、diagram.drawio、diagram.sources.json をアトミックに納品します。SVG と draw.io の出力にはローカルの VERIFIED SRC n バッジが付き、サイドカーファイルは検証済みの参照を納品済み SVG のダイジェストに紐付けます。捕捉された書き込みまたは置換の失敗時には、以前のファイル一式が復元されます。置換の途中でプロセスが終了した場合は、このロールバックの保証対象外です。
7. 引き渡し前に draw.io の付属ファイルをレビューします：
   1. draw.io で diagram.drawio を開きます。
   2. ゾーン、ノードコンテナー、アイコン、ノードラベル、エッジ、エッジラベルをそれぞれ個別に選択できることを確認します。
   3. ノードラベルを移動して保存します。出力では作成時の構造と初期の計算済み配置が維持されますが、SVG バイト列のラウンドトリップや手動ルートの維持は保証されません。
8. 必要に応じて作成済みのリビジョンを比較します：

   python3 -m engine compare base.yaml head.yaml
   

   compare は、作成済みのノード ID とエッジ ID のみをキーとする JSON レシートを出力します。追加、削除、変更、移動、ルート変更されたエンティティを、正確なフィールドパスとともに報告します。必須の制限事項は次のとおりです：Authored specification only; no runtime impact, causality, risk, or merge safety is inferred.
9. 出力します。最終的な .svg と、要求された .drawio の付属ファイルを作業ディレクトリまたはユーザー指定のパスに出力します。特定のプロバイダーで初回のレンダリングだった場合に限り、アイコンキャッシュの前提条件について説明します。

仕様フィールドの概要

スキーマ全体と実例については references/spec-format.md を参照してください。概要：

title: string
direction: LR | TB        # default LR
provider: aws | azure | gcp | generic   # default provider for nodes that omit it
profile: deployment-ownership             # opt-in blocking deployment checks
sources:
  - id: string               # unique authored reference id
    revision: 40-char hex    # declared Git object id
    path: relative POSIX path
    lines: [start, end]      # positive inclusive range
zones:
  - id: string
    label: string
    parent: string | null # nesting — omit for a top-level zone
    kind: generic | region | security # default generic
nodes:
  - id: string             # unique
    label: string
    sublabel: string       # optional secondary line
    service: string        # icon cache slug — see services-aws.yaml / services-azure.yaml / services-gcp.yaml
    provider: string       # overrides the top-level provider for this node
    zone: string | null    # zone id this node belongs to
    color: "#RRGGBB"       # icon fill color
    owner: string          # required for non-external nodes under deployment-ownership
    external: boolean      # default false
    storage: boolean       # true requires a security zone under deployment-ownership
    sources: [source-id]     # optional declared source ids
edges:
  - id: string              # required and stable when using compare
    from: string            # node id
    to: string              # node id
    label: string           # required for security-boundary crossings under deployment-ownership
    type: realtime | batch | event | control | default
    sources: [source-id]     # optional declared source ids

デプロイメント所有権の検証

仕様が視覚的な図にすぎず、デプロイメント所有権レコードである場合にのみ、profile: deployment-ownership を設定します。このプロファイルはフェイルクローズ方式で動作します。すべてのノードがちょうど1つの kind: region に属し、外部ノード以外のすべてのノードに空白でない owner が必要です。また、storage: true のすべてのノードは kind: security の内側にあり、セキュリティゾーンをまたぐエッジには、その仕組みを示す空白でないラベルが必要です。これらの事実をラベル、アイコン、サービスのスラッグ、レイアウトから推測することはありません。既存の動作を維持するには、profile を省略します。

接続タイプの意味

type	color	style	use for
realtime	青	実線	REST、gRPC、同期リクエスト
batch	赤	破線	SFTP、ファイル転送、スケジュール済みジョブ
event	緑	実線	パブリッシュ／サブスクライブ、Webhook、イベント駆動型トリガー
control	オレンジ	実線	管理プレーン、モニタリング、設定のプッシュ
default	グレー	実線	意味が指定されていない場合、またはフロータイプが1種類のみの場合

図で複数の接続タイプが使われると、凡例が自動的に表示されます。すべてのエッジが default の場合は、凡例は表示されません。

未対応／部分的な対応範囲

• Kubernetes およびオンプレミスのプロバイダーには、まだ専用のアイコンセットがありません。将来のマイルストーンでネイティブの K8s／オンプレミスアイコンに対応するまでは、provider: generic を指定してモデル化してください（サーバー、コンテナー、データベース、キュー、および references/icons-generic.md にある31種類の手描きグリフ、合計35種類）。
• GCP と Azure のアイコン対応範囲は AWS より狭いです（それぞれ297種類と約700種類で、AWS は1037種類）。references/services-aws.yaml、references/services-azure.yaml、references/services-gcp.yaml には、誤解を招くアイコンで代用することなく、各プロバイダー固有の不足点（例：GCP には Vertex AI または Artifact Registry 専用のアイコンがなく、Azure には Pipelines／Boards／Artifacts 専用のアイコンがありません）が記載されています。
• インタラクティブな要素（クリックによる遷移、アニメーション、モード切り替え）は対象外です。このスキルが生成するのは静的な SVG 1つです。そうした要素が必要な場合は、static-web-artifacts-builder を使用してください。
• PNG／PDF へのエクスポートは組み込まれていません。ラスター形式が必要な場合は、後から SVG をコンバーターに渡してください：rsvg-convert diagram.svg -o diagram.png または cairosvg diagram.svg -o diagram.pdf。

よくあるパターン

AWS サーバーレス API

title: Serverless API — us-east-1
provider: aws
direction: LR
zones:
  - id: vpc
    label: VPC 10.0.0.0/16
nodes:
  - id: cf
    label: CloudFront
    service: cloudfront
    color: "#8C4FFF"
  - id: apigw
    label: API Gateway
    service: api-gateway
    zone: vpc
    color: "#E7157B"
  - id: fn
    label: Lambda
    service: lambda
    zone: vpc
    color: "#ED7100"
  - id: ddb
    label: DynamoDB
    zone: vpc
    service: dynamodb
    color: "#C925D1"
edges:
  - {from: cf, to: apigw, label: HTTPS, type: realtime}
  - {from: apigw, to: fn, label: invoke, type: realtime}
  - {from: fn, to: ddb, label: query, type: realtime}

Azure Web アプリ（上から下）

title: Azure Web App
provider: azure
direction: TB
nodes:
  - {id: user, label: User, color: "#6B7280"}
  - {id: gw, label: App Gateway, service: application-gateways, color: "#0078D4"}
  - {id: app, label: App Service, service: app-services, color: "#0078D4"}
  - {id: db, label: SQL Database, service: sql-database, color: "#0078D4"}
edges:
  - {from: user, to: gw, label: HTTPS}
  - {from: gw, to: app}
  - {from: app, to: db, label: TDS}

マルチクラウドパイプライン

プロバイダーは自由に組み合わせられます。最上位ではなく、ノードごとに provider を設定してください：

title: Multi-Cloud Data Pipeline
direction: LR
nodes:
  - {id: ingest, label: Kinesis, provider: aws, service: kinesis, color: "#8C4FFF"}
  - {id: transform, label: Dataflow, provider: gcp, service: cloud-dataflow, color: "#4285F4"}
  - {id: notify, label: Logic Apps, provider: azure, service: logic-apps, color: "#0078D4"}
edges:
  - {from: ingest, to: transform, label: stream, type: event}
  - {from: transform, to: notify, label: alert, type: event}

ベンダー中立／オンプレミス

クラウドアイコンのないノードでは、service を省略する（または provider: generic を設定する）と、ラベルの先頭文字を使った色付きのプレースホルダーとして描画されます：

title: On-Prem 3-Tier
provider: generic
direction: LR
nodes:
  - {id: lb, label: Nginx, color: "#3A3A3A"}
  - {id: app, label: App Servers, color: "#3A3A3A"}
  - {id: db, label: PostgreSQL, color: "#3A3A3A"}
edges:
  - {from: lb, to: app}
  - {from: app, to: db}

曖昧さへの対応

• 命名規則からゾーンのネストを推測します（Region > VPC > Subnet、Resource Group > VNet > Subnet）。
• ユーザーがフローの意味を指定していない場合、接続タイプは default とし、凡例は表示しません。
• リクエスト／データフロー図では方向を LR、階層型またはレイヤー型の図では TB にします。
• クラウドプロバイダーが指定されていない場合、またはベンダー中立のアーキテクチャの場合は、provider: generic と手描きアイコンセットを使用します。
• コンポーネント一覧またはトポロジーが根本的に不明確な場合にのみ確認を求めます。アイコンが1つないだけの場合は確認を求めず、上記の「未対応」に従って代替してください。

終了コードと診断

すべての指摘は、code、severity、message、subject（対象）、evidence（対象の位置を示す数値）、supported_fixes（仕様レベルで可能な修正）、および場合によっては suppresses を含む、コード化された診断情報です。終了コードが判定結果を示します。

終了コード	意味	対応
0	validate がエラーの指摘なしで完了した、または deliver が検証済み SVG バンドルをアトミックにコミットした	レシートと要求された成果物を引き渡します。警告は、意図的で説明可能なトレードオフです
1	ブロッキング指摘、または運用上の配信失敗	診断の supported_fixes を適用するか、出力パスまたはファイルシステムの権限を修正します
2	使用方法のエラー — サブコマンドの指定漏れ、読み取り不能な仕様パス、不明なフラグまたはプロファイル値	コマンドを修正します

--json はレシートのみを標準出力に出力します。それには、input とプライマリ SVG artifact の SHA-256／バイト数の記録、output.written、validation.checks_passed／checks_total、品質、構成ステータス、重大度別の件数、および診断情報が含まれます。--emit drawio が指定されている場合、artifacts にはコミットされたすべての出力について、パス、SHA-256、バイト数が一覧表示されます。--quality showcase は composition/* の経路ジオメトリに関する指摘をエラーにします。デフォルトの standard では警告のままです。

コード	意味	修正方法
spec/*	仕様を解釈できません。ノードがない、ID が重複または欠落している、ゾーン／親／エッジの終点が不明、ゾーンに循環がある、ゾーンが空である、などです	各診断の supported_fixes に、変更するフィールドが示されます
icon/not-found	service スラッグがそのプロバイダーのキャッシュにないか、キャッシュがまだ取得されていません	そのプロバイダーの参照サービスマップにある正確なスラッグを使用するか、fetch_icons.py --provider <name> を実行します。意図的にラベル付きプレースホルダーを使用するには、service を削除します
layout/node-overlap	2 つのノードボックスが重なっています	ノードを異なるランクに分けるか、重複を削除します
layout/zone-overlap	メンバーノードが交互に配置されているため、互いに無関係な 2 つのゾーンボックスが重なっています	nodes 内で各ゾーンのメンバーを連続して並べるか、zone の割り当てを修正します
layout/label-overflow	ハード最小値の 6px でも、label または sublabel がノードボックスに収まりません（ブロッキング）	テキストを短くするか、詳細を sublabel に移します
editability/*	出力にラスター、<use>、または外部参照が含まれています	レンダラーのバグです。仕様が原因ではありません。報告してください
usage/spec-unreadable	仕様パスが存在しないか、読み取れません	既存の読み取り可能な YAML パスを指定します

取得失敗（could not fetch <provider> icons）はネットワークの問題であり、仕様の問題ではありません。そのプロバイダーについて fetch_icons.py を再実行してください。すでにキャッシュされているアイコンはスキップされます。

出力

SVG のパス、要求された draw.io 用の付随ファイルのパス、および未解決の警告レベルの指摘とその理由を報告します。アイコンキャッシュの取得コストに触れるのは、該当プロバイダーで初めてレンダリングするときのみです。

参照表

ファイル	内容	読むタイミング
references/spec-format.md	YAML 仕様の完全なスキーマを、フィールドごとにエッジケースも含めて記載	仕様を作成する前に必ず
references/services-aws.yaml	AWS サービス名 → アイコンスラッグと色、約 70 件、文書化された不足項目	AWS コンポーネントを図示するとき
references/services-azure.yaml	Azure サービス名 → アイコンスラッグと色、約 45 件、文書化された不足項目	Azure コンポーネントを図示するとき
references/services-gcp.yaml	GCP サービス名 → アイコンスラッグと色、約 35 件、文書化された不足項目	GCP コンポーネントを図示するとき
references/icons-generic.md	クラウド以外の図で使える、手描きの汎用アイコン 35 種（サーバー、データベース、キュー、ユーザーなど）	provider: generic を指定するとき、またはクラウドに相当するものがないノードがあるとき
references/editability.md	出力で <use>／ラスター／アウトライン化されたテキストを使用しない理由と、「編集可能」で実際に検証される内容	レンダラーの出力仕様を理解または変更するとき

エンジン

ファイル	用途
engine/__main__.py	検証、配信、比較を行う python3 -m engine のエントリーポイントです。
engine/pipeline.py	仕様から SVG を決定論的に構成し、レンダリング結果を生成します。
engine/commands.py	検証、配信、比較の記録、ステージング、CLI のディスパッチを行います。
engine/fetch_icons.py	ローカルのアイコンキャッシュを構築します。python3 -m engine.fetch_icons で実行します。
engine/stencil2svg.py	AWS/GCP のステンシルを SVG に変換します（内部用）。
engine/svg_inline.py	Azure の実 SVG をインライン化し、名前空間を付与します（内部用）。
engine/data.py	同梱アセットと参照データの単一リゾルバーです。

アセット

ファイル	内容
assets/example-serverless.yaml	完全な実例仕様（AWS、ゾーン、複数の接続タイプ）です。出発点としてコピーしてください。
assets/example-serverless.svg	その仕様を実際にレンダリングした出力です。参照用にコミットされています。
assets/generic-icons.json	BundledGenericIconLookup が読み取るデータです。references/icons-generic.md は、同じ内容をエージェントが読み取れる形式で記載したものです。