architecture-diagram

インタラクティブなアーキテクチャ図

ワークショップの参加者、クライアント、新しいチームメンバーが、システムの仕組みをステップごとにクリックして確認できる、単一ファイルでそのまま使えるHTMLページを作成します。ノード間をアニメーション付きのデータパケットが流れ、サイドパネルにはペイロードの詳細が表示され、モード（オフライン／オンライン、開発／本番、v1／v2）を切り替えられます。見た目はダークで、まず説明のしやすさを重視します。境界のあるノード、ゆるやかな二次曲線のワイヤー、アクティブなステップでのみ光るパケットを使い、虹色のグラデーションは使いません。assets/css-tokens.css のCSSトークンでブランドを変更できます。

---

このスキルを使う場面

状況	このスキルを使いますか？
「認証フローの仕組みを見せて」（ワークショップ向けのインタラクティブな図）	はい
「構築前にRAGパイプラインを設計して」（新しいサービスの計画）	はい
「マイクロサービスとその通信方法を図示して」	はい
「オンボーディング資料用にCI/CDパイプラインを可視化して」	はい
「ETLパイプラインを通るデータフローを見せて」	はい
「ツール呼び出しを含むエージェント型マルチエージェントシステムを図示して」	はい
「チームで反復して改善できるアーキテクチャのモックアップを作って」	はい
「PR用にシーケンス図を描いて」（静的で、Markdownに含める）	いいえ — Mermaidのシーケンス図をそのまま使うほうが簡単です
「スライドデッキやPDFに図を追加して」（静的で、インタラクティブではない）	いいえ — これはインタラクティブなHTMLを生成するもので、画像やスライドではありません
「静的なボックスと矢印のトポロジー図だけが必要」（フローやステップは不要）	いいえ — Mermaidのフローチャートで十分です

このスキルの強みは、インタラクティブ性と、順序立てられたデータフローです。「クリックして動きを確認する」ことに価値があるならこのスキルを使い、静的な画像、スライド、インライン図が必要なら、代わりにMermaidを使ってください。

---

基本的な考え方

すべての図には、4つの要素があります。

1. ノード — サービス、データストア、ユーザー、キュー、外部システムなどです。それぞれに役割（色）とメタデータ（技術スタック、ポート、デプロイ先）があります。
2. フロー — ユーザーが選択できる名前付きのシナリオ（例：RAG Query、Direct Query、Ingest、Auth）です。各フローは、順序付きのステップのリストです。
3. ステップ — {from, to, color, title, route, payload, desc, chips} です。各ステップでは、1本のワイヤーと1つの対象ノードが点灯します。（color と title は必須です。color は --c-orch のようなCSS変数名にする必要があります。それ以外の場合はブランドのアクセントカラーが使われます。title がない場合は「—」が表示されます。）from === to のステップは、そのノードの上にループとして描画されます（「CI → CI: build」のような内部処理）。
4. モード — フローとは独立して切り替える項目です（オフライン／オンライン、開発／本番、v1／v2）。モードでは次のことができます。
   • ノード全体を表示／非表示にする（例：Seedはオフラインの場合のみ存在）
   • ノード名を変更する（Qdrant → BigQuery）
   • ペイロード本体、ポート、認証ヘッダー、レイテンシチップを切り替える

モードは別のフローではありません。フローはシナリオ（「ユーザーが質問をする」）を表し、モードはデプロイ形態（「Docker上」か「Cloud Run上」か）を表します。

---

呼び出されたときのワークフロー

ステップ1 — 意図を把握する

ユーザーがSOLITION.md、README、OpenAPI仕様書、またはアーキテクチャの説明をアップロードしている場合は、質問する前にまずそれを読んでください。次の情報を抽出します。

• サービス名、技術スタック、ポート
• デプロイモード（ある場合）
• 名前付きのエンドポイント／操作とその役割（これらがフローになります）
• 各操作における内部サービス呼び出しの連鎖（これらがステップになります）

その後、不足している情報だけを尋ねてください。文書にすでに記載されていることは尋ねないでください。

文書がない場合は、ユーザーに簡潔に尋ねてください。

• 「どのシステムを図にしますか？」
• 「見せたい主なフローは何ですか？（例：ログイン、検索、チェックアウト）」
• 「切り替え可能なモードはありますか？（オフライン／オンライン、開発／本番、v1／v2）」
• 「対象読者は誰ですか？ワークショップの参加者、エンジニア、クライアントのどなたですか？」

