Community画像github.com

excalidraw-architecture

ソフトウェアアーキテクチャ、メッセージフロー、イベント駆動型システム、マイクロサービスをExcalidrawで図示する際に使用します。Enterprise Integration Patterns(EIP)記法で.excalidrawファイルを生成します。

excalidraw-architecture とは?

このスキルは、ソフトウェアアーキテクチャやメッセージングシステムをExcalidraw形式の図として生成するためのツールです。Hohpe & WoolfのEnterprise Integration Patterns(EIP)記法に基づき、ノード、エッジ、グループからなる小さなJSONスペックから、.excalidrawファイルとプレビュー用SVGを自動生成します。Claude Code、Cursor、CodexなどのAIエージェント上で動作し、インベントリ作成、図のレベル選択(コンテキスト、フロー、エンドポイント)、スペック記述、ビルド、レビュー、修正という一連のワークフローを提供します。チャネルの種類(P2P、Pub-Sub)、メッセージの種類(コマンド、イベント、ドキュメント)、エンドポイントの役割(ゲートウェイ、アウトボックス、コンシューマ)、ルーティングや変換のパターン、デッドレターチャネル(DLQ)や補正IDなどの重要な設計要素を明示的に図示するためのルールが組み込まれており、アーキテクチャレビューやドキュメント作成に適しています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jamescarr/diagram-skill/tree/HEAD/skills/excalidraw-architecture

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Excalidraw アーキテクチャ図 (EIP 記法)

図は小さな JSON スペック(ノード、エッジ、グループ)と、それを Hohpe & Woolf 記法でレイアウトするジェネレータで構成されます。スペックが真実の源泉であり、.excalidraw ファイルとプレビュー .svg はビルド成果物です。

