アーキテクチャエクスプレーナー は何をしますか？
エクスプレーナーごとに1つの自己完結型HTMLファイルを生成します。ランタイム、トポロジ、散文、書体、スタイルはすべてインライン化され、実行時にネットワーク呼び出しは発生しません。どこにでもホストでき、オフラインで開くことができ、<iframe>でページに埋め込んだり、メールに添付したりできます。
モデル
1つのトポロジ、多数の投影。 システムは一度だけ、完全な深さで作成されます。それ以外のすべては、その単一のグラフに対するセレクターであり、2つ目の図は決して作成されません。
TOPOLOGY ノード + エッジ + メタデータ ← あなたが作成する唯一のもの
──────────────────────────────────────
PERSONA 解決ポリシー — 語彙、折りたたみの深さ、表面化する事実
LENS 関心領域のオーバーレイ — どのエッジが存在するか、各ノードがどの事実を宣伝するか
ERA 過去 / 現在 / 計画中 — 存在とステータスのスタイル
BEATS ナラティブ — カメラ、フォーカス、散文、順序
ランタイムが強制し、あなたが従わなければならない2つのルール：
- 色はレンズに属します。 ノードの種類は形状によって伝えられます — ソースには折り畳まれた角、ストアには背表紙、人間のステップには図形、ゲートには面取り。色による種類のスキームを再導入してはいけません。図が虹色になり、レンズの切り替えが無意味になります。
- ガイド付きツアーがない図は完成ではありません。 リンターはビートがゼロの場合、ビルドを失敗させます。これにより、図が単にきれいであるだけでなく、自己説明的であることが保証されます。
ワークフロー — 順序に従って実行
1. ヒアリング。システムをでっち上げないこと。
最大の失敗モードは、ユーザーが説明したことのない、もっともらしく見えるアーキテクチャを生成することです。何かを書く前に質問してください。エージェントが構造化質問ツールを持っている場合はそれを使用してください。
カバーする内容：
- 階層。 5～8のトップレベルのステージまたはグループは何ですか？ これらがL1のボックスになります。
- 階層ごとのコンポーネント。 表示する価値があるものだけ。「Postgres」はボックスですが、そのテーブルはボックスではありません。
- ライフサイクル。 代表的なリクエストまたはジョブをエンドツーエンドで追跡します。これによりエッジが生成されます。
- 誰が読むか。 通常は経営幹部/アーキテクト/エンジニアのセットですが、確認してください。「顧客/私たちのチーム」や「学生/実務者」かもしれません。
- どの関心事が重要か。 データフローに加えて2～4の関心事：コスト、レイテンシ、信頼とガバナンス、障害モード、所有権、セキュリティ。各レンズには独自のエッジまたは事実が必要です。
- 履歴があるか。 v0 → 今日 → 計画は、顧客業務とロードマップにとって最も価値の高い軸です。システムに意味のある過去がない場合はスキップします。
- 主張。 読者がそれを読んだ後、何を信じるべきですか？ これがビートになります。ユーザーに主張がない場合、エクスプレーナーには背骨がありません — 主張を引き出してください。
2. 主軸を選択する
深さが興味深い軸であることはほとんどありません。図の目的を尋ねてください：
| 目的 | 主軸 |
|---|---|
| 仕組みを教える | 時間 — 1つのリクエストを通過するビート |
| クライアント/ステークホルダーのピッチ | 時代 — 存在するもの、提案されているもの |
| 設計レビュー、リスク | レンズ — 障害モード、信頼境界 |
| オンボーディング、リファレンス | 深さ — 階層、次にコンポーネント |
3. 仕様を書く
1つ書く前に、references/spec-format.mdを完全に読んでください。 これは、すべてのオプションフィールドを含む、完全なノード/エッジ/ビートのリファレンスです。
assets/runtime/specs/llm-eval.jsを作業例としてコピーしてください。これはすべての機能を実行し、模倣するのに適した形状です。新しい仕様をspecs/<name>.jsに書き、次にsrc/spec.jsをそれを指すように設定します（1行 — エントリポイントとリンターの両方がこれを介して読み取ります）。
4. ビルド
最初にassets/runtimeを作業ディレクトリにコピーし、そこでビルドします。インストールされたスキルフォルダ内でnpm installを実行しないでください。多くの場合、共有またはシンボリックリンクされたインストール場所です。
cp -R <skill-dir>/assets/runtime ./explainer
cd explainer
npm install # ネットワークが必要；約20秒
npm run build # 最初に仕様をリントし、次に dist/index.html を出力
リント出力は投影数を示します。失敗した場合は、リンターを弱めるのではなく、仕様を修正してください。 リンターが強制するすべてのルールは、実際の図がそれなしで出荷され、結果が悪化したために存在します。各ルールの意味については、references/spec-format.mdを参照してください。
5. 視覚的に確認 — 必須、両方のフォームファクター
これは最もスキップされがちで、最も影響の大きいステップです。レイアウトの計算は自明ではなく、障害は静かに発生します：クリップされたラベル、5つのボックスを通るエッジ、空のスペースをフレーミングするカメラ。確認せずに完了と宣言しないでください。
node scripts/shots.mjs # デスクトップマトリックス → shots/
次に、自分で電話サイズ（390×844）でスクリーンショットを撮り、画像を開いて検査します。確認事項：
- すべてのペルソナ×時代の組み合わせが重なりやクリップなしでレンダリングされること。
- 各レンズが実際に画像を変更すること — 2つのレンズが同一に見える場合、それらのエッジセットが間違っています。
- ビートフレーミング。 ビートをステップ実行する；各ビートは、空のスペースでもシステム全体でもなく、目に見えるコンテキストでフォーカスをフレーミングする必要があります。
- ラベル。 クリップされていないもの、ボックスの上に重なっているものがないこと。
- 電話。 1列にリフローされ、100%で読みやすく、コントロールがはみ出していないこと。
- コンソール。 サンドボックス化されたiframe内も含め、エラーがゼロであること。
何かがおかしいと思われる場合は、レイアウトコードを変更する前にreferences/troubleshooting.mdを読んでください。
6. 納品
ユーザーにビルドされたdist/index.htmlを提供します。ファイルは自己完結型であり、ホスト、埋め込み、またはオフラインで開くことができることを伝えます。
Claude Code / Claudeアプリのみ。
SendUserFileでファイルを送信してください。ユーザーが再訪するもの（ほとんどのエクスプレーナーが該当）の場合は、create_artifactで永続化も行ってください。
必須条件
- すべてのノードには
why（なぜそのボックスが存在するのか、それが何であるかではなく、1文）が必要です。 - 経営幹部が見ることができるものには、経営幹部向けの語彙で経営幹部レベルの
detailが必要です。 - それぞれが実際の散文を持つ、少なくとも6つのビート。薄いビートはスライドショーを生成し、主張にはなりません。
- ≤34のリーフノード。それを超える場合は、詰め込むのではなく、複数のエクスプレーナーに分割します。
- ビルドごとに1つのテーマ。読者はライト/ダークの切り替えを取得しますが、それ以上はありません。
適応
- 異なるビジュアルディレクション —
src/themes.jsには5つ（house、swiss、editorial、draft、shadcn）があります。src/App.jsxのTHEME_IDを変更します。書体を追加する場合は、metrics.charFactorを正しく設定する必要があります。そうしないと、すべてのラベルがクリップされます。references/troubleshooting.mdを参照してください。 - より多くのペルソナ/レンズ/時代 — 純粋な仕様データであり、コードの変更は不要です。
- ソースからの生成 — リポジトリをウォークし、
DIAGRAMツリーを出力するスクリプトは合理的な拡張ですが、why、detail、およびビートは依然として人間から提供される必要があります。
範囲
これは説明的な図を作成するものであり、ライブダッシュボード、自由形式の描画ツール、またはインフラストラクチャインベントリではありません。ユーザーがドラッグし続ける編集可能な図を望んでいる場合は、代わりにdrawioを望んでいます。ページに1つの数字を望んでいる場合は、チャートを望んでいます。