AWS draw.io構成図

実行環境

Python 3.9以降と、使用するAWS図形を表示できるdraw.io Desktopを用意する。検証スクリプトはPython標準ライブラリだけで動く。Windowsではdraw.io.exe、macOS/Linuxではインストール先のdraw.io実行ファイルを使い、利用者固有の絶対パスを固定しない。

python scripts/validate_aws_drawio.py <diagram.drawio>

検証対象は展開済みXMLのdraw.ioファイル。圧縮形式の場合はdraw.ioで非圧縮XMLとして保存する。同梱サンプルは配置・スタイルの参照であり、現行ルールへの適合は作図時に再確認する。validatorはXMLと一部スタイルのみを検査し、構成の正しさ・表示品質は実装照合と画像レビューで確認する。

正本

• AWS公式のArchitecture Iconsを正本とする。
• 作成・レビュー前にreferences/aws-official-diagram-guidelines.mdを最後まで読み、AWS公式Light-BG deckの表記・配置ルールを適用する。
• 新規作成または構成理解を伴う大幅修正では、作図前にreferences/architecture-understanding-guide.mdを最後まで読み、対象プロジェクトの一時フォルダへインフラ構成の理解ガイドを作成する。既存ガイドがある場合は再作成せず、実装との差分だけ確認して作図要件として使う。
• 初回案の提示前にreferences/self-review-and-user-feedback.mdを最後まで読み、セルフチェックで見つけた修正点を列挙した状態でユーザーへ早期提示する。
• 公式ページの「Draw.io」からdiagrams.netを開き、必要なAWS図形をキャンバスへ置いてローカルへ保存する。
• 保存した.drawioには配置した図形だけが入る。パレット全体が埋め込まれるとはみなさない。必要なサービスをすべて配置してから保存する。
• assets/sample-architecture-icons.drawioを公式Draw.ioから保存した図形スタイルのサンプルとして使う。必要な図形がサンプルにない場合は公式Draw.ioで追加取得する。
• WorkmateまたはAgentCoreの構成図で、境界、レーン、補足カードの配置を検討するときはreferences/layout-reference-samples.mdを読み、掲載画像を目視する。画像はレイアウト参考に限り、構成事実やAWSアイコンの正本にはしない。
• 第三者記事や既存テンプレートはレイアウトの参考に限り、アイコンの正本にしない。

draw.ioバージョン事前確認

• 作業開始時に、実際に編集・PNG書き出しへ使うdraw.io Desktopのバージョンをdraw.io.exe --versionまたは実行ファイルのFileVersionで確認し、作業メモへ記録する。検出できない場合はユーザーへ使用版を確認する。
• 検出したバージョンを作業開始時にユーザーへ明示し、ユーザーが認識しているアプリ版と一致するか確認する。ユーザーがアップデート済みと伝えた場合は、その申告を旧検出結果で上書きせず、実行ファイルを再検出して一致確認が取れるまで編集・固定PNG承認へ進まない。
• AWS公式で追加された新しいstencilを使う場合、インストール版が現行公式リリースまたはそのstencilを正常表示できる版か確認する。古い版、版不明、必要stencil非対応の場合は、作業継続前にユーザーへ状況を伝えて更新を依頼・確認する。
• 編集、固定PNG書き出し、最終再表示は同じdraw.ioメジャー／マイナーバージョンで行う。古いレンダラーでglyphが欠落したPNGを代用せず、正常表示できる版で全ページを再生成して以前の視覚承認を失効させる。
• とくにAmazon Bedrock AgentCoreはバージョン差の回帰検査対象とする。今回確認済みの具体例として、draw.io 29.0.3ではbedrock_agentcoreが緑一色になり、31.1.8では白glyphを含めて表示された。バージョン番号だけで合格にせず、固定PNGの実表示を最終根拠にする。

アイコンの扱い

• 参照用.drawioの該当mxCellからstyleを抽出し、図へ移植する。
• 現行のAWSリソースアイコンは、色付き背景、白い線画を基本とする。resourceIconでは次を満たすこと。

shape=mxgraph.aws4.resourceIcon
resIcon=mxgraph.aws4.<service>
strokeColor=#ffffff

