手を動かして覚える、エンジニアのAI練習帳

Mermaid でシーケンス図を書く — v12 の記法と、AI に下書きさせる手順

公開 2026-10-24 ／ 更新 2026-10-24 ／ 文：ランツ

Mermaid でシーケンス図を書く — v12 の記法と、AI に下書きさせる手順

シーケンス図はテキストで書けます。図形をドラッグする必要はないし、 テキストなので Git で差分が見えます。レビューもプルリクエストでできる。

そして2026年のいまは、白紙から書き始める必要もありません。 既存のコードを AI に読ませて下書きを出させ、人が直す、という手順が現実的になっています。 記法と、その手順の両方を書きます。

先に結論

「先に結論」の内容を図にまとめたもの

最小の1枚

「最小の1枚」の内容を図にまとめたもの

sequenceDiagram と書いて、あとは矢印をつなぐだけです。 参加者を事前に宣言しなくても、矢印に出てきた名前がそのまま並びます。

最小構成

sequenceDiagram
    Customer->>Web: 注文する
    Web->>API: POST /orders
    API-->>Web: 201 Created
    Web-->>Customer: 注文完了

並び順は最初に登場した順です。 思った順番にならないときは、次の participant で先に宣言します。

参加者の書き分け

「参加者の書き分け」の内容を図にまとめたもの

actor と participant

participant は箱、actor は棒人間になります。 長い名前は as で短縮できます。

名前を短縮して並び順を固定する

sequenceDiagram
    actor C as 顧客
    participant Web as Web アプリ
    participant API as API ゲートウェイ
    C->>Web: 注文する

種類を指定する

@{ "type": ... } で見た目の種類を指定できます。 DB を円筒で、キューをキューの形で描けるので、 「この参加者は何なのか」が図を見ただけで伝わります。

DB は円筒、キューはキューの形で描く

sequenceDiagram
    participant API
    participant DB@{ "type" : "database" }
    participant MQ@{ "type" : "queue" }
    API->>DB: SELECT
    API-)MQ: ジョブを積む
type見た目使いどころ
boundary境界UI・外部との接点
control制御コントローラ・オーケストレータ
entity実体ドメインモデル
database円筒DB
collections重なった箱複数インスタンス
queueキューメッセージキュー

box でまとめる

複数の参加者をまとめて囲みたいときは box を使います。 「ここまでが自社システム、ここから先は外部」を一目で示せます。

自社と外部の境界を示す

sequenceDiagram
    box rgb(235,245,255) 自社システム
        participant Web
        participant API
    end
    participant Bank as 決済代行
    Web->>API: POST /orders
    API->>Bank: 与信

メッセージと実行区間

「メッセージと実行区間」の内容を図にまとめたもの

矢印の種類

記法線意味
->>実線・矢印同期的な呼び出し
-->>点線・矢印戻り（レスポンス）
-)実線・開いた矢印非同期（投げっぱなし）
--)点線・開いた矢印非同期の戻り
-x実線・末尾に×失敗・中断
->実線・矢印なし向きを示さない関連

同期と非同期の書き分けができるのがポイントで、 ->> と -) を使い分けるだけで、 レスポンスを待っているのかどうかが図から読み取れるようになります。

実行区間と補足

処理している区間は activate / deactivate で示します。 矢印の後ろに + と - を付ける書き方のほうが短く済みます。

+ と - で実行区間を示す

sequenceDiagram
    Web->>+API: POST /orders
    API->>+DB: INSERT
    DB-->>-API: ok
    API-->>-Web: 201 Created

補足は Note で入れます。

    Note right of API: タイムアウトは 3 秒
    Note over Web,API: ここは同一 VPC 内

制御構造

「制御構造」の内容を図にまとめたもの

分岐・繰り返し・並行

どれも end で閉じます。閉じ忘れが構文エラーの一番多い原因です。

sequenceDiagram
    Web->>API: POST /orders

    alt 在庫あり
        API->>DB: 引当
    else 在庫なし
        API-->>Web: 409 Conflict
    end

    opt クーポンあり
        API->>API: 割引を適用
    end

    loop 商品ごと
        API->>DB: 明細を書き込む
    end

    par 決済
        API->>Bank: 与信
    and 通知
        API-)Mail: 確認メール
    end

    critical DB 接続
        API->>DB: connect
    option タイムアウト
        API->>API: リトライ
    end

    break 在庫切れ
        API-->>Web: 中断
    end
構文用途
alt / else条件分岐
opt条件を満たしたときだけ実行
loop繰り返し
par / and並行処理
critical / option必ず実行する処理と、その例外
break以降を打ち切る

範囲を色で囲う

範囲を色で囲いたいときは rect が使えます。 長い図で「ここからここまでが1トランザクション」を示すのに便利です。 

    rect rgba(0,150,120,.12)
        Web->>API: POST /orders
        API-->>Web: 201 Created
    end

