explain-architecture

アーキテクチャを説明する

モデルを選ぶ前にブランチを選択します。割り当てられた役割で調査、構成、検証を行い、視覚的な成果物を確認します。独立した調査作業を割り当てる前に、shared/references/model-preview.md を使って、承認済みのスナップショットを必ずちょうど1つ取得するか、既存のものを再利用してください。

コードベース（または選択した一部分）の正確なメンタルモデルを構築し、自己完結型のHTML オリエンテーションページとして提供します。目的はオリエンテーションであり、批評ではありません。読み終えた人が、各要素の内容、相互のつながり、データの流れ、次に調べる場所を理解できるようにします。

Practical Model-Driven Enterprise Architecture からの考え方です。説明とは、定義された対象読者のために定義された問いに答える「ビュー」であり、構造（各要素の内容とつながり）と振る舞い（何がどの順序で起きるか）に分けられます。まず対象範囲と対象読者を決め、それに役立つ内容だけを説明します。「1つのビューでは、1つの考えだけを伝える」のです。

成果の軸

• 成果物： インライン CSS、JavaScript、SVG を含む単一の .html ファイル。既定の保存先は docs/<scope>-architecture.html です。
• 次の利用者： 自分の位置づけを把握する人。サーバーを使わず、ディスクから直接開きます。
• 完了条件： ファイルが存在し、scripts/validate_explain_architecture.py が終了コード 0 で終了し、ページがレンダリングされているか、ユーザーに送信されていること。
• 意図： 地図であり、領域そのものではありません。セクションは4～6個、追跡するフローは1つとし、すべての主張を実際に読んだファイルに基づかせます。それ以上の深掘りは html-explainer に任せます。

ステップ 0 — 対象範囲と対象読者（不明な場合のみ確認）

調査を始める前に、次の2点を確定します。依頼から判断できる場合は推測し、判断できない場合は短い質問を最大1つだけします。

• 対象範囲 — リポジトリ全体、1つのサービス、1つの機能／フロー、または1つのモジュール。
• 対象読者／視点：
  • 初学者 — オンボーディング向けの概要。専門用語は最小限にし、「どこから始めるか」を示します。
  • 実装者 — 機能を追加するために必要な情報。拡張ポイント、慣例、注意点を含めます。
  • レビュー担当者 — 境界、依存関係、不変条件、リスク領域を示します。

ユーザーが特に条件を付けずに「アーキテクチャを説明して」とだけ依頼した場合は、_初学者向けのリポジトリ全体の概要_を既定とします。

視点が確定したら、調査を始める前に references/viewpoints.md を読み、その視点に応じた重点項目とページの分量を確認します。

出力先：プロジェクトリポジトリ内の docs/<scope>-architecture.html。成果物の更新を明示的に依頼された場合は、対象範囲を限定して編集できます。既存の出力先が置き換え対象として指定されていない場合は、新しいパスを使うか、どの成果物を更新するかを確認してください。無関係な内容は保持します。

ステップ 1 — 調査する（推測しない）

共通の証拠要件 shared/references/grounded-evidence.md に従います。すべての主張は実際に読んだファイルに基づかせ、path:line 形式で引用し、コードを再構成してはいけません。外側から内側へ調査します。

1. エントリーポイントとマニフェスト — パッケージマニフェスト、ワークスペースファイル、デプロイメントテンプレート、適用中のプロジェクト指示、README、docs/、設定を確認します。これらから意図を効率よく把握できます。
2. トップレベルの構造 — ディレクトリツリーを各要素の責務に対応付けます。主要な各単位の名称と、1行で説明できる役割を示します。
3. 接続点 — 単位間の通信方法を確認します。HTTP ルート、メッセージバス／イベント、共有データレイヤー、cron／ワーカーなどです。接続点がアーキテクチャそのものです。
4. 実際のフローを1つ、端から端まで追跡する — 代表的なリクエストまたはイベントを各レイヤーに沿って追います（例：フロントエンドの操作 → API ルート → サービス → エンティティ／DB → 発行イベント → ワーカー）。抽象的な説明より具体的な追跡を優先します。
5. 横断的な関心事 — 認証、マルチテナンシー、エラー処理、マイグレーション、コード生成。

対象範囲が広い場合は、調査領域が独立していて十分な規模があり、証拠に実質的な不足がある場合に限り、調査を割り当てます。選択した各ワーカーには承認済みスナップショットを使用してください。入れ子になったワーカーは、ルートを再解決したり、ワーカーを追加したりしてはいけません。それ以外の場合は、割り当てられた役割で調査します。結論、ソースパス、短く検証済みのスニペットを保持し、ファイル全体のダンプは避けます。計画した各セクションに、リード文、マップの事実、path:line 付きの逐語引用スニペットが1～3個そろった時点で終了します。

