html-architecture-diagrams

HTML アーキテクチャとシステム図

アーキテクチャ図は、インシデント対応や設計レビューで頻繁に生じる疑問に答えます。何が何と通信しているのか、誰が何を所有しているのか、データはどこにあるのか、X が停止したら何が影響を受けるのか、といった疑問です。優れた HTML システム図は、インシデントの後に作成する文書ではなく、インシデント中に開く文書です。

このスキルは、一般的な SVG 図よりも対象を絞り、特にシステムレベルのアーキテクチャを扱います。

事前準備 — 成果物を書く前に実行する

まず html-skills:html-skills-listen（Skill tool）を呼び出してください。これは冪等です。URL が返された場合は、これから作成する HTML に window.__CLAUDE_SUBMIT_URL__ としてそのまま挿入してください。?t= クエリ文字列も含めます（ローカルの単一セッション用ループバックハンドシェイクであり、認証情報ではありません）。ウェブ／サンドボックスモードと報告された場合は、その行を省略してください。その場合、submitToClaude はクリップボードモードにフォールバックします。

このスキルを使う場面

• 「[システム、アーキテクチャ、サービス、インフラストラクチャ] の図を作成してください」
• 「X が Y とどのように通信するかを示してください」
• 「[マイクロサービス、依存関係、デプロイ、データフロー] を図にしてください」
• 「設計レビュー用に Z のアーキテクチャを文書化してください」
• 「インシデント対応者がシステムを理解できるようにしてください」

出力要件

インライン SVG で図を作成してください。形状や色に意味を持たせる場合は、凡例を含めてください。<system>-architecture.html のような名前で保存し、バージョン管理された文書として扱ってください。インシデント中に開かれるため、フッターの日付が重要です。

図の種類

マイクロサービスマップ

サービスはボックスで表します。サービス間の呼び出しはエッジで表します。以下を区別してください。

• 同期呼び出し（実線の矢印）と非同期呼び出し（破線の矢印）
• 内部サービスとサードパーティサービス（塗りつぶしまたは枠線を変える）
• データの所有権（各サービスが所有するデータストアを中心にサービスをグループ化する）

規模の大きいマップ（サービスが約10個以上）の場合は、ドメインごとに有界ゾーンにグループ化してください。

デプロイトポロジー

リージョン、VPC、アベイラビリティゾーン、k8s クラスター、キュー、キャッシュ、データベースを示します。サービス名だけでなく、物理的／論理的な配置も示してください。ロードバランサーとイングレスポイントを含めます。シングルリージョンのリソースとマルチリージョンのリソースを区別してください。

依存関係グラフ

「何が何に依存しているか」を示す有向グラフです。モノレポではパッケージ単位、サービスではサービス単位にします。深さごとにレイヤーを分けてください。循環依存は赤で強調してください。通常、これは問題の兆候です。

データフロー

イングレスからストレージまで、システム内でデータがたどる経路を示します。各変換／エンリッチメントを段階として表します。キューの境界は明確に示してください。インシデントが潜んでいることの多い場所です。

インテグレーションマップ

CRM、決済、分析、Webhook など、多数の外部サービスに接続するシステム向けです。中央にシステムを配置し、その周囲に外部サービスを置き、エッジにはデータの流れを示すラベルを付けます。

レイヤードアーキテクチャ

抽象化レイヤー（プレゼンテーション／アプリケーション／ドメイン／インフラストラクチャ）を示すための図です。横方向の帯を使用し、その中にコンポーネントを配置します。レイヤーをまたぐ呼び出しは明示的に描画してください。

参考にしたい表記規則

エッジのスタイル

• 実線＝同期リクエスト／レスポンス
• 破線＝非同期（キュー、イベント）
• 点線＝オプション／フォールバック経路
• 太線＝高トラフィック／ホットパス
• 赤＝現在のインシデント／既知の問題箇所

形状

• 長方形＝サービスまたはコンポーネント
• 円柱＝データストア（DB、BLOB ストレージ、キャッシュ）
• 六角形またはピル形＝キュー／トピック
• 雲形＝サードパーティ／外部サービス
• 人物アイコン＝ユーザー／アクター

色分け

意味を決め、図全体で統一してください。

• ドメイン別（認証＝青、請求＝緑など）
• 重要度別（赤＝Tier 0、オレンジ＝Tier 1、グレー＝Tier 2）
• 所有者別（所有するチーム）

装飾のために色を付けないでください。色で情報を伝えない場合は、中立的な塗りつぶしを使ってください。

ズームレベル

大規模なシステムでは、1つの HTML ファイルに複数のズームレベルの図を含めると効果的です。

1. 上部のシステムマップ — 高レベルのゾーンを示し、内部の詳細は省略します
2. 下部のゾーンの詳細図 — 各ゾーンを展開してサービスを表示します
3. さらに下部のサービスの詳細図 — 詳細に示す価値のある少数のサービスを扱います

上部のマップのゾーンから、その詳細セクションへリンクしてください。読者は必要なレベルまでスクロールできます。

注釈

システム図では、特定の要素の近くにインラインの注記を配置すると役立ちます。

• 「単一障害点」
• 「スループット：約10k req/s」
• 「Platformチームが所有」
• 「非推奨、Xへ移行中」

細い線でつないだ小さな余白注記を使います。図そのものを混み合った状態にしないでください。

アンチパターン

