architecture-diagrams

アーキテクチャ図スキル

目標

インフラストラクチャのソースファイル、または宣言された DS_CATALOG_V1 データモデルを、レビュー、ADR、設計に関する議論に使える読みやすいアーキテクチャ図に変換します。呼び出し元が選択した出力形式と、ソースの権威範囲を維持します。

インフラストラクチャの入力には、Terraform、Bicep、ARM テンプレート、シェルスクリプト、Kubernetes マニフェスト、Docker または Compose ファイルが含まれます。カタログ入力では、データカタログ用の永続的なスキルである data-catalog の宣言済みエンティティと関係を使用します。SQL ファイルや ORM ファイルからデータモデルを推測することはありません。

このスキルは、インフラストラクチャのトポロジとデータモデルを文書化します。コンテナー、コンポーネント、ならびにそれらを取り巻く人やシステムを含むソフトウェアシステムを文書化するには、代わりに c4-architecture スキルを使用してください。

成功基準

• 図には、確認済みのソース範囲のみが含まれます。
• インフラストラクチャのソースでは、既存の解析と関係の処理が維持されます。
• カタログ図では、宣言済みのエンティティ ID、エンドポイント、多重度、エンドポイントの最小値、結合キー、信頼度、根拠を維持し、関係を捏造しません。
• ASCII または Mermaid の出力は、呼び出し元の希望に従います。
• 推測されたカタログの関係と仮定されたカタログの関係は、確認済みの関係と視覚的に区別されます。

制約

• 図はソースの権威範囲を反映したビューとして扱い、それ自体を意味上の権威と見なさないでください。
• DS_CATALOG_V1 の入力、多重度のマッピング、信頼度の表示、カタログ出力の契約、Functional Planner との互換性の境界については、catalog-erd.md を読んでください。
• SQL DDL、Prisma、SQLAlchemy、その他の ORM をカタログ入力として解析しないでください。
• カタログの結合キーにはフィールド名のみが宣言されており、データベースのキーの役割は宣言されていないため、主キー、外部キー、一意性を示すマーカーを表示しないでください。
• Feasibility Study Interchange Profile と下流の要件マッピングは、それぞれを所管するワークストリームに維持してください。

停止ルール

• インフラストラクチャの境界が曖昧な場合は停止し、範囲を確認してください。
• サポート対象外のカタログバージョン、解決できないエンドポイント、不明な多重度、欠落または無効なエンドポイントの最小値、不明な信頼度の値、または不正な結合キーの宣言がある場合は、推測したり一部だけを描画したりせず、停止して報告してください。
• 出力形式の希望を特定できない場合は、図の生成を開始する前に停止してください。

出力形式

このスキルは、ASCII ブロック図または Mermaid 図のいずれかを生成します。どちらも既定ではありません。呼び出し元または周囲のコンテキストによって、図ごとに出力形式が選択されます。呼び出し元が希望を示していない場合は、生成前に希望する形式を尋ねてください。

図の種類はソースの種類に従います。インフラストラクチャのソースは、以下の ASCII 規約または Mermaid 規約に従って、ASCII ブロック図または Mermaid フローチャートとして表示します。カタログのソースは、catalog-erd.md に従って、ASCII エンティティ行または Mermaid の erDiagram として表示します。いずれの場合も、形式が異なっても構造、境界、関係は同一にしてください。

希望形式の契約

アーキテクチャ図の形式選択は、ADR 以外にも適用されます。単独で使用する場合は、ルートの状態ファイル .copilot-tracking/architecture-diagrams/state.json を参照してください。このファイルが存在しない場合は、形式の選択時に作成してください。

{
  "userPreferences": {
    "diagramFormat": "mermaid"
  },
  "repoVisibility": "private"
}

userPreferences.diagramFormat の値は ascii または mermaid でなければなりません。repoVisibility フィールドは任意であり、周囲のワークフローがパブリックリポジトリとプライベートリポジトリを区別する必要がある場合に使用できます。形式の決定順序は次のとおりです。

