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

> インテリジェントなオーケストレーション、コードからダイアグラムへの変換、Pythonユーティリティを使用して、包括的なマーメイドダイアグラムと設計ドキュメントを生成します。数秒で詳細な技術ドキュメントの作成を開始できます。

- Canonical: https://nanoskill.ai/ja/skills/mermaid-agent-skill
- Markdown: https://nanoskill.ai/ja/skills/mermaid-agent-skill.md
- Author: SpillwaveSolutions
- Published: 2026-05-26T01:25:42.765Z
- Updated: 2026-07-19T03:48:37.206Z
- Language: ja
- Source type: github
- Popularity signal: 66

## Sources

- https://github.com/spillwavesolutions/design-doc-mermaid

## Install

```shell
npx skills add https://github.com/spillwavesolutions/design-doc-mermaid
```

## About

マーメイドアーキテクトスキルは、開発者、アーキテクト、テクニカルライターが包括的なマーメイドダイアグラムと設計ドキュメントを効率的に作成・管理できるようにします。インテリジェントなオーケストレーションとオンデマンドガイドの読み込みを活用することで、このスキルは複雑なシステム、ワークフロー、コード構造の可視化を合理化します。ユーザーが正確で視覚的に魅力的なダイアグラムを生成できるよう支援し、明確なコミュニケーションと最新のドキュメントを確保します。

この強力なクロードコードスキルは、コードからダイアグラムへの生成などの高度な機能を提供し、スプリングブートやファストエーピーアイアプリケーションから直接アーキテクチャの洞察を抽出できます。また、マーメイドダイアグラムを画像形式に抽出、検証、変換するための豊富なPythonユーティリティも含まれており、コンフルエンスのような既存のドキュメントワークフローやツールとの統合が容易です。階層型システムにより、効率的なトークン使用と高速な応答時間が確保され、シームレスな体験を提供します。

エーピーアイを文書化したい場合、システムアーキテクチャを可視化したい場合、あるいはビジネスプロセスを説明したい場合でも、マーメイドアーキテクトは作業を完了するためのツールとテンプレートを提供します。さまざまなダイアグラムタイプ、ユニコード意味記号、高コントラストスタイリングをサポートしているため、ダイアグラムは情報が豊富でアクセシブルになります。このスキルは、構造化された学習パスと例も提供し、ユーザーが詳細な技術ドキュメントの作成にすぐに習熟できるよう支援します。

## Key features

- **インテリジェントなダイアグラム生成**: ワークフロー、インフラストラクチャ、システムコンポーネント、APIフロー向けに、アクティビティ図、配置図、アーキテクチャ図、シーケンス図などのさまざまなMermaidダイアグラムを作成します。
- **コードからダイアグラムへの変換**: 既存のコードベース（例：Spring Boot、FastAPI）や設定ファイルからダイアグラムを自動生成し、アーキテクチャ、配置、シーケンスフローを可視化します。
- **包括的な設計ドキュメントの作成**: アーキテクチャ、API、機能、データベース、システム設計用の事前定義されたテンプレートを使用して、Mermaidダイアグラムが埋め込まれた完全な設計ドキュメントを作成します。
- **Unicode意味記号と高コントラストスタイリング**: 100以上の意味のあるUnicode記号と高コントラストの配色でダイアグラムの明瞭さとアクセシビリティを向上させ、読みやすさを改善します。
- **ダイアグラム管理用Pythonユーティリティ**: Pythonスクリプトを使用してMermaidダイアグラムを抽出、検証、PNG/SVG画像に変換し、バッチ処理やConfluenceなどのツールとの統合をサポートします。

## Use cases

- **ソフトウェアアーキテクチャの可視化**: 開発者やアーキテクトは、コードや設定ファイルからアーキテクチャ図や配置図を生成し、システムコンポーネントやインフラストラクチャを把握できます。
- **APIフローとワークフローの文書化**: テクニカルライターやエンジニアは、詳細なシーケンス図やアクティビティ図を作成して、APIインタラクション、ビジネスプロセス、ユーザージャーニーを説明できます。
- **設計ドキュメント作成の自動化**: チームは、API、システム、機能などさまざまな目的に応じた構造化された設計ドキュメントを、自動的にMermaidダイアグラムを埋め込んで迅速に生成でき、時間の節約と一貫性の確保が可能です。
- **最新の技術文書の維持**: コードや設定からダイアグラムを直接生成し、簡単に画像形式に変換して共有やコラボレーションを行うことで、ドキュメントが常に最新であることを保証します。

## Result preview

このエージェントスキルによって生成された、フードデリバリープラットフォームのシステムに関するマーメイドダイアグラムをご覧ください。

![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg)

![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg)

![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg)

## Result walkthrough

### ステップ1：インストール

スキルをエージェントに追加します。

![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg)

### ステップ2：プロセスを説明

可視化したいワークフロー、システム、またはシーケンスを入力してください。

![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg)

### ステップ3：結果を確認

プロセス記述に基づいて生成されたマーメイドダイアグラムを取得します。

![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg)

## Skill definition

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

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

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

## インストール

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

このスキルを[Skilzマーケットプレイス](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)から即座にインストールします：

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

### 手動インストール

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

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

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

### インストールの確認

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

```bash
# 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シンボルを使用します：

```mermaid
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ユーティリティ

#### 図の抽出

```bash
# 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
```

#### 画像への変換

```bash
# 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スキルシステム（自動）
- ガイドとテンプレート（このスキルに含まれています）

### 検証と画像変換の場合
```bash
# 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リポジトリ](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- [Skilzマーケットプレイスリスティング](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- [Mermaid公式ドキュメント](https://mermaid.js.org/)

---

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

## FAQ

### このスキルはどのような種類のMermaidダイアグラムを生成できますか？

このスキルはアクティビティ図、配置図、アーキテクチャ図、シーケンス図を生成できます。ワークフロー、クラウドインフラストラクチャ、システムコンポーネント、APIインタラクションの可視化をサポートしています。

### コードからダイアグラムへの変換はどのように機能しますか？

このスキルは、コードや設定ファイル（例：Spring Bootのapplication.yml）を解析し、事前定義されたパターンとガイドを使用して、配置図やシーケンス図などの対応するMermaidダイアグラムを自動生成します。

### このスキルで完全な設計ドキュメントを作成できますか？

はい、このスキルにはさまざまな設計ドキュメント（アーキテクチャ、API、機能、データベース、システム）用のテンプレートが含まれています。入力と選択したテンプレートに基づいて、Mermaidダイアグラムが埋め込まれた完全なドキュメントを生成できます。

### Mermaidダイアグラムを生成するための階層型システムの利点は何ですか？

階層型システムは、意図を効率的に解析し、スキルドキュメント全体ではなく必要なガイドとテンプレート（通常2～5KB）のみを読み込みます。これにより、トークン使用量が大幅に削減され、応答時間が短縮されます。

### このスキルにはPythonユーティリティが含まれていますか？

はい、このスキルはMarkdownファイルからMermaidダイアグラムを抽出し、構文を検証し、PNGまたはSVG画像形式に変換するPythonスクリプトを提供します。これらのユーティリティはバッチ処理もサポートしています。

### 検証機能と画像変換機能を使用するための要件は何ですか？

ダイアグラムの検証と画像変換には、npmを通じて\`mermaid-cli\`をグローバルにインストールする必要があります（\`npm install -g @mermaid-js/mermaid-cli\`）。PythonスクリプトはPython 3.7以降が必要です。