---

name: generate-architecture-docs description: | 構成図からアーキテクチャドキュメントを自動生成するスキル。 visualize-architectureまたはpropose-architectureの出力を正式なドキュメントに変換。 docs/配下にGitHub管理対象ドキュメントを生成。 allowed-tools: Read, Grep, Glob, Bash, Write

Architecture Documentation Generator Skill

visualize-architecture または propose-architecture で生成した構成図を基に、GitHub 管理対象となる正式なアーキテクチャドキュメントを docs/ 配下に自動生成するスキルです。

使用例

構成図からドキュメント生成

Copy/generate-architecture-docs tmp/architecture_diagrams/pre_docs/infrastructure

提案から ADR 生成

Copy/generate-architecture-docs tmp/architecture_diagrams/pre_adr/image_upload

対象

• tmp/architecture_diagrams/pre_docs/ 配下の構成図（visualize-architecture 出力）
• tmp/architecture_diagrams/pre_adr/ 配下の提案ドキュメント（propose-architecture 出力）

出力先

スキル構成

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

引数

• {source_path}: 構成図ファイルのパス（必須）
  • 例: tmp/architecture_diagrams/pre_docs/infrastructure/
  • 例: tmp/architecture_diagrams/pre_adr/new_feature/

実行手順

Step 1: ソースファイルの取得

引数で指定されたパスから構成図ファイルを取得：

Copyls {source_path}

期待するソースディレクトリ構造:

Copy{source_path}/
├── 01_<name>.md              # Markdownドキュメント
├── 02_<name>.md
├── draw/                     # Draw.io ソースファイル
│   └── 01_<name>.drawio
├── mmd/                      # Mermaid ソースファイル
│   ├── 01_<name>.mmd
│   └── ...
├── puml/                     # PlantUML ソースファイル
│   └── 01_<name>.puml
└── images/                   # PNG/SVG 画像ファイル
    ├── 01_<name>.png
    └── ...

対象ファイル形式：

• .md (Markdown ドキュメント)
• .drawio (Draw.io 形式)
• .mmd (Mermaid 形式)
• .puml (PlantUML 形式)
• .png, .svg (画像ファイル)

ファイルが存在しない場合はエラーを返す：

「指定されたパス {source_path} にファイルが見つかりません。 /visualize-architecture または /propose-architecture を先に実行してください。」

---

Step 2: 構成図ファイルの解析

解析内容：

---

Step 3: 出力先の決定

ソースパスと内容に基づいて適切な出力先を決定。

ADR 番号の採番ルール

Copy# 既存ADRの最大番号を取得して+1
ls docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1 || echo "0"

新規 ADR の場合は {最大番号 + 1} を使用（例: 001_, 002_）

---

Step 4: ドキュメントの生成

4-1. ドキュメント構成

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

feature_components の場合:

Copydocs/feature_components/<feature_name>/
├── 01_<name>.md              # 英語版ドキュメント
├── 01_<name>.ja.md           # 日本語版ドキュメント
├── draw/                     # Draw.io ソースファイル
│   └── 01_<name>.drawio
├── mmd/                      # Mermaid ソースファイル
│   ├── 01_<name>.mmd
│   └── ...
├── puml/                     # PlantUML ソースファイル
│   └── 01_<name>.puml
└── images/                   # PNG/SVG 画像ファイル
    ├── 01_<name>.png
    └── ...

architecture/infrastructure の場合:

Copydocs/architecture/infrastructure/<concept_name>/
├── 01_overview.md            # 英語版
├── 01_overview.ja.md         # 日本語版
├── draw/
├── mmd/
├── puml/
└── images/

ADR の場合:

Copydocs/adr/<number>_<feature_name>/
├── 01_README.md              # 英語版
├── 01_README.ja.md           # 日本語版
├── draw/
├── mmd/
├── puml/
└── images/

4-2. 命名規則

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

連番ルール:

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

4-2. ドキュメントテンプレート

feature_components / architecture 用:

Copy[English](./{filename}.md) | [日本語](./{filename}.ja.md)

# {タイトル}

## 概要

{システム/機能の概要説明}

## 決定事項

- {採用した構成・技術の要点}

## 背景

- {なぜその構成にしたのか}

## アーキテクチャ図