1. 明示的なリクエストまたは呼び出し元の状態。
2. ルートの状態ファイル .copilot-tracking/architecture-diagrams/state.json。
3. 単独のリクエストで希望する形式が不明な場合は、希望を一度尋ね、後で再利用できるよう回答をルートの状態ファイルに保存します。

ワークフロー

図を作成するときは、次の手順に従ってください。

1. 調査。関連するインフラストラクチャファイル、または宣言されたカタログと、アーキテクチャの対象範囲を特定します。対象範囲が不明確な場合は、どのフォルダー、サービス、エンティティを含めるべきか確認します。
2. 解析。インフラストラクチャの場合は、サービス、データストア、ネットワークコンポーネント、イングレスポイント、デプロイ単位を抽出します。カタログの場合は、scripts/render_catalog_erd.py を実行するか、推測に基づく意味を加えずに catalog-erd.md に従います。
3. 関係のマッピング。インフラストラクチャの場合は、コンポーネントを正しい方向で接続します。カタログの場合は、宣言されたエンドポイント、カーディナリティ、エンドポイントの最小数、結合キー、信頼度、根拠を正確に保持します。
4. 生成。境界やエンティティラベルが明確で、簡潔な凡例を備えた図を、呼び出し元が選択した形式で描画します。

ASCII の規則

一貫したボックス表記と配置を使用します。

+------------------+      +------------------+
|   Service Name   |----->|   Service Name   |
+------------------+      +------------------+

読みやすさを保つため、次の規則に従ってください。

• ボックスのラベルは短く、具体的にします。
• 矢印の位置をそろえ、可能な場合は1行につき1つの関係を記述します。
• 装飾を詰め込むのではなく、境界に分かりやすい名前を付けます。
• 類似するコンポーネントには、同じ形状のボックスを使用します。

矢印の種類

矢印	意味
---->	データフローまたは依存関係
<--->	双方向の接続
- - >	オプションまたは条件付きのリソース

グループ化と境界

ネットワーク、アカウント、またはデプロイドメインを共有する関連コンポーネントは、より大きな境界内にグループ化します。

明確な境界には、全面的なボックスを使用します。

+-----------------------------------------------+
|  Resource Group                               |
|                                               |
|  +-------------+        +-------------+       |
|  |   VNet      |------->|   Subnet    |       |
|  +-------------+        +-------------+       |
|                                               |
+-----------------------------------------------+

二次的な境界や入れ子になった境界には、ラベル付きの境界を使用します。

:--- Virtual Network ---------------------------:
:                                               :
:  +-------------+        +-------------+       :
:  |   Subnet A  |------->|   Subnet B  |       :
:  +-------------+        +-------------+       :
:                                               :
:-----------------------------------------------:

Mermaid の規則

呼び出し元が Mermaid 形式を選択した場合は、ASCII で描画する構造、境界、関係を同じように表現する flowchart を、mermaid のフェンス付きコードブロックで描画します。

• 上から下へのトポロジには flowchart TB を使用し、主要なフローが左から右に進む場合は flowchart LR を使用します。
• 各コンポーネントを、lb["Load Balancer"] のような短く具体的なラベルを持つノードとして宣言し、データストアには [("...")] を使用します。
• ネットワーク、アカウント、またはデプロイドメインを共有するコンポーネントは、VNet、サブネット、リソースグループなどを表す subgraph ブロック内にグループ化します。
• データフローまたは依存関係には -->、双方向の接続には <-->、オプションまたは条件付きのリンクには -. optional .-> を使用します。
• ノード識別子は小文字で一貫性を保ち、人が読める名前にはラベルを使用します。

