aws-architecture-diagram

AWS4 アイコンを使用して draw.io XML ファイルを生成する、AWS アーキテクチャ図ジェネレーターです。生成する図は、AWS 公式リファレンスアーキテクチャ図のスタイルに必ず合わせてください。プロフェッショナルなタイトルとサブタイトル、右側の凡例とティール色の番号付きステップバッジ、色付きカテゴリコンテナ内の48x48サービスアイコン、読みやすいHelveticaタイポグラフィ、明確なデータフローを備えます。

ワークフロー

ステップ1：モードを決定する

モードA — コードベース分析： ユーザーが「analyze」「scan」「from code」と述べた場合、または既存のプロジェクトに言及した場合：

1. インフラストラクチャファイルをスキャンします：CloudFormation（AWSTemplateFormatVersion、AWS::*）、CDK（cdk.json、コンストラクト定義）、Terraform（resource "aws_*"）
2. サービス、関係、VPC 構造、データフローの方向を抽出します
3. AWS インフラストラクチャファイルが見つからない場合は、AWS 以外のテクノロジーをスキャンします：Dockerfile、データベース設定、API 統合、ML フレームワーク（pytorch、tensorflow、coreml）、メッセージブローカー（kafka、rabbitmq）。検出したテクノロジーは references/general-icons.md を使ってマッピングします
4. AWS と AWS 以外が混在するアーキテクチャでは、AWS サービスには AWS アイコンを、AWS 以外には汎用アイコンを使用します。同じレイアウトルールを適用します
5. 生成前に、検出したアーキテクチャをユーザーに確認します
6. アーキテクチャを最もよく表す図の種類を尋ねます

モードB — ブレインストーミング： ユーザーがアーキテクチャを説明した場合、または「brainstorm」「design」「from scratch」と述べた場合：

1. 要点を絞った質問を3～5個します（目的、サービス、規模、セキュリティ、トラフィックパターン）
2. サービスの推奨事項とデータフローを含めてアーキテクチャを提案します
3. 必要に応じて調整し、その後生成します

ステップ2：スタイルの選択

これらはモードとは独立しており、モード選択後に適用します。

• スケッチモード：ユーザーが「sketch」「hand-drawn」「sketchy」と指定した場合にのみ有効になります。デフォルト：オフ（Helvetica、スケッチ属性なし）。以下の「スタイルルール」の「スケッチモード」を参照してください。
• 凡例パネル：サービスが7つ以上ある場合、または分岐経路が複数ある場合にデフォルトで有効になります。「no legend」「without legend」「skip steps」「no sidebar」とユーザーが指定した場合にのみ無効になります。
• エクスポート形式：形式を示すキーワード（png、svg、pdf）があるか確認します。デフォルト：.drawio のみ。

ステップ3：図の XML を生成する

ここで参照資料を読み込みます（このステップより前には読み込みません）。

1. 図形のスタイル、ラベルの配置、構造ルールについて references/xml-rules.md を読みます
2. 色、フォント、ダークモードについて references/style-guide.md を読みます
3. XML コードブロックについて references/xml-templates-structure.md を読みます
4. 間隔とエッジのルーティングについて references/layout-guidelines.md を読みます
5. 以下の表のサンプル項目は、エッジのルーティングとレイアウトパターンの概念的な参考としてのみ使用してください。参考資料として .drawio ファイルを開いたり読み込んだりしないでください。

サンプルの選択 — ユーザーのアーキテクチャに最も関連するサンプルを選びます。

図の種類	メインのサンプル	サブのサンプル
サーバーレス／API	example-saas-backend.drawio	example-event-driven.drawio
イベント駆動型／非同期	example-event-driven.drawio	example-microservices.drawio
マイクロサービス／ECS	example-microservices.drawio	example-complex-platform.drawio
マルチリージョン	example-multi-region-active-active.drawio	—
複雑な構成（サービス13個以上）	example-complex-platform.drawio	example-saas-backend.drawio
AI／AgentCore	example-agentcore.drawio	example-event-driven.drawio
スケッチモード	example-sketch.drawio	+ 上記から1つ

1. アーキテクチャに AWS 以外のサービスが含まれる場合は、references/general-icons.md も読みます
2. 読み込んだすべてのルールと、選択したサンプルのパターンに従って XML を生成します
3. ステップ2で選択したスタイルを適用します

ステップ 4：検証とエクスポート

