---

name: visualize-architecture description: | プロジェクトのアーキテクチャ構成図を生成するスキル。 インフラ、バックエンド、フロントエンドを解析し、Draw.io/Mermaid.js/PlantUML形式で可視化。 現状構成の把握、ドキュメント作成時に使用。 allowed-tools: Read, Grep, Glob, Bash, Write

Architecture Visualization Skill

プロジェクトのインフラ・バックエンド・フロントエンドを解析し、各種フォーマットで構成図を生成するスキルです。

使用例

全体構成図の生成

Copy/visualize-architecture
→ 「1. インフラ全体構成図」を選択
→ 「1. 全体」を選択

特定コンポーネントの構成図

Copy/visualize-architecture
→ 「2. シーケンス図」を選択
→ 「5. 特定コンポーネント」を選択
→ 「記事閲覧数カウンター機能」と指定

対象

• infra/ 配下の Terraform リソース定義
• backend/ 配下の API サービス、バッチ処理
• frontend/ 配下の Next.js アプリケーション
• .github/workflows/ 配下の CI/CD パイプライン

生成可能な構成図

解析観点

• 使用クラウドサービス（AWS: Amplify, Lambda, API Gateway, DynamoDB, ECR 等）
• サーバー構成（コンテナ、サーバーレス）
• バックエンド技術（Go, Clean Architecture, sqlc, pgx/v5）
• フロントエンド技術（Next.js 14, TypeScript, TailwindCSS）
• データストア（Supabase PostgreSQL, DynamoDB）
• CI/CD パイプライン（GitHub Actions）

スキル構成

Copy.claude/skills/visualize-architecture/
└── SKILL.md                        # このファイル

実行手順

Step 1: 要件ヒアリング

ユーザーに以下を確認：

「どのような構成図を生成しますか？

1. インフラ全体構成図 - AWS/クラウドリソースの俯瞰（Draw.io 推奨）
2. シーケンス図 - API 連携、データフロー（Mermaid.js 推奨）
3. コンポーネント図 - サービス間の依存関係（Draw.io, or PlantUML 推奨）
4. フローチャート - 処理フロー、CI/CD パイプライン（Mermaid.js 推奨）

番号で選択、または具体的な要件を教えてください。」

---

Step 2: 対象範囲の確認

ユーザーに以下を確認：

「対象範囲を選択してください：

1. 全体 - インフラ・バックエンド・フロントエンド全て
2. インフラのみ - AWS/クラウドリソース
3. バックエンドのみ - API、Lambda、データベース
4. フロントエンドのみ - Next.js 構成
5. 特定コンポーネント - 具体的に指定

番号で選択してください。」

---

Step 3: 解析の実行

注意: 解析には時間がかかります。正確性を重視して解析を行います。

ユーザーに以下を伝達：

「解析を開始します。正確な構成図を生成するため、コードベースを詳細に解析します。 数分程度かかる場合がありますので、しばらくお待ちください。」

解析対象ディレクトリ：

---

Step 4: 構成図の生成

4-1. 出力先ディレクトリの作成

Copymkdir -p tmp/architecture_diagrams/pre_docs/<feature_name>/{draw,mmd,puml,images}

4-2. 出力ディレクトリ構造（必須）

重要: 図表ソースファイルは必ず専用ディレクトリに分離し、MD ファイルから参照する形式とすること

Copytmp/architecture_diagrams/pre_docs/<feature_name>/
├── 01_<diagram_type>.md          # Markdownドキュメント（図表を参照）
├── 02_<diagram_type>.md          # Markdownドキュメント（図表を参照）
├── draw/                         # Draw.io ソースファイル
│   └── 01_<name>.drawio
├── mmd/                          # Mermaid ソースファイル
│   ├── 01_<name>.mmd
│   ├── 02_<name>.mmd
│   └── ...
├── puml/                         # PlantUML ソースファイル
│   ├── 01_<name>.puml
│   └── ...
└── images/                       # PNG/SVG 画像ファイル
    ├── 01_<name>.png             # mmdからmmdc変換
    ├── 02_<name>.png
    ├── draw.png                  # drawioから手動エクスポート
    └── ...