ステップ 2 — レイヤーに整理する

コンポーネントを（書籍にある）3 つのレイヤーにグループ化し、読者に一覧ではなく順序が伝わるようにします。

• ビジネス — ドメインルールと不変条件。
• アプリケーション — ドメインを自動化するソフトウェア：サービス、ルート、ワーカー、フロントエンドアプリ。
• テクノロジー — インフラの配線：クラウドランタイム、データベース、認証、ビルド／デプロイ。

これらの名称を無理に当てはめるのではなく、実際に見つかったものからレイヤーを導き出します。独立したワーカーティアがないリポジトリでは、ページにそのレイヤーを設けません。

ステップ 3 — ページを組み立てる

このスキルのディレクトリにある assets/template.html を出力先にコピーし、各スロットを置き換えます。自己完結性、3 つの深さ、エスケープ、検証については shared/references/html-page-conventions.md を読みます。以下の表は、このスキルのページ構成です。

ページ領域	内容
ヘッダーのサブタイトル	1 段落で： このシステムが何で、どのような単一の考え方で整理されているか（例：「イベント駆動型のサーバーレスモノレポ、組織単位のマルチテナント、OpenAPI ファーストのフロントエンド」）。
全体像マップ	構成要素とその境界を 1 つの SVG で示し、レイヤー（ビジネス／アプリケーション／テクノロジー）ごとにボックスをグループ化します。各ボックスには、対応するセクションへ移動する onclick="jump('sec-…')" を設定します。キャプションには、このページで扱わない内容を記します。
技術スタックのグリッド	視点に必要なものだけを示します。初学者向けなら 3～5 項目、レビュアー向けならランタイム全体を示します。追加する意味がなければ、この領域は省略します。
1 · 構成要素（構造）	主要コンポーネントごとに details.drill を 1 つ設けます。1 行で役割を示し、パスと、やり取りする隣接コンポーネントを記載します。
2 · 全体の連携	レイヤーの流れ、依存関係の方向、境界とその契約を説明します。方向が重要な場合は、小さなセクション図を添えます。
3 · エンドツーエンドのフロー（振る舞い）	実際のリクエスト／イベントをたどる .flow の各ステップに、path:line のバーと短い逐語的なスニペットを付けます。
4 · 横断的な関心事	対象範囲に関係するものに限り、認証、マルチテナンシー、マイグレーション、コード生成などを扱います。
5 · 次に確認する場所	読者が目的に応じて最初に開くべき 3～5 個のファイル／ディレクトリを示します。

視点上必要な場合に限り、第 6 セクションを追加します（レビュアー向け：境界と不変条件、実装者向け：拡張ポイントと規約）。6 セクションを超えてはいけません。超える場合は、対象に html-explainer が必要です。

書籍の「モデリングのベストプラクティス」にあるルールを、ページに適用します。

• 1 ページにつき 1 つの考え方。 2 つのサブシステムそれぞれに十分な説明が必要なら、2 ページを作成して相互にリンクします。
• 対象読者に必要な詳細だけにする。 初学者にはすべての Lambda の説明は不要ですが、レビュアーには境界の説明が必要です。
• コードベース固有の語彙（分類体系）で名称を付ける。 独自の用語を作らないでください。
• 論評を加えない。 理解を妨げる問題があれば、コールアウトで 1 つ指摘するにとどめます。品質の評価はこのスキルではなく、architecture-lens の役割です。
• スニペットはすべて、根拠の契約に従い、逐語的なものにするか、載せないかのどちらかにします。

ステップ 4 — 検証する

SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
python3 "$SKILL_DIR/scripts/validate_explain_architecture.py" <output-file.html>

終了コードが 0 になるまで問題を修正し、その後、共通規約の検証手順に従います（レンダリング、jump() のクリックでセクションに移動できること、最初の画面より下にある DOM クエリ）。

ステップ 5 — 納品する

ファイルパスとナビゲーション方法（マップ上のボックスをクリックする、▸ パネルを展開する）を最初に示します。各セクションを 1 行ずつ列挙し、視覚的に確認できなかった箇所があれば明記します。読者が 1 つのサブシステムをさらに詳しく調べたい場合は html-explainer を提案します。その際、対象範囲、視点、調査資料を引き継ぎ、再調査を避けます。