• strokeColor=noneを指定しない。黒線表示になり、公式の見た目と一致しない。
• Amazon Bedrock AgentCoreはresIcon=mxgraph.aws4.bedrock_agentcoreを使用する。
• Amazon Bedrock AgentCoreはdraw.ioのバージョンやstencil解決状態によって、緑の塗りつぶしだけになり白いglyphが消える事象を重点検査する。XML上のresIconだけで合格にせず、編集画面と100%固定PNGの両方で白いAgentCore glyphを確認する。単色なら公式SVGまたはGeneral Resourcesへ切り替え、再レンダーする。
• resourceIconが公式draw.ioライブラリにあるAWSサービスは、同じ見た目の埋め込みSVGで代用せずresourceIconを優先する。公式draw.ioに未収録の場合だけ公式SVGのdata URI埋め込みを許可し、理由をレビューで確認する。
• resIcon名がXMLに存在しても、固定PNGで白いglyphが消えて単色の塗りつぶし矩形になる場合は未登録・非対応stencilとして不合格にする。別名を推測して残さず、公式SVGが取得できなければサービス名を明記した主要オブジェクト（白背景＋カテゴリ色枠）またはGeneral Resourcesへ切り替える。
• 同じ図で使うAWSサービスアイコンは、公式toolkitの既定サイズに合わせて同一サイズ・正方形にする。図内で個別に拡大縮小しない。
• アイコンの色、形、縦横比を変えず、切り抜き、反転、回転をしない。
• 目的の公式図形を確認できない場合、別サービスのアイコンで代用しない。未解決として示し、公式パレットで図形名を確認する。
• 外部URLの画像参照は使わない。draw.io内蔵図形、または公式SVGをdata URIとして埋め込み、単一ファイルで開けるようにする。

作成手順

1. draw.ioの使用バージョンを確認して作業メモへ記録し、必要stencilを正常表示できない場合はユーザーへ更新・使用版を確認する。
2. IaC、アプリコード、運用資料を読み、references/architecture-understanding-guide.mdの仕様で対象プロジェクトの理解ガイドを一時フォルダへ作る。既存ガイドがあれば内容を実装と照合して流用する。
3. 理解ガイドを作図要件として、作るリソース、既存参照、条件付き要素、意図的に存在しない要素、通信、IAM、デプロイ依存を図のページとレーンへ割り当てる。IaCと実装が最終的な事実の正本であり、差分を見つけたら図より先にガイドを直す。
4. 利用者経路、認証経路、アプリ実行経路、デプロイ経路を分ける。
5. 信頼境界を先に配置し、その後にAWSリソースと矢印を置く。
6. 公式draw.ioページから必要なアイコンを配置して保存し、各mxCellのスタイルを採用する。
7. .drawioを作成し、scripts/validate_aws_drawio.pyでXMLとアイコンスタイルを検証する。
8. draw.ioで実際に開き、「ページ全体表示」と75〜100%表示を確認する。さらにPNGを100%で書き出し、固定画像を原寸表示して確認する。編集画面のスクリーンショットだけで完了しない。
9. validator、draw.io実表示、固定PNG原寸表示が成立したら、このファイルの全自己レビュー観点を一度走査する。XML不正、レンダー失敗、AWSアイコンのglyph欠落だけは初回提示前に直す。
10. その他の修正点は先回りして直さず、重要度、画像上の場所、根拠、修正案を短く列挙し、初回の.drawioと固定PNGをユーザーへ提示する。ユーザーが見た目と情報量を判断できる段階までを最優先する。
11. ユーザーの指摘とセルフチェック結果を一つの修正バッチへまとめて反映する。修正後はvalidatorと変更箇所・影響範囲を確認して再提示する。ユーザーから追加修正の依頼がない限り、自律的な磨き込みループを開始しない。
12. ユーザーが完成を確認した版を正規ファイル名へ反映する。実装との重大な事実不一致、誤った所有・地理・信頼境界が残る場合は、完成扱いにせず具体的に説明する。

図の設計