<skill-dir> は、このスキルがインストールされているディレクトリです(例: ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture、.agents/skills/excalidraw-architecture、または https://github.com/jamescarr/diagram-skill リポジトリ内の skills/excalidraw-architecture)。

使用するタイミング

  • サービス、イベント、メッセージングアーキテクチャの図示、描画、スケッチ、可視化を依頼された場合。
  • メッセージの経路(どのチャネル、どのエンドポイント、失敗時に何が起こるか)を説明する場合。
  • 境界付けられたコンテキストの統合面をコンテキスト、フロー、エンドポイントレベルで文書化する場合。
  • メッセージ指向の設計をレビューし、図が欠落している DLQ、相関 ID、または冪等性を明らかにする必要がある場合。

使用しないタイミング

  • UI モックアップ、ワイヤーフレーム、スライドデッキ、自由形式のホワイトボーディング。
  • 単一プロセス内の呼び出しのシーケンス図。
  • 成果物が .excalidraw ファイルではないもの。

ワークフロー

  1. インベントリ — 描画前に以下をリストアップ:

    • 参加者: サービス、外部システム、アクター、ストア;
    • チャネル: 名前、ポイントツーポイント vs パブリッシュ-サブスクライブ、キー/パーティション/順序付け、持続性、DLQ;
    • メッセージ: 名前(コマンド = 命令形、イベント = 過去形、ドキュメント = 名詞)とタイプ;
    • サービスごとのエンドポイント: ゲートウェイ、アウトボックス/トランザクション、コンシューマスタイル、競合数、冪等性、持続性、選択性;
    • ルーティングと変換ステップ;
    • リクエスト-リプライペア: リプライチャネル、相関、TTL;
    • 管理: ワイヤータップ、ストア、コントロールバス。 パターンの選択が不明な場合は、インストールされていれば enterprise-integration-patterns スキルを読んでください。
  2. レベルを選択 — context: アクター、サービス、外部システム、ブローカーは message-bus、rpc/data エッジ。flow(デフォルト): チャネルと EIP コンポーネントを含む、エンドツーエンドの1つのビジネスフロー。endpoint: 1つのサービス内部 — ゲートウェイ→アウトボックス→チャネル、またはコンシューマ→冪等レシーバ→アクティベータ。図1つにつき1フロー、最大20ノード。それ以外の場合はフローごとに分割。

  3. スペックを記述 — 図を配置する場所(デフォルトは docs/architecture/)に <name>.spec.json を作成し、以下のチートシートを使用します。node <skill-dir>/scripts/eip_excalidraw.mjs kinds を実行すると、ライブカタログが表示されます。

  4. ビルド — node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json を実行すると、<name>.excalidraw と <name>.svg が作成されます。すべての error:(終了コード 2)を修正し、warning: はレイアウトの欠陥として扱います(--strict を指定すると警告も終了コード 1 になります)。--check は検証とレイアウトのみ行い、ファイルは書き出しません。 --png [OUT.png] を追加すると、Excalidraw 自身によってレンダリングされた PNG もエクスポートします(手描きスタイル、Excalifont フォント、シーンがファイルに埋め込まれているため、再度 excalidraw.com にドロップ可能)。これは README、ドキュメント、ブログ記事に埋め込むのに適しています。Chrome または Chromium(CHROME でパスを上書き可能)と esm.sh へのネットワークアクセスが必要です。ブラウザは scripts/export_png.mjs によって駆動されます。エクスポートに失敗した場合は終了コード 3 で終了しますが、シーンは依然として書き込まれます。

  5. 確認 — PNG をビルドした場合は read <name>.png、それ以外の場合は read <name>.svg:img を実行し、レビューリストに従って確認します。

  6. 修正 — スペックを変更するたびに再ビルド:

    症状スペックの変更
    矢印がノードを横切るroute: "ortho" または "below"、あるいは row を固定
    ラベルがノードと重なるmessage/label を短縮するか、ノードの row を矢印から遠ざけるように固定
    矢じりが縮むその列のギャップに矢印が集中しすぎている: ルートを below/above にするか、row を固定して縦の共有数を減らす
    逆向きの矢印が乱雑route: "above"
    リプライ矢印が図全体の下をループするroute: "ortho"、またはリプライチャネルをリクエストチャネルの隣に配置
    列が混雑lanes を追加するか、図を分割
    ノードラベルが長い詳細を sub に移動
    グループメンバーが分散メンバーが隣接するように col/row を固定
    フレームが非メンバーを含むグループのメンバーが連続したブロックを形成するように col/row を固定するか、lanes を使用
  7. 成果物として提供 — .spec.json、.excalidraw、.svg(PNG をビルドした場合はそれも含む)。スペックが真実の源泉であると明記し、編集後は再生成すること。Excalidraw での手動編集は後で行っても問題ありませんが、再ビルドすると上書きされます。

モデリングルール

各ルールは図が可視化すべき主張です; それが真実でない場合、例外を明示的に描画します。

  • すべてのチャネルは、その種別タグとキー/パーティション/順序付けタグ(tags)を表示する。
  • アットリーストワンス(at-least-once)チャネルのすべてのコンシューマは idempotent を付けるか、図にその理由を記載する。バッジはアプリファミリーノードにのみ存在するため、サガ、ルーター、アグリゲーターは sub に重複排除ルール(dedupe by orderId)を記述する。
  • コンシューマが失敗する可能性のあるすべてのチャネルには dead-letter-channel shadow がある; バリデーション失敗には invalid-message-channel を設ける。描画されていない、または意図的に欠落している DLQ は、チャネルの sub または note に記載する。
  • リクエスト-リプライ = reply_to と correlation を持つコマンドエッジと、破線のリプライエッジ。
  • アグリゲーター、スキャッター-ギャザー、サガノードには、完了ルール(カウント/タイムアウト)を示す sub を付ける。
  • トランザクション内でのパブリッシュ = outbox バッジまたは outbox ノード。コミット後にベアでパブリッシュしてはならない。
  • トランスレーターは境界付けられたコンテキストの境界(フレーム)上に配置する。
  • 競合コンシューマは competing:N と表示し、持続的サブスクリプションは durable を付ける。
  • ワイヤータップは message-store への tap エッジである。
  • スマートエンドポイント、ダムパイプ: ルーティングロジックはルーターノードに配置し、チャネル内に暗黙的に含めてはならない。
  • 同期呼び出しは rpc エッジであり、デフォルトではなく例外である。
  • 境界を越える内部レコードには content-filter または claim-check 参照を付ける。

スペックチートシート

EIP 章ごとのノード — 完全な種類別テーブルは references/spec.md にあります:

章種類使用するタイミング
チャネルchannel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-busメッセージが参加者間を移動する; P2P か Pub-Sub を選択し、次に障害チャネルを選択。
メッセージmessage command-message document-message event-messageメッセージ自体が主題であり、エンドポイントではない。
ルーティングcontent-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga1つのメッセージに複数の宛先がある、または再構成する必要のある部分がある。
変換message-translator envelope-wrapper content-enricher content-filter claim-check normalizerペイロードまたはそのエンベロープがホップ間で変化する。
エンドポイントmessage-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapterサービスがチャネルに接続し、それを消費する方法。
システム管理wire-tap detour message-history smart-proxy test-message channel-purger可観測性、プローブ、運用。
インフラストラクチャmessage-broker messaging-bridge outbox inboxブローカー自体、ブローカー間リンク、トランザクショナルパブリッシュ/コンシューム。
参加者とストアservice external-system actor datastore message-store schema-registry noteチャネルエンドの所有者; 状態、スキーマ、アノテーションの保存場所。

バッジ(アプリファミリーノードのみ; ピルは短いテキストをレンダリング):

グループバッジ
エンドポイントgateway (Messaging Gateway)、mapper (Messaging Mapper)、activator (Service Activator)、adapter (Channel Adapter)
消費polling (Polling Consumer)、event-driven (Event-Driven Consumer)、competing / competing:N (Competing Consumers、最大3つのボックススタックに competing ×N と表示)、dispatcher (Message Dispatcher)、selective (Selective Consumer)、durable (Durable Subscriber)
トランザクションtx (Transactional Client)、outbox (Transactional Outbox)、inbox (Transactional Inbox)、idempotent (Idempotent Receiver)
耐障害性bulkhead、retry、circuit-breaker — 耐障害性パターン (EIP ではない)

エッジ:

エッジの種類線種幅矢印の先端マーカー
message (タイプなし)実線 #1e1e1e2→ arrowなし
message type: command実線2→ triangle«C»
message type: event実線2→ arrow«E»
message type: document実線2→ arrow«D»
message type: reply破線2→ arrow«R»
rpc実線1→ arrowなし
data点線1→ arrowなし
tap点線1circle → arrowなし
dlq破線 #c92a2a1→ arrowなし
control破線 #868e961┤ barなし

エッジフィールド: from、to、kind、type、message、label、seq、route、correlation、reply_to、ttl、sequence、style、color。ノードフィールド: id、kind、label、sub、badges、tags、group、lane、col、row、shadow、attach、link。

レビューチェックリスト

  • タイトルが存在し、システム全体ではなくフローに名前を付けている。
  • すべての矢印にメッセージまたは呼び出しのラベルが付いている。
  • すべてのチャネルに、その種類タグとキー/パーティションタグが付いている。
  • すべてのチャネルについて DLQ の決定が可視化されている。
  • 6種類以上の種類が出現する場合、凡例が存在する。
  • ビルドからの warning: が残っていない。
  • グループフレームはメンバーのみを含んでいる。
  • 最大20ノード。

スタックマッピング

スタック描画方法
Kafka トピックpubsub-channel; コンシューマグループ → competing:N; 持続的サブスクリプション → durable
RabbitMQ キューp2p-channel; エクスチェンジ → message-broker または content-based-router; DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
EventBridge ルールcontent-based-router
Step Functionsprocess-manager または saga
Lambda コンシューマservice with event-driven
データベースdatastore; 監査/リプレイコピー → message-store
パートナー APIexternal-system、破線

手動編集

references/excalidraw-format.md には、手動編集後も Excalidraw のバインディング、テキスト、フレームを有効に保つための JSON 不変条件がリストされています。

関連スキル