マーメイドアーキテクト: ダイアグラム & ドキュメンテーションスキル

Mermaid Architect - 包括的な図とドキュメント作成スキル

バージョン2.0 - インテリジェントなオーケストレーションによる階層化アーキテクチャ

オンデマンドガイド読み込み、コードからの図生成、Pythonユーティリティを使用して、Mermaid図と設計ドキュメントを作成する強力なClaude Codeスキル。

インストール

Skilzマーケットプレイスからのワンクリックインストール

このスキルをSkilzマーケットプレイスから即座にインストールします：

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

手動インストール

Claude Codeのスキルディレクトリに直接クローンします：

# Navigate to your skills directory
cd ~/.claude/skills

# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

インストールの確認

インストール後、スキルが利用可能であることを確認します：

# List installed skills
ls ~/.claude/skills/design-doc-mermaid

# Or ask Claude Code
# "List my installed skills"

このスキルの機能

インテリジェントな図生成:

• アクティビティ図（ワークフロー、プロセス、ビジネスロジック）
• デプロイメント図（クラウドインフラ、K8s、サーバーレス）
• アーキテクチャ図（システムコンポーネント、マイクロサービス）
• シーケンス図（APIフロー、サービスインタラクション）
• 図を埋め込んだ完全な設計ドキュメント

コードから図への変換:

• Spring Bootアプリケーションからアーキテクチャを抽出
• 設定ファイルからデプロイメント図を生成
• メソッド呼び出しからシーケンス図を作成
• ETLパイプラインとデータフローを文書化

図の管理:

• MarkdownファイルからMermaid図を抽出
• mermaid-cliで図の構文を検証
• 図をPNG/SVG画像に変換
• ディレクトリ全体をバッチ処理

クイックスタート

アクティビティ図を作成する

User: "Create an activity diagram for user registration with email verification"

スキルは次のことを行います：

1. references/guides/diagrams/activity-diagrams.mdをロード
2. 登録パターンテンプレートを使用
3. Unicodeシンボルを追加（🔐 セキュリティ、📧 メール、✅ 成功）
4. 高コントラストスタイルを適用
5. 完全なMermaid図を出力

コードから生成

User: "Here's my Spring Boot application.yml - generate a deployment diagram"

スキルは次のことを行います：

1. 設定を分析（データソース、キャッシュ、セキュリティ）
2. references/guides/diagrams/deployment-diagrams.mdをロード
3. examples/spring-boot/README.mdをロード
4. 設定をクラウドリソースにマッピング
5. リソース仕様を含むデプロイメント図を生成

設計ドキュメントを作成する

User: "Create an API design document for the contacts API"

スキルは次のことを行います：

1. assets/api-design-template.mdをロード
2. 関連する図ガイドをロード（シーケンス、ER、アーキテクチャ）
3. 図を埋め込んだ完全なドキュメントを生成
4. docs/design/api-contacts-v1-2025-01-13.mdに保存

構造

階層構造

mermaid-architect/
├── SKILL.md                          # Main orchestrator with decision tree
├── README.md                         # This file
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Complete
│       │   ├── deployment-diagrams.md    # ✅ Complete
│       │   ├── architecture-diagrams.md  # ✅ Complete
│       │   └── sequence-diagrams.md      # ✅ Complete
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Complete (master guide)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Complete (100+ symbols)
│       └── troubleshooting.md        # ✅ Complete (28 common errors)
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # ✅ Extract & validate diagrams
│   └── mermaid_to_image.py          # ✅ Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # ✅ Complete
│   ├── fastapi/                     # ✅ Complete
│   ├── react/                       # ✅ Complete
│   ├── python-etl/                  # ✅ Complete
│   ├── node-webapp/                 # ✅ Complete
│   └── java-webapp/                 # ✅ Complete
│
└── assets/                           # Design document templates
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

主な特徴

1. Unicodeセマンティックシンボル

すべての図は意味のあるUnicodeシンボルを使用します：

graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]

シンボルカテゴリ:

• インフラストラクチャ: ☁️ 🌐 🔌 📡 🗄️
• コンピューティング: ⚙️ ⚡ 🔄 🚀 💨
• データ: 💾 📦 📊 📈 🗃️
• メッセージング: 📨 📬 📤 📥 🐰
• セキュリティ: 🔐 🔑 🛡️ 🚪 👤
• モニタリング: 📝 📊 🚨 ⚠️ ✅ ❌

2. 高コントラストスタイリング

すべての図はアクセシブルな高コントラストカラーを使用します。詳細はSKILL.mdを参照してください。