ステップ 2 — まずトポロジーを紙に書き出す

コードを書く前に、どのサービスが存在するのか、それぞれが相互にどこに位置するのか、どのノード間でどのフローがつながるのかを、紙の上で（頭の中や一時ファイルでもかまいません）スケッチします。配線の交差は避けてください。これが読みやすさを大きく向上させる最も重要なポイントです。レイアウトのヒューリスティクスについては、references/flow-design-patterns.md を参照してください。

簡単なルール：

• オーケストレーター／API ゲートウェイは中央に配置し、依存先を放射状に配置します
• ユーザーは一番左（入口）、データストアは右側（出口）、サービスはその間に配置します
• 読み取り専用サービスは上、書き込みの多いサービスは下に配置します（データが下へ流れ込むため直感的です）
• 任意のサービス／一度だけ実行するサービス（シードジョブ、cron）は隅に配置します

ステップ 3 — テンプレートを基に作成する

assets/template.html を作業ディレクトリにコピーします。これはダークテーマ、サイドパネル、プレーヤーコントロール（再生／一時停止／ステップ）、キーボードショートカット、アニメーション付き SVG パケット、モード切り替えを備えた、コピーしてすぐに使える完全なテンプレートです。編集するのは次の箇所だけです（テンプレート冒頭の EDIT THESE THINGS コメントが、編集箇所の確定リストです）。

1. <title> と <h1> — {{SYSTEM_NAME}} とヘッダーテキストを置き換えます。ポーランド語（またはその他の英語以外の言語）の図の場合は、<html lang="pl"> も設定します。
2. .modepick ボタン — モード切り替えのラベルを設定します（単一モードの場合は .modepick 全体を削除できます。パネルのバッジと O キーは自動的に対応します）。モードは 3 つ以上でもかまいません。O キーで順に切り替わります。
3. .flowtabs — シナリオごとに .flowtab を 1 つ配置します。data-flow は flows のキーと一致させる必要があります。タブの順序はキーボードの数字 1～9 に対応します。それ以外に同期が必要な項目はありません。
4. .stage 内の .node div — サービスごとに 1 つ配置します。data-id、data-role、style="left/top"、ラベル、技術、ポートを設定します。
5. JavaScript の flows オブジェクト — シナリオごとに 1 つエントリを作成し、順序付きの steps[] 配列を設定します。最初に表示するキーを state.mode／state.flow に設定します（不明なキーの場合は最初のボタンにフォールバックし、警告が記録されます）。