flowchart TB
    subgraph rg["Resource Group"]
        lb["Load Balancer"]
        subgraph subnet["App Subnet"]
            vm1["VM 1"]
            vm2["VM 2"]
        end
        db[("SQL Database")]
    end
    lb --> vm1
    lb --> vm2
    vm1 --> db
    vm2 --> db

レイアウトのガイドライン

• 外部サービスまたは公開サービスを上部に配置します。
• コンピューティング層またはアプリケーション層を中央に配置します。
• データストアを下部に配置します。
• VNet やサブネットなどのネットワーク境界ごとにコンポーネントをグループ化します。
• 方向が明確な場合は、主要なフローを上から下に配置します。

リソースの特定に関するヒューリスティクス

インフラストラクチャのソースを読む際は、次の情報を抽出します。

• リソースの種類と名前
• VNet、サブネット、プライベートエンドポイント、イングレス設定などのネットワーク関連付け
• 構成で明示された依存関係と、参照から暗示される依存関係
• コンテナレジストリ、サービスメッシュ、ワークロードの配置などのデプロイ関係

出力形式の契約

すべてのインフラストラクチャ図で、次の構成を使用します。

## <Name> Architecture

[diagram in the selected format]

### Legend
[Arrow meanings from this diagram; reference the arrow types above]

### Key Relationships
[Notable connections and dependencies]

タイトルにはタイトルケースを使用し、<Name> Architecture のパターンに従います。凡例では使用した特殊記号を説明し、主要な関係のセクションでは、最も重要な依存関係やデータフローに焦点を当てます。

カタログ図では、catalog-erd.md で定義されている並行の ## <Engagement> Data Model の契約を使用します。凡例には多重度と信頼度を含め、主要な関係のセクションには宣言されたすべての関係とその根拠を記載します。

作成例：AKS プラットフォームアーキテクチャ

## AKS Platform Architecture

+===============================================================+
|  Resource Group                                               |
|  :--- Virtual Network ------------------------------------:   |
|  :  +------------------+        +------------------+      :   |
|  :  |   NAT Gateway    |------->|   AKS Cluster    |      :   |
|  :  +------------------+        +--------+---------+      :   |
|  :                              +--------v---------+      :   |
|  :                              |       ACR        |      :   |
| :                              +------------------+      : |
|:----------------------------------------------------------:|
|      +------------------+        +------------------+      |
|     | Log Analytics    |<-------|  App Insights    |          |
|     +------------------+        +------------------+          |
+===============================================================+

### Legend
See the arrow types above. Additional symbols: `====` primary boundary, `:---:` secondary boundary.

### Key Relationships
* AKS pulls images from ACR through the network boundary.
* NAT Gateway provides egress for AKS workloads.

同じアーキテクチャを Mermaid 形式で表すと、構造、境界、関係が同じ図になります。

## AKS Platform Architecture

```mermaid
flowchart TB
    subgraph rg["Resource Group"]
        subgraph vnet["Virtual Network"]
            nat["NAT Gateway"]
            aks["AKS Cluster"]
            acr["ACR"]
        end
        appinsights["App Insights"]
        logs[("Log Analytics")]
    end
    nat --> aks
    aks --> acr
    appinsights --> logs
```

### Legend
See the arrow types above; `subgraph` blocks denote network or resource boundaries.

### Key Relationships
* AKS pulls images from ACR through the network boundary.
* NAT Gateway provides egress for AKS workloads.

作成ガイドライン

• アーキテクチャの範囲が曖昧な場合は、確認の質問を1つか2つしてください。
• 検出から解析、または生成へ移る際は、現在のワークフローの段階を伝えてください。
• 最終確定の前に、含まれるリソースの簡単な概要を添えて、図のドラフトを提示してください。
• 図に影響する場合は、暗黙の依存関係など、重要な推論の判断を記載してください。
• 図はインフラストラクチャのソースを静的に表現するものとして扱い、実行時のビューにはしないでください。
• 読みやすさを保てるよう、出力の対象は単一のアーキテクチャ範囲に絞ってください。