参加者の生成と破棄

「参加者の生成と破棄」の内容を図にまとめたもの

途中で生まれて途中で消えるオブジェクトは、create と destroy で表せます（Mermaid v10.3 以降）。 ワーカーを起動して、終わったら破棄する、といった流れがそのまま書けます。

途中で生まれて途中で消えるオブジェクト

sequenceDiagram
    participant API
    API->>API: ジョブを受理

    create participant W as Worker
    API->>W: 起動

    W-->>API: 完了
    destroy W
    API-xW: 終了

生成できるのはメッセージの受け手だけです。送り手を create することはできません。 破棄は送り手・受け手のどちらでも可能です。

通し番号を振る

「通し番号を振る」の内容を図にまとめたもの

autonumber を1行足すだけで、全メッセージに連番が付きます。 レビューで「3番のところだけど」と言えるようになるので、長い図では入れたほうがいいです。 

sequenceDiagram
    autonumber
    Web->>API: POST /orders
    API-->>Web: 201 Created

開始値と増分も指定できます（v11.15 以降）。 既存のドキュメントの番号体系に合わせたいときに使います。 

    autonumber 10 10

AI に下書きさせる

「AI に下書きさせる」の内容を図にまとめたもの

ここからが本題です。Mermaid はテキストなので、AI に出力させるのに向いています。 ただし投げ方を間違えると、もっともらしいけれど実装と違う図が出てきます。

何を渡すか

一番精度が高いのは実装コードをそのまま渡すことです。 仕様書の文章を渡すと、書かれていない部分を AI が埋めてしまいます。コードなら、書いてあることしかありません。

コントローラ1本、サービスクラス1本、外部APIを叩いている箇所。 この3つを貼れば、だいたい使える下書きが出ます。

プロンプト

そのまま使える形にしたものです。

コードから起こすプロンプト

次のコードを読んで、処理の流れを Mermaid の sequenceDiagram で書いてください。

条件:
- 参加者は、コードに実際に出てくるクラス・サービス・外部APIだけにする。
  推測で参加者を足さない
- レスポンスを待つ呼び出しは ->> 、待たない呼び出しは -) を使う
- 戻り値のある呼び出しは activate / deactivate で実行区間を示す
- 条件分岐は alt、繰り返しは loop、並行処理は par を使う
- エラー時の経路も含める。正常系だけにしない
- コードから読み取れなかった箇所は図に含めず、
  図の後に「確認が必要な点」として箇条書きで出す

--- コード ---
（ここに貼る）

効くのは最後の2つです。 「読み取れなかったことは書くな、代わりに質問として出せ」と指示しておくと、 埋め合わせの推測が減ります。 そして AI は放っておくと正常系だけを描くので、エラー経路は明示的に要求します。

出てきた図の検証

AI の出力をそのままドキュメントに貼るのは避けてください。最低限、次の3つを見ます。

見るところ確認の仕方
構文が通るかMermaid Live Editor に貼る。CI に組み込むなら mmdc（mermaid-cli）でレンダリングして落ちないかを見る
参加者が実在するか図に出てくる名前を、そのままコードベースに grep する。1件も当たらない名前は AI が作ったもの
流れが実装と合うか分岐と例外処理を上から突き合わせる。抜けるのはたいていエラー経路とリトライ
# 構文チェックをコマンドで回す場合
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

直すときは差分で

「全体を書き直して」と頼むと、直してほしくないところまで変わります。 変更点だけを指定して、ほかは触らせないようにします。

差分で直すプロンプト

さきほどの図を、次の点だけ直してください。
ほかの行は変更しないでください。

1. Worker への呼び出しを非同期（ -) ）に変える
2. 決済が失敗したときの経路を alt で追加する
3. DB の参加者に @{ "type" : "database" } を付ける

結局のところ、AI は下書きを速くするだけで、正しさの担保は人の側に残ります。 記法を知らないと、出てきたものが正しいかどうかを判断できません。 最初にひととおり書いてみるのは、結局いまでも近道です。

どこで書いて、どう管理するか

「どこで書いて、どう管理するか」の内容を図にまとめたもの

書ける場所

リポジトリに置く

運用で効くのは、図をコードと同じリポジトリに置くことです。 別のツールに置いた図は、実装が変わったときに更新されずに残ります。 リポジトリに .mmd か Markdown で置いておけば、 プルリクエストの差分に図の変更が出てくるので、レビューの流れに乗ります。

なお Mermaid 12.0 からシーケンス図の既定のテーマと見た目が変わりました。 バージョンを上げたときに図の印象が変わって見えるのはこれが理由です。 以前の見た目に戻したい場合は、テーマと look を明示的に指定すれば従来どおりになります。

アーカイブ一覧に戻る