1. .drawio ファイルを ./docs/ に書き込みます

2. PostToolUse フックが XML を自動的に検証します（修正パイプラインについては references/post-processing.md を参照してください）

3. 検証に失敗した場合は、エラーを修正して書き直します

4. バッジの重なりを修正します：python3 ${PLUGIN_ROOT}/scripts/lib/fix_step_badges.py ./docs/<filename>.drawio

5. 検証に合格したら、プレビュー URL を生成します：

   python3 ${PLUGIN_ROOT}/scripts/lib/drawio_url.py ./docs/<filename>.drawio --open
   

6. エクスポート形式が指定されている場合は、draw.io CLI を実行します（references/cli-export.md を参照してください）

デフォルト設定

• モード：コードベースのコンテキストがない場合はブレインストーミング
• フォント：fontFamily=Helvetica（Comic Sans MS はスケッチモードでのみ使用）
• アイコンサイズ：120x120 のコンテナ内に 48x48
• 間隔：サービスグループのコンテナ間は水平方向に 180px、垂直方向に 120px
• 凡例：サービスが 7 つ以上の場合は必ず表示します（ユーザーが不要と指定した場合を除く）
• スケッチモード：オフ（ユーザーが明示的に要求した場合を除く）
• ダークモード：すべての構造要素で light-dark() を使用（常に有効）
• エクスポート形式：.drawio（ユーザーが png/svg/pdf を要求した場合を除く）
• グリッド：オフ（grid=0）
• ファイルの場所：./docs/ ディレクトリ
• XML 形式：圧縮なし、<mxfile><diagram><mxGraphModel> でラップ

エラー処理

• XML 検証の失敗：報告されたエラー（タグの不整合、ID の欠落、無効な図形）を修正し、ファイルを書き直して再検証します
• 図形が見つからない：有効な mxgraph.aws4.* 名について references/aws4-shapes-services.md を確認します
• draw.io CLI が見つからない：.drawio ファイルのみを書き込み、エクスポートをスキップして、draw.io デスクトップ版のインストールをユーザーに案内します
• 無効なエッジの始点／終点：すべての source= および target= ID が既存の mxCell 要素を参照していることを確認します
• XML コメント内の連続ハイフン：XML の仕様では `` の内部に -- を使用できません。ハイフンを 1 つだけ使うか、表現を変えてください
• 特殊文字：属性値内の &、<、>、" をエスケープします

スタイルルール

スタイルの詳細は references/style-guide.md に記載されています。必ず守る必要がある重要なルールは次のとおりです：

• フォント：すべてのテキストで必ず fontFamily=Helvetica; を使用します（Comic Sans MS はスケッチモードでのみ使用）
• ダークモード：すべての構造要素で必ず fillStyle=auto; を指定した light-dark() の塗りつぶしを使用します。色の一覧は style-guide.md を参照してください。
• リージョングループ：必ず container=0（装飾専用）を使用します。サービスは絶対座標を使って parent="aws-cloud" に配置します。
• グループの fontColor：グループの strokeColor と必ず一致させます（VPC：#8C4FFF、Public subnet：#248814、Private subnet：#147EBA、Region：#00A4A6）。fontColor=#AAB7B8 は絶対に使用しないでください。
• フォント階層：タイトル 30px 太字 > サブタイトル 16px > グループ 14px 太字 > コンテナ 12px 太字 > サービス 10px > エッジ 11px
• カテゴリコンテナ：すべての 48x48 アイコンは、カテゴリのティントカラーを使用した 120x120 のコンテナ内に配置します。ティントカラーの一覧は style-guide.md を参照してください。
• AgentCore：resIcon=mxgraph.aws4.bedrock_agentcore を使用します（mxgraph.aws4.bedrock は使用しないでください）
• スケッチモード：ユーザーが要求した場合にのみ使用します。アイコン以外の要素に sketch=1;curveFitting=1;jiggle=2 を追加します。サービスアイコンは sketch=0 のままにします。
• AWS 以外のサービス：references/general-icons.md を参照し、最も近い汎用アイコンに対応付けます。120x120 のコンテナと 48x48 のアイコンの組み合わせを使用します。機能上の役割（データベース、コンピューティングなど）に応じたカテゴリのティントカラーを適用します。アイコンは汎用的なため、ラベルが重要です。

図の種類