3. Pythonユーティリティ

図の抽出

# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

画像への変換

# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png

# Custom theme and size
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

要件

図生成の場合

• Claude Codeスキルシステム（自動）
• ガイドとテンプレート（このスキルに含まれています）

検証と画像変換の場合

# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version

Pythonスクリプトの場合

• Python 3.7以上
• 追加パッケージ不要（標準ライブラリのみ使用）

学習パス

Mermaid図が初めてですか？

1. アクティビティ図から始める - references/guides/diagrams/activity-diagrams.mdを読む
2. Unicodeシンボルを学ぶ - references/guides/unicode-symbols/guide.mdを読む
3. 例を試す - examples/spring-boot/のパターンを使用する
4. 作業を検証する - python scripts/extract_mermaid.py --validateを実行する

既存のコードを文書化する必要がありますか？

1. フレームワークを特定する - Spring Boot、FastAPI、Reactなど
2. 例のガイドを読み込む - examples/{your-framework}/README.mdを読む
3. パターンを一致させる - 例の中から類似のコードパターンを見つける
4. 図を生成する - ガイドのテンプレートを使用する
5. 検証する - 検証スクリプトを使用する

設計ドキュメントを作成しますか？

1. テンプレートタイプを選択する - アーキテクチャ、API、機能、データベース、システム
2. テンプレートを読み込む - assets/{type}-design-template.mdから読む
3. セクションを埋める - プレースホルダーを実際のコンテンツに置き換える
4. 図を追加する - 各セクションに必要な図ガイドを読み込む
5. シンボルを使用する - 全体をUnicodeシンボルで強化する
6. 保存する - タイムスタンプ付きでdocs/design/に配置する

階層システムの仕組み

従来のアプローチ（非効率）

• スキルドキュメント全体を読み込む（~50KB）
• AIがすべてのテンプレートと例を処理
• 高いトークン使用量
• 遅い応答時間

階層的アプローチ（効率的）

1. ユーザーがリクエスト → AIが意図を分析
2. 決定木がアクティブ化 → 必要なガイドを決定
3. 必要なものだけを読み込む → 特定のガイドを読む（~2-5KB）
4. 出力を生成 → 対象のテンプレートを使用
5. トークン効率が良い → 必要なコンテキストが10分の1

例の流れ

ユーザー: "Docker Composeセットアップのデプロイメント図を作成してください"

決定木:

1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds

消費トークン数: 約2,000（従来のアプローチでは約10,000）

完了状況

✅ 完了:

• 階層的決定木オーケストレーター
• テンプレート付きアクティビティ図ガイド
• デプロイメント図ガイド（AWS、GCP、K8s、サーバーレス、Docker）
• Unicodeシンボルガイド（100以上のシンボル）
• 検証機能付きMermaid抽出スクリプト
• Mermaidから画像への変換スクリプト
• Spring Bootコードから図への変換例
• 設計ドキュメントテンプレート（5種類）
• 高コントラストスタイリングシステム

🚧 進行中:

• FastAPIの例
• Reactコンポーネントアーキテクチャの例
• Python ETLパイプラインの例

📋 計画中:

• アーキテクチャ図ガイド
• シーケンス図ガイド
• コードから図へのマスターガイド
• Node.js/Expressの例
• Java Webアプリの例

貢献

新しい図タイプガイドを追加するには：

1. references/guides/diagrams/{type}-diagrams.mdにガイドを作成
2. 含めるもの：
   • 使用するタイミング
   • 基本構文
   • 一般的なパターン（3〜5のテンプレート）
   • Unicodeシンボルの例
   • ベストプラクティス
3. SKILL.mdの決定木を更新
4. コードマッピング付きの例を追加

新しい言語の例を追加するには：

1. examples/{framework}/にディレクトリを作成
2. 以下を含むREADME.mdを追加：
   • フレームワークの概要
   • 構造からのアーキテクチャ図
   • 設定からのデプロイメント図
   • コードからのシーケンス図
   • ロジックからのアクティビティ図
3. SKILL.mdのコードから図への変換テーブルを更新

ライセンス

Claude Code Skillsの一部 - MITライセンス

関連スキル

• confluence - Confluenceに図をアップロード
• plantuml - 代替図形式

リンク

• GitHubリポジトリ
• Skilzマーケットプレイスリスティング
• Mermaid公式ドキュメント

バージョン: 2.0.0 更新日: 2025-01-13 メンテナンス: SpillwaveSolutions