4-3. 命名規則

各階層ごとに連番プレフィックスを付与すること:

連番ルール:

• 各ディレクトリ内で独立した連番（01, 02, 03...）
• ゼロ埋め 2 桁（01, 02, ... 99）

4-4. Mermaid 図の PNG 変換

mmd ファイル作成後、mmdcコマンドで PNG に変換：

Copyfor f in mmd/*.mmd; do
  name=$(basename "$f" .mmd)
  mmdc -i "$f" -o "images/${name}.png" -b white -w 1600 -H 1200
done

4-5. MD ファイルからの参照形式

図表はコードブロックではなく、ファイル参照形式で埋め込むこと:

Copy## シーケンス図

![画像アップロードURL取得フロー](./images/01_upload_url_flow.png)

**Mermaid ソース:** [mmd/01_upload_url_flow.mmd](./mmd/01_upload_url_flow.mmd)

PlantUML の場合:

Copy## コンポーネント図

**PlantUML ソース:** [puml/01_component.puml](./puml/01_component.puml)

{PlantUML コードブロック - 変換ツールがない場合のフォールバック}

4-6. 決定事項と背景の明記（必須）

生成する構成図には、以下の情報を端的かつ簡潔に明記すること：

必須記載項目:

記載フォーマット:

Copy## 決定事項

- {採用した構成・技術の要点を 1-2 文で}

## 背景

- {なぜその構成にしたのかを 1-3 文で}

記載ルール:

• 冗長な説明を避け、要点のみを記載
• 技術的な正確性を保ちつつ、簡潔に表現
• 推測ではなく、コードベースから読み取れる事実に基づく

---

Step 5: ユーザへの提供

生成した構成図をユーザーに提示：

「構成図を生成しました：

出力先: tmp/architecture_diagrams/pre_docs/<feature_name>/

生成ファイル:

• {ファイル 1}
• {ファイル 2}

プレビュー: {構成図のプレビュー表示}

修正や追加の要望があればお知らせください。」

---

Step 6: ドキュメント生成の確認

ユーザーに以下を確認：

「この構成図を基に、正式なアーキテクチャドキュメントを docs/ 配下に生成しますか？

• y: /generate-architecture-docs を実行してドキュメントを生成
• N: 構成図のみで完了

（y/N）」

承認された場合は /generate-architecture-docs tmp/architecture_diagrams/pre_docs/<feature_name> を実行。

---

出力フォーマット例

Mermaid.js（シーケンス図）

Copy# API 連携シーケンス図

## 決定事項

- フロントエンドから API Gateway 経由で Lambda 関数を呼び出す構成を採用

## 背景

- サーバーレスアーキテクチャによるスケーラビリティと運用コスト削減のため

## シーケンス図

```mermaid
sequenceDiagram
    participant F as Frontend (Next.js)
    participant AG as API Gateway
    participant L as Lambda (Go)
    participant DB as PostgreSQL (Supabase)

    F->>AG: GET /article/v1/articles
    AG->>L: Invoke
    L->>DB: Query
    DB-->>L: Results
    L-->>AG: Response
    AG-->>F: JSON
```

PlantUML（コンポーネント図）

Copy# コンポーネント図

## 決定事項

- Clean Architecture に基づく 4 層構成を採用

## 背景

- ドメインロジックの独立性を保ち、テスタビリティを向上させるため

```plantuml
@startuml
package "Controller" {
    [ArticleController]
}
package "Usecase" {
    [ArticleUsecase]
}
package "Domain" {
    [Article]
}
package "Repository" {
    [ArticleRepository]
}

[ArticleController] --> [ArticleUsecase]
[ArticleUsecase] --> [Article]
[ArticleUsecase] --> [ArticleRepository]
@enduml
```

---

注意事項

• 解析には時間がかかる旨をユーザーに事前通知すること
• 正確性を重視し、推測での記載は避けること
• 複雑な構成の場合は複数ファイルに分割すること
• 決定事項と背景は必ず明記すること
• このスキルは構成図の生成のみを行い、コードの変更は行わない
• 図表ファイル（.drawio, .mmd, .puml）は全て英語表記で作成すること