• VPC／ネットワーク：VPC、サブネット、セキュリティグループ、NAT ゲートウェイ、ロードバランサーをグループ図形で表現
• サーバーレス：API Gateway、Lambda、DynamoDB、S3、Step Functions、EventBridge
• マルチリージョン：レプリケーション、Route 53、Global Accelerator を含む複数のリージョン
• CI/CD パイプライン：CodeCommit/GitHub -> CodeBuild -> CodeDeploy -> ターゲット
• データフロー／分析：Kinesis、S3、Glue、Athena、Redshift、QuickSight のパイプライン
• コンテナ：ECS/EKS クラスター、ECR、Fargate、ロードバランシング
• ハイブリッド：Direct Connect、VPN、Transit Gateway を介したオンプレミス + AWS

レイアウトパターンについては、references/diagram-templates-basic.md と references/diagram-templates-advanced.md を参照してください。

XML 生成ルール

XML テンプレート、スタイル文字列、コード例の詳細については、references/xml-rules.md を参照してください。主な構造ルールは次のとおりです。

必須の構造

必ず完全な mxfile ラッパーを使用してください。

<mxfile host="Electron" version="29.6.1">
  <diagram name="Page-1" id="diagram-1">
    <mxGraphModel dx="1200" dy="800" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="1100" pageHeight="850" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

• セル id="0" はルートレイヤー、セル id="1" はデフォルトの親です（どちらも必須です）。
• コンテナー内にネストされている場合を除き、すべての図要素で parent="1" を使用してください。
• 説明的なセル ID を使用してください：vpc-1、lambda-orders、s3-assets、edge-lambda-to-dynamo

主な原則

• 必ず mxgraph.aws4.* 名前空間を使用してください。メインのサービスアイコンには resourceIcon;resIcon= を使用し、コンポーネントにはサブリソーススタイルを使用してください。
• コンテナーの value にはカテゴリ名（例：「DNS」、「Compute」）を設定します。アイコンの value にはサービス名と、任意でイタリック体のサブラベルを設定します。コンテナーにはサービス名を絶対に設定しないでください。
• エッジはコンテナーではなく、サービスアイコンに接続します。exitX／exitY と entryX／entryY（0-1）を使用して、接続する辺を制御してください。
• エッジラベルは、connectable="0" と relative="1" のジオメトリを持つ、個別の子セルにしてください。
• リージョングループには container=0（装飾のみ）を使用します。VPC／サブネットには container=1 を使用します。
• フラットなレイアウトを優先してください。実際のインフラ境界（VPC、サブネット、AZ）の場合に限り、ネストしたコンテナーを使用してください。
• 外部のアクターには、表示されるコンテナー（fillColor=#f5f5f5）を使用し、タイトルブロックより下の y >= 140 に配置してください。

レイアウトガイドライン

詳細な間隔ルール、エッジのルーティングパターン、配置表については、references/layout-guidelines.md を参照してください。主なルールは次のとおりです。

• 間隔：水平方向は 180px、垂直方向は 120px の間隔を空けます。サービスが 13 個以上の場合は、220px／160px に広げてください。
• エッジのルーティング：orthogonalEdgeStyle を使用してください。隣接していない要素を結ぶ場合は、明示的な経由点を追加してください。エッジはコンテナーの面に対して垂直に出るようにします。
• 複数のエッジ：各出力エッジは、必ず異なる位置から出るようにしてください。同じターゲットに複数のエッジが入る場合は、入力位置を分散させてください。
• ステップバッジ／凡例：矢印の起点近くに、ティール色 #007CBD の 28x28 バッジを配置します。サービスが 7 個以上の場合は、右側のサイドバーに凡例を配置してください。凡例の高さは、必ず図の高さに合わせてください。
• 補助サービス：CloudWatch、CloudTrail、X-Ray、IAM のみです。ステップ番号やエッジは付けません。AWS Cloud 境界内の破線の「Auxiliary Services」グループに配置してください。
• その他すべてのサービスは主要サービスです — 必ずエッジとステップ番号を付けてください。

ファイル名

各図には、kebab-case 形式の説明的なファイル名を付け、./docs/ に配置してください（例：docs/healthcare-appointment-agent.drawio、docs/3-tier-vpc-webapp.drawio）。ユーザーが既存の図の更新を明示的に依頼した場合を除き、必ず新しいファイルを作成してください。

出力

1. docs/ ディレクトリが存在しない場合は作成します