• 主経路は左から右へ配置する。ブラウザ、公開入口、BFF、AgentCore、モデル推論の順に読むだけでE2Eが追えるようにする。
• 主経路のサービスアイコンは原則40〜56px程度に抑え、アイコン間にラベルと矢印のための余白を確保する。大きなアイコンで情報量を表現しない。
• 横幅へ詰め込まず、必要ならページの縦幅を広げる。主経路、デプロイ、認証・データ、ログの各レーンに、アイコン、ラベル、説明カードが重ならない高さを割り当てる。
• CloudFront OACによるオリジン保護と、Cognitoによる利用者認証を別の信頼境界として描く。
• ブラウザがAgentCoreを直接呼ばない構成では、必ずBFF経由の矢印にする。
• 要求とストリーミング応答が同じ経路なら、交差する2本の線を増やさず双方向線または明確な往復ラベルを使う。
• 接続線は原則として黒い実線に統一する。デプロイやログを破線などで区別するのは、図の局所だけを切り出しても凡例なしで意味を復元できる場合、またはユーザーが凡例を許可した場合に限る。線種を変える場合も接続線は黒を維持し、境界線には黒以外のAWS公式色または用途固有色を使って、局所的に接続と境界を判別できるようにする。
• 構成図の外周に置く文章は、原則として左上の1行タイトルだけにする。副題、スコープ説明、E2Eの要約、デプロイ先メタデータ、CDKメタデータ、凡例、レビュー注記を追加しない。
• AWSアカウント、リージョン、VPC、CloudFormation/CDKスタック、信頼境界などのスコープは、説明カードではなくAWS公式のグループ枠・グループアイコン・ラベルで表現する。
• AWSの要素を囲む独自枠をラベルだけで済ませない。適切なプリセットがないStack、account-global IAM、cross-Regionなども、公式generic/custom groupまたは意味を表す公式グループマーカーを枠内に付ける。マーカーのないAWSスコープ枠は不合格とする。
• グループ境界にdraw.ioの折りたたみ機能を付けない。マイナス記号やプラス記号でアコーディオンのように開閉できるコンテナは禁止する。親子関係を保持する必要がある場合もcontainer=1;collapsible=0を明示し、固定PNGだけでなくdraw.io編集画面で折りたたみUIが出ないことを確認する。
• グループ、ローカル環境、AWS Cloud、account、Region、VPC、Stackなどの四角い境界は、原則fillColor=noneの透明背景にする。境界全体をグレーで塗らない。補足カードだけを薄いグレーにし、透明化後の固定PNGで補足のグレーが識別できることを再確認する。
• 矢印をサービスアイコン、説明カード、境界見出しの上へ通さない。直交線と明示的な中継点を使う。
• 矢印をアイコンの頂点や角へ接続しない。接続点は辺の中央寄り（原則として辺長の20〜80%）へ置き、同一アイコンから複数線を出す場合は各線へ別の接続点を割り当てる。固定PNGで、別の線から分岐しているように見えないことを確認する。
• 別の意味を持つ複数接続に、同一のsource/targetポート、最初の区間、最後の区間を共有させない。共有した線がT字・Y字・一本の線からの分岐に見えたら、実際の分岐意図がない限り不合格とする。source/targetの辺上位置とレーンの両方を分離する。
• 異なる接続線同士を、回避可能なのに交差させない。同一sourceから複数targetへ接続する場合は、targetの左右順とsourceポートの上下順を一致させる。CloudWatchとX-Rayのようにtarget位置の交換で交差を消せる場合は、オブジェクトを入れ替えてから経路を引く。
• 左右から入出力する線は左右辺の中央付近を使う。複数線は原則30%、50%、70%付近へ分散し、20%未満または80%超の角寄りへ置かない。上下面へつなぐ線と接続点を共有しない。
• アイコン間を結ぶ主経路、下段の認証・データ経路、上段または下段のデプロイ・ログ経路を別レーンにする。補助線は説明カードの左右を迂回させる。
• エッジラベルは独立したテキストオブジェクトにする。白塗り背景を無条件に使わない。白塗りラベルは背後の境界線、破線、アイコンを消すため、配置範囲が他オブジェクトと交差しない場合だけ使う。交差を避けられない場合は透明背景へ変更し、線が文字を通らない位置へ移す。
• サービスのアイコン、サービス名、補足は可能な限り同じ中心線上へ縦1列で配置し、各テキストを中央揃えにする。線と衝突する場合は、まずサービスオブジェクト自体を動かして列と経路の両方を整える。
• 補足カードは原則として中立的な薄いグレー背景（例：#F2F3F3）、枠線なし、中央揃えにする。独立して意味を持つ主要オブジェクト（例：非公開Runtime ZIP）は補足カードとして扱わず、意味に合う非グレー背景を使用してよい。
• ラベル、アイコン、説明カード、グループ見出しの矩形範囲を相互に確認し、数pxでも重ねない。特にアイコンの角、境界線、別用途のエッジへラベルを被せない。
• サービス、デプロイ部品、ラベルを境界線へ接触させない。境界の内側へ視認できる余白を取り、エッジラベルが境界線を横切る場合はラベルを移動して完全に分離する。
• 下向きの補助線をアイコン直下のサービス名や説明カードへ通さない。アイコンの左右から分岐し、カード外側へ回してから下段へ接続する。
• 終端付近に短い水平・垂直線や行き過ぎて戻る折り返しを作らない。ターゲット中心と最後の中継点を揃え、不要な中継点を削除する。視認用の接続線は原則24px以上を確保する。
• 直線で結べる関係は直線を優先する。不要なジョグが出たら中継点だけで補正せず、source/targetの接続位置とサービスオブジェクトの座標を試行錯誤し、100%固定PNGで最も自然な配置を選ぶ。
• 直線化できる線に直角を残さない。まずsource/targetの中心線を揃えるためにオブジェクト位置を動かし、次に辺上ポートを20〜80%の範囲で調整し、それでも必要な場合だけ24px以上の直角区間を使う。境界をまたぐこと自体を理由に不要な角を作らない。
• 公式サービス名をラベルに使う。実装固有値は補足カードへ置く。
• AWSサービスのアイコンラベルは12pt Arialにし、2行以内に収める。AWSまたはAmazonだけを改行でサービス名から切り離さず、単語の途中で改行しない。
• AWS公式ドキュメント、公式toolkit、Architecture Iconsで使われている名称をそのまま使う。公式に通用している短縮名は積極的に使う。 Amazon S3、AWS IAM、Amazon VPC、Amazon ECS、AgentCore Runtimeのような短縮名は、同じ図の中で正式名称を先に示さなくてもラベルへ直接使ってよい。
• 長い正式名称がラベルで2行に折り返す場合や、隣の要素と接触する場合は、公式の短縮名を選ぶ。図の可読性を名称の冗長さより上に置く。
• 禁止するのは独自の造語・非公式な略記だけとする。公式にない形へ短縮しない。異なるサービスへ同じ短縮形を割り当てない。
• AWSのグループは公式のグループアイコンとラベルを組み合わせ、グループアイコンを拡大縮小しない。入れ子のグループ間には余白を確保する。
• AWS Cloud、AWS account、Region、VPC、Stack、IAM範囲などを示す左上の公式グループアイコンは、境界の左上頂点とアイコンの左上頂点を一致させ、隙間を作らない。draw.io XMLでは境界の直接子にした32pxマーカーを原則x=0;y=0へ置く。ラベルだけを右へ逃がし、アイコン自体を内側へインセットしない。
• 接続線とすべての境界線に同じ色を使わない。AWS Cloudも含む境界は非黒色の公式色または用途固有色にし、境界交差部分だけを切り出しても黒い接続線と即座に判別できることを合格条件にする。
• 境界名は囲んでいる実体と一致させる。CloudFormation/CDKスタック、AWSアカウント、リージョン、VPC、アプリの信頼境界を混同せず、実際にその境界へ属するリソースだけを囲む。
• 包含関係を一種類の入れ子として扱わない。地理、ネットワーク、IaC管理、信頼、実行、デプロイの各スコープを区別する。同じリソースが複数の直交するスコープへ属する場合、誤った親子関係を示す無理な入れ子を避け、境界の交差、隣接、または別ページへの分離を選ぶ。
• ノードごとに地理、IaC管理者、所有者（customer-managed/AWS-managed）、管理状態（created/referenced/existing）を別々に復元する。CloudFormation Stack自体のリージョンと、そのStackが作成するaccount-global IAMリソースを同じ地理枠へ押し込めない。
• API呼出先として参照するだけのAWS managed service（例: AWS STS）は、ユーザーアカウント内のIAMリソース群やCloudFormation Stack管理枠へ包含しない。サービスendpointと、ユーザーが所有・管理するrole/policyを別の集合として描く。
• 接続ごとにcontrol plane/data plane、bootstrap/deploy/runtime、実API呼び出し/AWSマネージド動作/permission-onlyを区別する。権限があるだけの経路を実通信と断定しない。
• profile、IAM user/role、STS AssumeRole、一時credentials、実API呼び出しをcredential chainの小単位としてE2E確認する。スクリプトやcredentialsカードが図上にあるだけでAWS主体へ未接続な状態を許可しない。
• CloudFormation Custom Resourceは、Custom Resource、service token、Lambda、Lambda Permission、Lambda execution role、操作対象を別リソースとして再構築し、図の目的上省略できる要素だけを意図的に統合する。
• 通信やAPI呼び出しの矢印をRegionやStackなどのコンテナ境界そのものへ接続しない。具体リソースをtargetにし、管理集合は包含または交差で表現する。
• クロスリージョン推論プロファイルなど、デプロイ先リージョンを越え得るサービスは単一リージョン内に閉じているように断定せず、モデル注記で明示する。
• 未実装のセキュリティ対策や本番化前の課題は構成図へ記載せず、タスク管理・セキュリティ設計など別の成果物で管理する。ユーザーが明示的に要求した場合だけ別ページまたは別資料へ分離する。