条件付き：役割がデフォルトと異なる場合に限り .legend を更新します。スタイルを変更する場合に限り、:root CSS 変数の色を変更します。編集後、ファイル内を検索して {{ が残っていないか確認し、{{SYSTEM_NAME}}／{{FLOW_*}} の置き忘れがないか調べます。ページは起動時にも自己検証を行い、残っているプレースホルダー、不明なノード ID、タブとフローの不一致をブラウザーコンソールに出力します（window.archValidate() は同じリストを返します）。

CSS、プレーヤー、SVG 配線レンダラー、サイドパネルを一から作り直す必要はありません。どれもそのまま動作します。

ステップ 4 — ユーザーに見せる前に検証する

生成後、次の自己チェックを行います。

• ファイルを頭の中で開いて確認します。各フローのステップ順序は、ストーリーとして自然ですか？（ステップ 1 で準備し、最後のステップでユーザーに結果を返します。）
• 配線が不必要に交差していませんか？交差している場合は、ノードの位置を調整します（後から到着する依存先を、先に到着する依存先から離してみてください）。
• 連続する 2 つのステップで、同じノードが to になっているフローはありますか？ループであれば問題ありませんが、その理由が説明に記載されていることを確認してください。
• モード切り替え：モード間で最も異なるノード（通常はデータベース）を選び、モード依存のフィールド（ラベル、技術、ポート、ペイロード、チップ）がすべて設定されていることを確認します。
• 対応する architecture.md を生成しましたか？（必須です。ステップ 6 を参照してください。）

puppeteer-core と Chrome／Chromium のバイナリが利用できる場合は、node references/screenshot.js architecture.html を実行してください。デスクトップとスマートフォンのプレビューをキャプチャし、ページ自体の整合性に関する警告を出力します。図で JavaScript エラーが発生した場合はゼロ以外の終了コードを返すため、ゼロ以外の終了コードは「表示前に HTML を修正する」ものとして扱ってください。

ステップ 5 — ファイルを出力する

常に 2 つのファイルを作成します。

• architecture.html — インタラクティブな図
• architecture.md — テキストによる説明（コンポーネント、ステップごとのフロー、モードの違い、ワークショップのシナリオ）

現在の作業ディレクトリに保存します。プラットフォームごとの上書き設定：

• Claude.ai — 代わりに /mnt/user-data/outputs/ を使用します
• Claude Code / Gemini CLI / OpenCode / Copilot CLI — 現在の作業ディレクトリに保存します（デフォルト）

どちらのファイルも単独で内容を理解できるようにします。HTML を開かなくても Markdown を読め、逆も同様です。

ステップ 6 — 出力を提示する

ファイルの保存先と開き方（macOS では open architecture.html、Linux では xdg-open architecture.html、またはブラウザーで開く）をユーザーに伝えます。present_files が利用できる場合（Claude.ai）、まず HTML を表示し、次に Markdown を表示するために呼び出します。

---

ファイル参照

ファイル	読み込むタイミング
assets/template.html	必ず読み込みます。 コピーして変更する際の出発点です。
assets/css-tokens.css	ユーザーがスタイル変更（例：ライトテーマ、異なるブランドカラー）を求めた場合に読み込みます。既存の CSS に組み込める独立したトークンです。
references/flow-design-patterns.md	システムを新規に設計する際に読み込みます。ノードの配置、フローの命名、ステップの順序付け、モード選択のためのヒューリスティックが記載されています。
references/component-library.md	ノードリストを作成する際に読み込みます。適切な役割とアイコンを備えた User/API/DB/Queue/Cache/LLM/Cron/External などのノードスニペットをコピーして使用できます。
references/screenshot.js	結果をユーザーに見せる前に確認する場合に読み込みます。puppeteer-core がインストールされていれば、node で実行します。
examples/rag-eskadra-bielik.json	参考例：5 つのフローとオフライン／オンラインモードを備えた実際の RAG システムです。トポロジーのレイアウト、オフライン／オンラインモードの設計（ノードごとの技術／ポート切り替え）、step_outline によるフローの分解を確認できます。ペイロード／チップの規則については、例ではなく以下のセクションを参照してください。
examples/auth-oauth2.json	参考例：開発／本番モードを備えた OAuth2 ＋ セッションフローです。リダイレクトフローと外部 IdP ノードを示します。
examples/event-driven.json	参考例：Kafka を使用したイベント駆動型マイクロサービスです。非同期のファンアウトフローを示します。
examples/cicd-pipeline.json	参考例：GitHub Actions を使用した CI/CD パイプラインです。ステージング／本番モードとロールバックフローを備えています。
examples/agentic-tool-calling.json	参考例：ツール呼び出しを行うエージェント型 AI システムです。単一エージェントモードとマルチエージェントモードを示します。

examples/*.json ファイルは計画仕様であり、そのまま使えるコードではありません。JSON の概要を、テンプレートの HTML ノードとインライン JavaScript の flows オブジェクトに変換します。フィールドごとの変換については、references/flow-design-patterns.md → 「Example JSON → template mapping」を参照してください。

---

クイックリファレンス — ノードの役割と色

template.html の CSS 変数にハードコードされています。ノードごとに 1 つ選びます。

役割	色	用途
user	ミント #46f9b8	ブラウザー、モバイルクライアント、エンドユーザー、CLI ユーザー
orch	スカイ #6aa9ff	API ゲートウェイ、オーケストレーター、BFF、コントローラー
compute	マゼンタ #ff6b8a	LLM、ML モデル、高コストな計算処理
embed	アンバー #ffc14d	埋め込みサービス、トランスフォーマー、プリプロセッサー
vector	バイオレット #b388ff	データベース（種類を問わず）、ベクトルストア、キャッシュ、BLOB ストレージ
seed	オレンジ #ff9457	Cron、単発ジョブ、マイグレーション、シード、スケジュール済みタスク

役割を追加する必要がある場合は、CSS 変数を追加してください。種類は 6 以下にしてください。それを超えると、凡例が色覚に配慮できないほど複雑になります。

たとえば、システムに異なるデータストア（Postgres と Redis）が 2 つある場合も、両方に vector を使用し、7 つ目の色を追加するのではなく、アイコンとラベルで区別します。

---

ビジュアル状態 — 各ステップで閲覧者に表示される内容

これは図の最も重要な学習メカニズムです。JS や CSS を変更する前に理解してください。そうしないと、「フロータブをクリックすると、経路全体が表示される」という直感的な操作性が損なわれます。

ユーザーがフロータブを選択してステップ N に進むと、すべてのノードとワイヤーは次のいずれかの状態に分類されます。

要素	状態	表示	条件
ノード	active	完全なリング＋グロー＋ステップ番号バッジ	現在のステップの対象（例：「Orch → LLM」というステップの LLM）
ノード	active-from	ソフトなリング、バッジなし	現在のステップの送信元
ノード	participant	不透明度はほぼ通常どおりで、彩度が少し低い	このフローのどこかには登場するが、現在のステップには登場しない
ノード	dimmed	不透明度 25％で、色あせた表示	このフローには一切登場しない（例：login フロー中の seed）
ノード	hidden	非表示	モードによって完全に除外される（例：オンラインモードの seed ノード）
ワイヤー	active	明るいロールカラー、グロー、パケットがアニメーション表示	現在のステップのワイヤー
ワイヤー	preview	ロールカラーで不透明度 50％、破線	このフローに属するが、アクティブなステップではない — この先の経路全体を表示します
ワイヤー	muted	不透明度約 8％	このフローに属さない

participant が重要な理由（および JS/CSS 実装上の注意点）については、references/flow-design-patterns.md →「The participant state」で詳しく説明しています。要点は、フローで使われるノードを確認するためにステップを進めるのではなく、最初のクリックで経路全体を閲覧者に見せられることです。これこそが図の目的です。ノードの状態を追加する場合は、applyStep と CSS（.node.participant、.wire.preview）の整合性を保ってください。

---

インタラクションモデル

この図では、閲覧者の習熟度が高まる順に、5 通りの操作ができます。

操作	動作	利用者
フロータブをクリック	そのフローで再生可能な最初のステップに移動し、サイドパネルを更新します	すべての閲覧者
Next/Prev をクリック（または →/←、Space）	ステップを 1 つ進める／戻す。最後に Play を押すとフローが最初から再生されます	ステップを追いながら学ぶワークショップ参加者
ノードをクリック	そのノードが登場する最初のステップに移動します	興味のある箇所を探る閲覧者
ノードをドラッグ（マウス／ペン）、またはフォーカスしたノードで Shift+矢印キー	キャンバス上でノードの位置を変更します。ワイヤーはリアルタイムで再描画され、レイアウトはブラウザーごとに保存されます	レイアウトを調整する人／プレゼンター
全画面表示（F）	キャンバスが画面全体に表示され、コントロールバーが上部に、フロータブが下部に、サイドパネルがオーバーレイとして表示されます。Escape または同じボタンで終了します	ワークショップのプレゼンター

ノードのクリックとドラッグ。 移動量が 5px に達したかどうかで、クリック（ステップに移動）とドラッグ（位置を変更）を区別します。タッチ画面ではノードはタップで移動するだけなので、ノード上をスワイプしてもページのスクロールを妨げません。

スキルの変更時に見落としやすいのが、ノードのクリック操作です。 次の 3 つがすべて必要です。

1. .node に cursor: pointer を指定する（クリック可能であることを視覚的に示します）
2. ロールカラーを表示する :hover 状態（操作できることを示します）
3. 現在のフローのステップに対して findIndex を実行し、そのステップに移動する JS ハンドラー

現在のフローに属さないノード（.dimmed 状態）をクリックすると、何も起こらないのではなく、ノードが揺れます。何も反応しないのは UX として望ましくありません。閲覧者はページが壊れていると思ってしまいます。

キーボードアクセシビリティ：ノードには tabIndex=0 が設定されており、Enter/Space キーでクリックと同じ動作を実行します。Shift+矢印キーを使うと、ノードをグリッド 1 セル分移動できます。ステップの変更はライブリージョンを通じて通知されます。タブの下にある「shortcuts on」リンクから、単一キーのショートカットを無効にできます（WCAG 2.1.4）。

機能追加時にこれを壊さないでください。 これがあれば、閲覧者が「ちょっと待って、LLM はどこで使われているのか」と思ったときに、すぐに見つけられます。これがなければ、ノードの役割を知るだけでも 8 つのステップをすべて進める必要があります。

クイックリファレンス — ペイロード形式

サイドパネルのペイロードは、等幅フォントと最小限の構文ハイライトで表示されます。現実的でありながら簡潔にしてください。形式を示し、不要なフィールドは省きます。

{
  payloadOffline:
`POST /ask
{
  "query": "Ile kosztuje parking?",
  "limit": 3,
  "temperature": 0.7
}`
  // avoid: full HTTP headers, User-Agent, 50-line bodies — show only the shape
}

インデントにはスペースを4つ使い、タブは使わないでください。インライン注釈には // comments を使います。

両方のモードで手順が同じ場合は、payload（キーは1つ）を使います。異なる場合は、payloadOffline + payloadOnline（またはモード名に応じて、payload + 先頭を大文字にしたモードキー。たとえば、モードが prod なら payloadProd）を使います。両方が存在する場合は、モード固有のキーが優先されます。「汎用ペイロードを用意し、1つのモードで上書きする」ときに便利です。chips / chipsOffline も同じルールです。文字列ではなくオブジェクトを指定すると、JSON として整形表示されます。

desc で使用できるのはインライン HTML のみです：<em>、<strong>、<code>、<kbd>、<br>、<a href="https://…">。それ以外はレンダリング時に削除されます（ブロックタグはタグが取り除かれ、中身は残り、スクリプトと iframe は削除されます）。説明は1〜3文に収めてください。

---

クイックリファレンス — チップ（メタデータバッジ）

ペイロードの下に表示されるチップは、短いメタデータラベルです。次の2つの意味的なタイプは、自動的にスタイルが適用されます：

• レイテンシ（/\d+\s*(?:ms|s|min)\b/ に一致） — ストップウォッチアイコンが付きます。例："~150ms"、"5-30s"、"timeout 120s"
• サイズ／件数（/dim|×|loaded|rules|count/ に一致） — データベースアイコンが付きます。例："768 dim"、"38 loaded"、"×N"
• その他 — ニュートラルなスタイルです。例："COSINE"、"baseline"、"idempotent"、"UUID5"

手順ごとのチップは最大3つです。チップは仕様ではなく、参考情報です。

---

命名規則

対象	規則	例
JS のフローキー	snake_case	ask、ask_direct、ingest_text
フローの表示名	"Title Case (METHOD /route)"	"RAG Query (POST /ask)"
ノードの data-id	短い snake_case	orch、vector、embed
モードキー	説明的な snake_case	offline/online、dev/prod、v1/v2
手順のタイトル	ワークショップの言語に応じて、ポーランド語または英語。1つのファイル内では統一します。	"Pytanie z UI" または "Question from UI"

よくある落とし穴

文字列内の </script> はすべてを壊します。 ペイロード、説明、タイトル、チップに </script> という文字列が含まれている場合（HTML スニペットを表示する場合など）、ブラウザーの HTML パーサーはこれをメインの <script> ブロックの終了タグとして扱い、すべての JavaScript が停止します。テンプレートリテラル内では <\/script> または </script> にエスケープしてください。これは </style> など、同様の終了タグにも当てはまります。

ページ自身が lint を実行します。 ブラウザーのコンソールを開くか（または references/screenshot.js を実行すると）、ステップ内の不明なノード ID、flows エントリがないフロータブ（およびその逆）、不明な onlyMode / data-modes の値、title / color の不足、残った {{PLACEHOLDERS}} が警告として表示されます。コンソールに警告がないことも「完了」の一部です。

コンテンツセキュリティポリシー。 テンプレートには、インラインのスクリプトとスタイル、および Google Fonts のみを許可する CSP <meta> が含まれています。ユーザーが外部の画像、スクリプト、フォントを求めた場合は、該当するディレクティブを拡張してください。そうしないと、コンソールにリクエストがブロックされたと表示されます。

ソースノードが機能していないように見える。 ステップのソースノードが active-from ではなく dimmed として描画される場合は、参加者のロジックを後退させています。「Visual states」を参照してください。

ワイヤーの交差。 これはコードではなく、ノードの配置が原因です。ノードの位置を入れ替えて修正してください。（テンプレートはステップのインデックスに応じてワイヤーを交互の方向に自動でカーブさせます。これは役立ちますが、レイアウトの問題までは解決できません。）

フローが多すぎる。 フローが 6 個を超えると、タブバーが煩雑になります。8 個以上ある場合はグループ化してください。グループごとに 1 つの図を作成します（例：「読み取りフロー」と「書き込みフロー」を別々の HTML ファイルにします）。

本当はモードではないモード。 切り替えによってトポロジー全体（異なるサービスやプロトコル）が変わる場合、それはモードではなく、別のシステムです。HTML ファイルを 2 つ作成してください。

静的なスクリーンショットのほうが、ライブ図より適していることもあります。 図を PDF レポート、スライド資料、印刷用の配布資料に掲載する場合、このスキルは適していません。代わりに静的な図を作成してください。このスキルは、ブラウザーでのインタラクティブな閲覧を目的としています。

.md を忘れないでください。 HTML は見せ場ですが、GitHub で読まれ、Slack に貼り付けられ、エンドポイント名の検索に使われるのは .md です。必ず両方を生成してください。

ポーランド語と英語。 ワークショップで使う言語に合わせてください。バイリンガルの環境では、通常、社内ワークショップにはポーランド語、クライアント向けの成果物には英語を使います。不明な場合は確認してください。

---

テンプレートの拡張

ユーザーからテンプレートで対応できない内容を求められた場合の難易度は、次のとおりです。

リクエスト	難易度	編集箇所
新しいノード	簡単	.node div を追加し、left/top % で配置します
新しいフロー	簡単	flows オブジェクトに項目を追加します
ブランドカラーの変更	少し	:root の CSS 変数を編集します（assets/css-tokens.css を参照）
ライトテーマ	組み込み済み	月／太陽ボタンをクリックするか、T を押します。ライトテーマをデフォルトにするには、<body> に class="light" を追加します。
ノードのドラッグ＆ドロップ	組み込み済み	すでに対応しています。任意のノードをドラッグする（マウス／ペン）か、フォーカスしたノードを Shift+矢印キーで移動します。位置は 48px の格子にスナップし、localStorage に保存されます（ページタイトルとノード ID のセットをキーにします。図ごとに固有のタイトルを付けてください）。
全画面モード	組み込み済み	F を押すか、拡大アイコンをクリックします。コントロールバー、フロータブ、サイドパネルには引き続きアクセスできます。Escape を押すかボタンをクリックすると終了します。
自己ステップ（内部処理）	組み込み済み	from === to のステップは、ノードの上にループを描画します。
3 つ以上のモード	少し	.modepick にボタンを追加し、payload<Mode>／chips<Mode>／data-*-<mode> フィールドを追加します。O を押すと、すべてのモードが自動的に切り替わります。
レイアウトのリセット	組み込み済み	R を押すか、↻ ボタンをクリックします（ドラッグ後に表示されます）。
進捗バー	組み込み済み	プレイヤーの下に細いバーが表示され、現在のフロー内のステップ位置を示します。
フローの注記行	組み込み済み	フローに note を設定します（onlyMode フローには onlineNote を設定します）。注記はプレイヤーの下に表示されます。
モーションの軽減	組み込み済み	prefers-reduced-motion に従います。飛んでいくパケットは非表示になり、トランジションは簡略化されます。
並列ステップ（同時に動く 2 本のワイヤー）	中程度	ステップを {parallel: [step, step]} としてグループ化します。プレイヤーは両方を進めます。
分岐フロー（if-then-else）	難しい	現在は直線的なフローのみです。フローを別々に分岐するか、分岐を選択する UI と branch フィールドを追加します。
URL への状態保存	少し	ハッシュベースです。#mode=online&flow=ask&step=3 — 起動時に解析し、変更時に更新します。

テンプレートで対応できない機能については、必要な作業を明示せずに対応を約束しないでください。

---

反復時のヒント

ユーザーから「図が窮屈すぎる」や「ステップ 5 がわかりにくい」といったフィードバックがあった場合：

• 「窮屈すぎる」 → ノードの間隔を広げます。使える幅は 100% です。隣接するノード間の水平方向の間隔は 12% 未満にしないでください。
• 「ステップがわかりにくい」 → ステップの説明に詰め込みすぎています。2 つのステップに分けるか、1 つの受け渡し（X が Y を Z に送る、それだけ）に焦点を当てて書き直します。
• 「実際の動作と違う」 → 実際のコードパスを尋ねます。推測してはいけません。実態と異なる図には価値がありません。
• 「もっと目立たせて」 → 控えてください。視覚的なインパクトより、学習しやすさを優先します。結果ノードにフロー完了時のグローを付けるなど、アクセントを 1 つ加える程度にとどめます。
• 「凡例を追加して」 → すでにあります。大きくしたい場合は、.legend のフォントサイズと間隔を大きくします。