{構成図の埋め込みまたは画像参照}

## コンポーネント詳細

### {コンポーネント名 1}

- **役割**: {役割説明}
- **技術**: {使用技術}
- **責務**: {責務説明}

## データフロー

{データフローの説明}

## 技術スタック

| カテゴリ   | 技術     | 用途   |
| ---------- | -------- | ------ |
| {カテゴリ} | {技術名} | {用途} |

## セキュリティ考慮事項

{セキュリティに関する説明}

## スケーラビリティ・パフォーマンス

{スケーラビリティとパフォーマンスに関する説明}

## 関連ドキュメント

- {関連ドキュメントへのリンク}

ADR 用:

Copy[English](./{filename}.md) | [日本語](./{filename}.ja.md)

# ADR-{番号}: {タイトル}

## ステータス

{Proposed | Accepted | Deprecated | Superseded}

## コンテキスト

### 現状の課題

- {課題 1}: {具体的な問題点}
- {課題 2}: {具体的な問題点}

### なぜこの構成・機能が必要か

{課題を解決するために、なぜこの構成・機能が最適なのかを説明}

## 決定

### 選定経緯（他選択肢との比較）

| 選択肢     | Pros       | Cons         | 採用 |
| ---------- | ---------- | ------------ | ---- |
| {選択肢 A} | {メリット} | {デメリット} | ✅   |
| {選択肢 B} | {メリット} | {デメリット} | -    |
| {選択肢 C} | {メリット} | {デメリット} | -    |

**選定理由:** {なぜ選択肢 A を採用したのかを 1-2 文で}

### 採用する構成

{採用した構成の説明}

## アーキテクチャ図

{構成図の埋め込みまたは画像参照}

## 結果

### 解決される課題

- ✅ {解決される課題 1}
- ✅ {解決される課題 2}

### 残課題・今後の観測事項

| 項目       | 状態          | 対応方針                                           |
| ---------- | ------------- | -------------------------------------------------- |
| {残課題 1} | 🔶 一部不明瞭 | リリース後に{観測内容}を確認し、必要に応じて再検討 |
| {残課題 2} | ⚠️ 未解決     | Phase 2 で対応予定                                 |

### 観測ポイント

- {リリース後に確認すべき指標やログ}
- {再検討のトリガーとなる条件}

## 関連ドキュメント

- {関連ドキュメントへのリンク}

---

Step 5: 最終確認

生成したドキュメント内容をユーザーに提示し、確認を求める：

「以下の内容でドキュメントを生成します。よろしいですか？（y/N）

---

出力先: {出力パス}

生成ファイル:

• {ファイル1} (英語版)
• {ファイル2} (日本語版)
• diagrams/ (図表ファイル)

プレビュー: {ドキュメントプレビュー}

---」

既存ファイルがある場合は上書き確認：

「⚠️ 既存ファイルが存在します: {ファイルパス}

上書きしてよろしいですか？（y/N）」

---

Step 6: ファイル出力

承認後、ドキュメントファイルを生成：

Copy# ディレクトリ作成
mkdir -p {出力先}/diagrams

# ドキュメントファイル生成
# 英語版: {filename}.md
# 日本語版: {filename}.ja.md

# 画像ファイルのコピー
cp {source_path}/*.png {出力先}/diagrams/ 2>/dev/null || true
cp {source_path}/*.svg {出力先}/diagrams/ 2>/dev/null || true

---

Step 7: 完了報告

「ドキュメントを生成しました：

出力先: {出力パス}

生成ファイル:

• {ファイル1} (英語版)
• {ファイル2} (日本語版)

次のステップ:

• 生成されたドキュメントを確認してください
• 必要に応じて内容を編集してください
• コミット・プッシュして GitHub 管理下に置いてください」

---

注意事項

• ソースファイルが存在しない場合はエラーを返すこと
• 既存ファイルがある場合は上書き確認を行うこと
• 英語版・日本語版の両方を生成すること
• 言語切り替えリンクを各ファイルの冒頭に追加すること
• 画像ファイルは diagrams/ ディレクトリにコピーすること
• ADR の場合は採番ルールに従うこと
• 決定事項・背景・選定経緯は必ず含めること
• 図表ファイル（.drawio, .mmd, .puml）は全て英語表記で作成すること