自己レビュー

• IaCにないサービスを描いていないか。
• 認証主体がトークンのsubなど実装上の値と一致するか。
• 保存先のユーザー分離キーと図の説明が一致するか。
• CloudFrontからオリジンへの認証方式と、利用者ログインを混同していないか。
• 同じAWSサービスへ別のサービスアイコンを流用していないか。
• 全AWSリソースアイコンが公式の色付き背景と白線で表示されるか。
• CloudWatchなど複数の図形名が存在するサービスは、公式パレットで現在のリソースアイコン名を確認し、draw.ioで線画が表示されるか目視する。
• draw.io内蔵図形が編集画面または書き出しPNGで塗りつぶしだけになる場合、最新版公式toolkitのSVGをdata URIとして埋め込み、再書き出しで白い線画まで確認する。
• Amazon Bedrock AgentCoreを、アイコン周辺だけの100%画像でも確認する。緑一色の矩形、glyph欠落、別のBedrockアイコンへの置換をすべて不合格にする。
• すべてのグループ境界が透明背景かつcollapsible=0で、編集画面に開閉用のマイナス・プラス記号が出ないか。
• エッジの始点から最初の中継点、最後の中継点から終点までを含め、説明カードを貫通していないか。
• 孤立したサービスがないか。意図的に矢印を省く場合は、注記でどのリソースの出力先・依存先かを明示する。
• 50%前後の全体表示で流れが分かり、75〜100%で文字切れや重なりがないか。
• 100%で書き出した固定PNGを原寸表示し、短すぎて見えない線、数pxの不要な段差、編集画面では見えなかったアイコン欠落や文字の不自然な折り返しがないか。
• PNGのcontent crop後も最外周オブジェクトと画像端に16〜24px以上の安全余白があり、境界strokeが半分クリップされていないか。
• 白塗りラベルが境界線や破線を部分的に消していないか。ラベルの矩形がサービスアイコンの角や別用途の線へ数pxでも侵入していないか。
• 固定PNGの意味の小単位ごとに、接続線が黒、境界線が非黒で局所判別できるか。矢印がアイコンの角ではなく辺へ接続し、同じ始点付近で別用途の線と共有・T字接続して見えないか。
• サービスやデプロイ部品の外形、接続ラベルがアカウント、Region、VPC、Stack、信頼境界の線へ接触・交差していないか。
• 補助線の最後に24px未満の短辺、ターゲットを通り過ぎて戻る折り返し、2px程度の不要なジョグがないか。
• 左右辺の接続点が角寄りになっていないか。同じ辺の複数線が十分に分離され、別線からの分岐に見えないか。
• サービスアイコン、サービス名、補足が同じ中心線上で中央揃えになっているか。補足カードが薄いグレー・枠線なしで、主要オブジェクトのカードと視覚的に区別できるか。
• 直線で表現できる接続に不要な折れがないか。サービス位置を動かした複数案を固定PNGで比較したか。
• 接続線同士の全組合せを走査し、共通endpointではない交差が残っていないか。targetの左右順とsourceポートの上下順を交換すれば消せる交差を残していないか。
• グループ背景を透明化した後、すべての補足カードが薄いグレーとして識別でき、文字・線・境界に埋没していないか。
• 全AWSグループ境界について、左上マーカーと境界の左上頂点が固定PNGで隙間なく一致し、XMLでも直接子の32pxマーカーがx=0;y=0か。アイコン移動後にタイトルと重なっていないか。
• 丸数字は対応する手順説明があり、線形順序で読む必要がある場合だけ使う。説明のない丸数字は置かない。
• 左上の1行タイトル以外に、外周のメタ説明、凡例、セキュリティ課題が残っていないか。
• リージョンやCDKスタックの範囲が文章ではなく、公式グループ枠とラベルで正しく表現されているか。
• 各境界について、内側の全要素がそのスコープに属し、属する要素が外側へ漏れ、属さない要素が内側へ混入していないか。グローバルサービス、クロスリージョンサービス、CDK管理対象を特に確認する。
• 各矢印について、接続元、接続先、向き、実行・認証・データ・デプロイ・ログの種別、IAM主体、プロトコルがIaCと実装に一致するか。
• 异なる線が同一の辺上座標・最初の区間・最後の区間を共有していないか。局所PNGでT字分岐に見えたら、XML上が別edgeでも不合格とする。
• AWSサービス以外も含む全工程カード、スクリプト、credentials、アセットに孤立がなく、ページタイトルのE2E開始点から終点まで追跡できるか。
• 全mxCell.styleに同一キーの重複指定がないか。align=center;align=leftや異なるdashPatternのlast-winsに依存しない。