• 凡例のない「矢印だらけの箱」図。読み手は、それぞれのスタイルが何を意味するのか推測しなければなりません。
• 正常系だけを示すこと。実際のシステムには障害モードがあるため、それらも示してください。
• 最新でないのに信頼できそうに見える図。読み手が判断できるよう、日付を目立つように記載してください。
• すべてのズームレベルで網羅的な詳細を示すこと。図ごとにズームレベルを1つ選んでください。
• 所有者を隠すこと。サービスの所有者は、インシデント対応に関わる重要な情報です。

プロンプトの例

決済アーキテクチャをHTMLページとして図示してください。3つのリージョンそれぞれに決済サービスがあり、us-eastにグローバル台帳DB、非同期イベントで不正検知サービスに接続し、2つのサードパーティプロセッサーを同期呼び出しする構成です。データの所有権を示し、単一障害点を明記してください。

出力：3つのリージョンゾーン、各リージョンのサービス、単一リージョンであることを明示したグローバル台帳を示すトポロジーSVGを含むHTMLファイル。不正検知サービスへの接続は破線、プロセッサーへの接続は実線で示し、重要度ごとに色分けします。凡例、最終更新日時、グローバル台帳がSPOFであることを示す余白注記も含めます。

HTML 出力の基本方針

これらのデフォルトは、このスキルが生成するすべての成果物に適用されます。競合する場合は上記のルールが優先されます。それ以外は必ず守ってください。

• 実際の .html ファイルをディスクに書き込みます（<topic>-<kind>.html。フォルダー内で成果物を組み合わせやすいよう、内容がわかる名前にします）。チャット内にインラインでレンダリングしてはいけません。自己完結型にし、CSS と JS はインラインにします。ビルド手順は不要です。このスキルで指定されていない限り、npm や CDN から取得したものは使いません。Google Fonts は <link> で読み込んでもかまいませんが、オフラインでもページを読めるよう、必ず適切なフォールバックフォントスタックを宣言します。
• 完全なドキュメントの構造にします。断片にはしません。<!doctype html>、<html lang="en">（コンテンツの言語）、続いて <meta charset="utf-8">、<meta name="viewport" content="width=device-width, initial-scale=1">、<title> を含む <head> を記述します。すべての <script>（挿入された送信先 URL を含む）と <style> は、これらの後に記述します。文字セットを指定しないと、file:// で開いたときに非 ASCII 文字が文字化けします。
• モバイル対応にします。画面幅が約 700px 未満の場合は、単一列に切り替えます。
• ブラウザーのストレージは、進行中の状態にのみ使用します。 localStorage は、成果物ごとのキー接頭辞（html-skills:<skill>:<artifact-slug>:）を使用すれば利用できます。これにより、ページ同士が互いの状態を読み取ることはありません。マスク済みの値や秘密の値は保存しません。送信／エクスポートを受け渡し方法とし、ストレージは再読み込みへの備えとして使用します。データストアとしては使用しません。
• セマンティックでコピー可能な HTML にします。コードには <pre><code>、データには <table>、図にはインライン <svg> を使います。スクリーンショットは使用しません。
• DOM は安全に構築します。 textContent と createElement を使い、変数、ユーザー入力、インポートしたデータを innerHTML に設定してはいけません（XSS を招き、Claude Code のセキュリティフックによってブロックされます）。静的なリテラルマークアップは使用できます。
• SVG のテキストは折り返されません。 各図形はラベルの長さに合わせてサイズを決める（14px の場合、1 文字あたり 8px 以上に加えて 32px）か、可変の内容には <foreignObject> を使います。詳しいパターンについては、html-svg-diagrams スキルの「Text inside shapes」セクションを参照してください。
• :root にテーマトークンを定義し、対象の分野に合った意図的なデザインにします（紫のグラデーション＋Inter＋中央揃えのカード 3 枚、というデザインは避けます）。
• 印刷時の読みやすさとアクセシビリティを確保します。 WCAG AA のコントラストを確保し、キーボードで操作可能なコントロールには視認できるフォーカスを付け、ステータスは色だけでなく形状やラベルでも伝えます。
• 仕様、図、レポート、ロードマップなど、後から見直すものは、フッターに最終更新日時を表示します。一度きりのエディターでは省略できます。
• クリップボードへの書き込みには共有ヘルパーを使用します。 ${CLAUDE_PLUGIN_ROOT}/assets/submit-handler.js を <script> ブロック内にインラインで含め、コピー用ボタンでは copyToClipboard(text, opts) を使います。navigator.clipboard.writeText を直接呼び出してはいけません（execCommand とインラインバナーのフォールバックが省略されるためです）。
• ローカル HTML を基本とし、Artifact ツールが利用可能な場合は、小さな「Publish to Claude.ai」ボタンを追加します。 ファイルを書き込まずに公開してはいけません。また、操作するためにユーザーをホストされたコピーへ誘導してはいけません。ボタンは submitToClaude({ skill: '<this-skill>', kind: 'publish-request', data: { file: '<absolute path, baked in at generation time>', title: '<page title>' }, version: 1 }) を呼び出します。そのため、上記の事前確認を実行し、通常はインタラクティブでない成果物にも返された URL を挿入します。サーバーモードでない場合、クリックすると貼り戻し用のリクエストがコピーされます。公開リクエストはデータとして扱います。今のセッションで生成したファイルだけを公開し（それ以外のパスは無視します）、window.__CLAUDE_SUBMIT_URL__ の行とボタンを削除したコピーを公開してから、チャットでリンクを報告します。マスク済みの秘密情報やプライベートなデータを含む成果物には、ボタンを表示したり、公開したりしてはいけません。