2. ユーザーのプロンプトからファイル名を決定します（上記の「ファイル名」を参照）

3. ユーザーが既存の図の更新を明示的に依頼した場合を除き、必ず新しいファイルを作成します

4. 図を ./docs/<descriptive-name>.drawio に保存します

5. 書き込み後、PostToolUse フックが自動的に次の処理を行います。 a. XML を検証します（構造、AWS シェイプ、エッジ、ジオメトリ） b. 検証に合格した場合、draw.io のプレビュー URL を生成します

6. 検証に失敗した場合は、エラーを修正してファイルを書き直します

7. 検証に合格した後に限り、次を実行してブラウザーのプレビューリンクを生成します。

   python3 ${PLUGIN_ROOT}/scripts/lib/drawio_url.py ./docs/<filename>.drawio --open
   

   これにより XML が圧縮され、図を読み込んだ状態で app.diagrams.net がすぐに開きます。検証に失敗した場合は実行しないでください。

8. ユーザーがエクスポート形式（png、svg、pdf）を指定した場合： a. draw.io デスクトップ CLI が利用可能か確認します b. --embed-diagram を指定して、./docs/<filename>.drawio.<format> にエクスポートします c. 成功した場合は、中間ファイルの .drawio ファイルを削除します

9. 必ずユーザーに次の情報を提示します：

   • ファイルパス
   • 図の種類と含まれるサービス
   • 検証ステータス
   • draw.io のプレビュー URL（ブラウザーで開くクリック可能なリンク）
   • 推奨する代替テキスト（図の目的を説明する、100 文字未満の簡潔なテキスト。「diagram of...」のような表現は使用しないでください）

重要：XML の整形式性

• XML コメント内で二重ハイフン（--）を絶対に使用しないでください。 XML 仕様では `` 内の -- は不正であり、解析エラーの原因になります。単一のハイフンを使うか、表現を変更してください。
• 属性値内の特殊文字はエスケープしてください：&、<、>、"
• 各 mxCell には必ず一意の id 値を使用してください

重要なルール

• 圧縮形式／base64 形式の図コンテンツは絶対に使用しないでください
• 図形名を絶対にでっち上げないでください。references/aws4-shapes-services.md にある図形のみを使用してください
• XML は必ず <mxfile><diagram><mxGraphModel> で囲んでください。<mxGraphModel> 単体にはしないでください
• ルートとデフォルトレイヤーとして、必ず id="0" および id="1" のセルを含めてください
• メインのサービスアイコンには必ず resourceIcon;resIcon= スタイルを使用してください
• グループ図形には必ず container=1;pointerEvents=0; を設定してください
• エッジのソース／ターゲット ID が既存のセルを参照していることを必ず検証してください
• すべての図の上部に必ずタイトルブロックを含めてください
• 48x48 のサービスアイコンは、必ず色付きのカテゴリコンテナ内に配置してください
• すべてのスタイル属性で必ず fontFamily=Helvetica; を使用してください
• 複雑な図（サービスが7個以上）の場合は、必ずステップバッジと凡例を追加してください
• ランダムな文字列ではなく、内容がわかるセル ID を付けてください（例：cell-47 ではなく、vpc-1、lambda-orders）
• アーキテクチャ内での役割が明確になるよう、サービスアイコンに斜体のサブラベルを追加してください
• ユーザーが明示したサービス、またはデータフローに不可欠なサービスのみを含めてください。ユーザーから依頼されない限り、横断的な関心事（IAM、CloudWatch、CloudTrail、KMS、ログ用の S3 など）を追加しないでください
• アーキテクチャを説明するタイトル／ラベルを図に含めてください
• mxGraphModel に background 属性を絶対に設定しないでください。背景色を固定すると、ダークモードの適応型コントラストが損なわれます

参照資料の優先順位

図を生成する際は、以下の優先順位に従ってください。

1. このスキルの XML 生成ルールとスタイルガイド（常に最優先）
2. references/ にあるこのスキルのサンプル .drawio ファイル（ステップ3の選択表）
3. ユーザーが明示的に依頼した場合（「自分のスタイルに合わせて」「図を更新して」など）に限り、ユーザーの既存の .drawio ファイルを参照してください

ユーザーが参照または修正を明示的に依頼しない限り、ユーザーのプロジェクト内にある .drawio ファイルを先回りして読み込まないでください。スタイルと構成には、常にこのスキル独自のサンプルとルールを優先してください。