こんにちは、one_inaです。
Claude Codeをはじめとする自律型コードエージェントを利用していると、
凄まじいスピードでコードが生成されていきます。
しかし、あまりの速さにふと立ち止まった時、
「今、システム全体はどう繋がっているんだ？」
と、全体像の把握が追いつかなくなる瞬間があります。
AIは複雑なロジックを数秒で組み上げますが、
人間がそれを理解するには視覚的な情報、 つまり「ダイアグラム」が欠かせません。
そこで行き着いたのが、
「Claude Codeに設計図をマーメイド記法で出力させ、それをNotionにストックする」
という手法です。
テキストを介して思考するAIと、テキストを即座にビジュアル化するNotion。
この2つをマーメイド記法で繋ぐことで、設計と実装が完全に同期する体験を得ることができましたので、本記事で紹介します。
目次
マーメイド（Mermaid）記法とは？
Mermaid（マーメイド）記法とは、
テキストベースのコードで図やチャートを描画するための構文です。
主な特徴は以下の通りです：
- テキストで図を作成： Markdownのようなシンプルな記述で、
フローチャート、シーケンス図、ガントチャートなどを自動生成できます。 - 管理が容易： 画像ファイルではなく
「テキストデータ」として管理できるため、
修正やバージョン管理（Gitなど）が非常に簡単です。 - 幅広いサポート： GitHub、Notion、Obsidian、VS Codeなど、
多くのエンジニアリング・ドキュメントツールで標準的に採用されています。
専門的な描画ソフトを使わずに、
ドキュメント内に素早く図を組み込みたい際に非常に便利な仕組みです。
今回特にお勧めしたいのは以下の特徴です。
- AIとの親和性: バイナリ画像ではないため、Claude Codeが直接書き換えたり、
既存のコードから生成したりできます。 - Notionでの再現性: Notionでは
/mermaidでMermaidブロックを作成でき、
貼り付けたコードが図としてレンダリングされます。
Notionにおける記述例
例：認証シーケンス図
1. 入力するテキスト（コード）
Notionで /mermaid と入力してMermaidブロックを作成し、
以下のテキストを入力します。
sequenceDiagram
participant User as ユーザー
participant App as Claude Code
participant Notion as Notionドキュメント
User->>App: 「設計を図解して」と指示
App->>App: コードを解析
App-->>User: マーメイド記法のコードを出力
User->>Notion: コードを貼り付け
Notion-->>User: ダイアグラムとして表示
マーメイド記法で描ける多彩な表現
マーメイド記法で描けるダイアグラムの種類は非常に豊富です。
ここでは代表的な例をいくつか表示してみます。
（環境やMermaidのバージョンによって、表示できる種類が異なる場合があります。）
1. フローチャート（クラウドネイティブなリクエストルーティング）
単なる処理順序ではなく、
システム全体のトラフィック制御や異常系の分岐を網羅した実戦的なフローです。
【入力するコード】
graph TD
User((ユーザー)) --> LB{Load Balancer}
LB -- HTTP/S --> Auth[API Gateway / Auth]
Auth --> Valid{認証確認}
Valid -- OK --> Cache{Redis Cache}
Valid -- NG --> Reject[401 Unauthorized]
Cache -- Hit --> Respond[Fast Response]
Cache -- Miss --> Logic[Backend Microservice]
Logic --> DB[(PostgreSQL)]
DB --> Logic
Logic --> Respond
style Auth fill:#e1f5fe,stroke:#01579b
style DB fill:#fff3e0,stroke:#e65100
style Reject fill:#ffebee,stroke:#c62828
2. シーケンス図（OAuth2.0 認証フロー）
システム間の複雑なメッセージのやり取りを時系列で整理します。
【入力するコード】
sequenceDiagram
autonumber
participant U as ユーザー
participant A as クライアントアプリ
participant S as 認可サーバー
participant R as リソースサーバー
U->>A: ログインボタン押下
A->>S: 認可リクエスト (Client ID)
S-->>U: ログイン画面表示
U->>S: 認証情報入力
S-->>A: 認可コード発行
A->>S: 認可コード + 秘密鍵 送信
S-->>A: アクセストークン発行
A->>R: トークン付きリクエスト
R-->>A: データ返却
3. クラス図（決済システムのドメインモデル）
抽象クラスやインターフェース、集約関係を用いた、保守性の高い設計図の例です。
【入力するコード】
classDiagram
class PaymentMethod {
<<interface>>
+pay(amount: int) bool
}
class CreditCard {
-String cardNumber
-String expiry
+pay(amount: int) bool
}
class BankTransfer {
-String bankCode
+pay(amount: int) bool
}
class PaymentProcessor {
-PaymentMethod method
+execute(amount: int)
}
PaymentMethod <|.. CreditCard : 実装
PaymentMethod <|.. BankTransfer : 実装
PaymentProcessor o-- PaymentMethod : 集約
【Notionでの表示】
4. 円グラフ（開発工数のビフォー・アフター分析）
Claude Code導入によって、
手動のコーディング工数がどれだけ削減されたかを可視化します。
【入力するコード】
pie title Claude Code導入後の週次工数配分
"AIによる自動コード生成" : 45
"設計・レビュー (人間)" : 30
"要件定義・MTG" : 15
"手動デバッグ" : 10【Notionでの表示】
5. ER図（データベース設計）
データベースの構造を可視化します。Claude Codeに「このスキーマ定義からER図を作って」と頼むと、テーブル間のリレーションが一瞬で作成されます。
【入力するコード】
erDiagram
USER ||--o{ POST : "作成する"
USER {
int id PK
string username
string email
}
POST {
int id PK
string title
string content
int author_id FK
}【Notionでの表示】
6. 状態遷移図（ステートマシン）
注文ステータスや、ユーザーの認証状態など、
複雑なロジックを整理するのに最適です。
【入力するコード】
stateDiagram-v2
[*] --> 注文受付
注文受付 --> 支払い待ち : 注文完了
支払い待ち --> 出荷準備中 : 決済確認
支払い待ち --> キャンセル : 期限切れ
出荷準備中 --> 配達中 : 発送
配達中 --> 完了 : お届け【Notionでの表示】
7. マインドマップ（アイデア整理）
開発前のブレインストーミングや、
機能の洗い出しをClaude Codeと一緒に行う際に便利です。
【入力するコード】
mindmap
root((新機能開発))
フロントエンド
React
Tailwind CSS
バックエンド
Node.js
PostgreSQL
インフラ
AWS
Docker【Notionでの表示】
8. Gitグラフ（ブランチ戦略）
複雑なマージ作業や、リリースフローを説明する際に、
Claude Codeに「今のGitの状態を図解して」と指示して出力させます。
【入力するコード】
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit【Notionでの表示】
参考：マーメイド記法で書き出せる主なダイアグラム一覧
これだけの図が「テキストだけ」で管理できるため、
Claude CodeのようなAIエージェントにとって、
マーメイドは最強の「お絵描き道具」になります。
| カテゴリ | ダイアグラム名 |
|---|---|
| 基本設計 | フローチャート、シーケンス図 |
| 構造設計 | クラス図、ER図（データベース図） |
| 振る舞い | 状態遷移図 |
| プロジェクト管理 | ガントチャート、タイムライン、円グラフ |
| その他 | マインドマップ、Gitグラフ |
このように、設計のあらゆるフェーズをテキストデータとしてNotionに集約できるのが、この組み合わせの最大のメリットです。
Claude CodeからNotionへ：設計図生成のステップ
実際のユースケースに沿って、
Claude Codeを使って設計図をNotionに反映させる際の手順です。
例えば、SQLやテーブルの情報はあるので、
テーブル構造を「横並びの図（graph LR）」として可視化したい、
というユースケースがあるとします。
Step 1: Claude Codeへ解析と出力を依頼
ターミナル上のClaude Codeに対し、
現在の実装をベースに図を作成するよう依頼します。
以下のSQL（テーブル定義）ファイルをClaude Codeに読み込ませ、
「カラム同士が直接繋がる横並びの図」を作らせます。
erDiagram
CUSTOMERS ||--o{ ORDERS : "注文する"
CAMPAIGNS ||--o{ ORDERS : "適用される"
CUSTOMERS {
int customer_id PK
string customer_name
string prefecture
int age
string gender
date registered_at
}
CAMPAIGNS {
int campaign_id PK
string campaign_name
date start_date
date end_date
string channel
}
ORDERS {
int order_id PK
int customer_id FK
int campaign_id FK
date order_date
number amount
}Claude Codeへの指示
「このSQLを解析して*graph LR（フローチャート）でテーブル構造図を書いて。
各テーブルをsubgraphで囲み、主キーから外部キーへ、
カラム単位で線を結んで。Notionで見やすいように横並びにして。」
Step 2: マーメイドコードの取得
Claude Codeが解析を行い、以下のようなテキストを生成します。
Claude Codeは以下のような、カラム同士を紐付けるコードを出力します。
graph LR
direction LR
subgraph CUSTOMERS [CUSTOMERS / 顧客マスタ]
c1["customer_id (PK)"]
c2["customer_name"]
c3["prefecture"]
c4["age"]
c5["gender"]
c6["registered_at"]
end
subgraph CAMPAIGNS [CAMPAIGNS / キャンペーン]
ca1["campaign_id (PK)"]
ca2["campaign_name"]
ca3["start_date"]
ca4["end_date"]
ca5["channel"]
end
subgraph ORDERS [ORDERS / 注文情報]
o1["order_id (PK)"]
o2["customer_id (FK)"]
o3["campaign_id (FK)"]
o4["order_date"]
o5["amount"]
end
%% カラム間のリレーションを定義
c1 --- o2
ca1 --- o3
Step 3: Notionへの貼り付けと可視化
- Notionで
/mermaidと入力し、Mermaid専用のブロックを呼び出します。 - Claude Codeが生成したコードをコピー＆ペーストします。
- ペーストした瞬間、テキストが「設計図」に変わります。
Step 4: 実装変更に伴う更新
コードを変更した際は、再度Claude Codeに
「最新のコードに合わせて、先程のマーメイド図を修正して」と指示します。
「コードを修正したら、設計図のマーメイド記法のテキストもAIに書き換えさせる」
このループにより、ドキュメントの鮮度を常に最新に保つことができます。
まとめ
自律型エージェントであるClaude Codeと、マーメイド記法、そしてNotion。
この3つを組み合わせることで、
「設計書は書くものではなく、コードから自動生成され、Notionで育てるもの」
へと変わります。
AI時代のドキュメンテーションの標準形として、非常におすすめの組み合わせです。
最後までお読みいただきありがとうございました！
この記事を書いた人
