【初心者応援】徹底解説_Mermaid記法の書き方

初心者応援・徹底解説シリーズ 【初心者応援】徹底解説 Mermaid記法の書き方 「図解を資料に落とし込む技術 要件定義 設計レビュー 公式ドキュメント：mermaid.js.org ／ 根拠論文：ACM CHI 2024 実装 → テスト

WHY — なぜMermaidを学ぶのか 「図がない資料」は、読み手に負担を押し付けている ① 現場のエンジニアは、実はいつも図を描いている ACM CHI 2024の研究では、プログラマーが日常的にコード内へASCII図を書き込み、構造や処理の流れを視覚的に補足している実態が報告 されている。テキストだけでは伝わりにくい関係性を、人は自然と図に頼って補っている。 ② 「コードとしての図」はレビューできる Mermaidで書いた図はテキストファイルなので、Gitで差分管理・プルリクエストレビューが可能。画像で図を管理すると更新の度に手作 業でズレていくが、Mermaidなら仕様変更にコードと一緒に追従できる。 ③ 文系出身エンジニアほど「先に」武器にすべき 設計や仕様の説明を口頭・文章だけでこなすのは経験値がいる。先にMermaidを押さえておけば、関係性を図にして見せるだけで、実装 前のレビューの精度が一段上がる。 【初心者応援】徹底解説 Mermaid記法の書き方 2

WHAT — Mermaidとは何か テキストを書くだけで図になる「Diagram as Code」 Markdownのような簡易記法を書くと、JavaScriptライブラリが解析してSVG図を自動生成するツール。公式サイト：mermaid.js.org flowchart sequenceDiagram classDiagram 業務フロー・処理の分岐 APIの通信・処理の時系列 クラス設計・データ構造 stateDiagram-v2 erDiagram gantt / timeline ステータスの状態遷移 テーブル間のER図 スケジュール・工程表 GitHub / Qiita / Notion / VSCode / Confluence など主要ツールが標準対応 【初心者応援】徹底解説 Mermaid記法の書き方 3

HOW ① — 基本のフローチャート 最初に覚えるのはこの5行だけ flowchart TD A[要件定義] --> B{設計レビュー} B -->|OK| C[実装] B -->|NG| A C --> D[テスト] [ ] 四角＝処理・作業 { } 菱形＝分岐・判断 --> 実線矢印＝通常の流れ -.-> 点線矢印＝補助的な流れ |OK| 矢印上のラベルで分岐条件を明示 TD = Top Down（上から下）。左右に流したい場合は LR（Left to Right）に変えるだけ。ノードのIDは半角英数字、表示名は [ ] の中に日本 語でOK。 【初心者応援】徹底解説 Mermaid記法の書き方 4

図解サンプル① — フローチャート 同じ5行が、そのままこの図になる コード 描画される図 flowchart TD 要件定義 A[要件定義] --> B{設計レビュー} B -->|OK| C[実装] B -->|NG| A C --> D[テスト] NG 設計 レビュー OK 実装 テスト 左のコードをそのまま Mermaid Live Editor に貼ると、右と同じ図が一 瞬で描画されます。ノード名・矢印・分岐ラベルが、そのまま図の要 素に対応しているのがポイントです。 【初心者応援】徹底解説 Mermaid記法の書き方 5

図解サンプル② — シーケンス図 「誰が誰に何を送ったか」が時系列で見える コード 描画される図 sequenceDiagram ユーザー->>API: リクエスト送信 API->>DB: データ取得 ユーザー API DB ①リクエスト送信 DB-->>API: 結果を返却 API-->>ユーザー: レスポンス ②データ取得 ③結果を返却 ④レスポンス 実線（-->>）は要求、点線（-->>の破線）は応答。上から下に読むだ けで、通信の順番がそのまま追えます。 【初心者応援】徹底解説 Mermaid記法の書き方 6

図解サンプル③ — 状態遷移図 「今どの状態か」が一本の流れで見える コード 描画される図 stateDiagram-v2 [*] --> 未着手 未着手 --> 対応中 対応中 --> 完了 完了 --> [*] 未着手 対応中 完了 [*] は「開始」と「終了」を表す特殊な状態。矢印でつないだ順番ど おりに、ステータスが一方向に進んでいくことが一目で分かります。 【初心者応援】徹底解説 Mermaid記法の書き方 7

図解サンプル④ — クラス図 「データ構造とその関係」が箱と線で見える コード 描画される図 classDiagram User class User { +String name +String email + name : String +login() + email : String Order 1 many + id : String } class Order { + login() + createdAt : Date +String id +Date createdAt } User "1" --> "many" Order クラス名・属性（+name等）・メソッド（+login()）が箱の中に整理され、クラス間の関係は線と多重度（1・many）で表現されます。 【初心者応援】徹底解説 Mermaid記法の書き方 8

図解サンプル⑤ — ER図 「テーブル同士のつながり」が線と関係名で見える コード 描画される図 erDiagram USER ||--o{ ORDER : places ORDER ||--|{ ITEM : contains places USER contains ORDER 1 N ITEM 1 N ||--o{ は「1対多（0以上）」を表す記号。読み方を覚えなくて も、ER図として描画されれば関係は直感的に伝わります。 【初心者応援】徹底解説 Mermaid記法の書き方 9

HOW ② — シーケンス図・状態遷移図 「時系列」と「状態」は書き方が変わる ① API通信の時系列 → sequenceDiagram sequenceDiagram ② ステータスの変化 → stateDiagram-v2 stateDiagram-v2 ユーザー->>API: リクエスト送信 [*] --> 未着手 API->>DB: データ取得 未着手 --> 対応中 DB-->>API: 結果を返却 API-->>ユーザー: レスポンス 対応中 --> 完了 完了 --> [*] 使い分けの目安 sequenceDiagram → 「誰が誰に何を送ったか」を時系列で説明したいとき（API設計・障害調査の再現手順） stateDiagram-v2 → 「あるモノの状態がどう変わるか」を説明したいとき（チケットのステータス、注文の流れ） 【初心者応援】徹底解説 Mermaid記法の書き方 10

HOW ③ — 書いたその場で確認する プレビュー環境は3択、迷ったらMermaid Live Editor ① ② ③ Mermaid Live Editor VSCode拡張機能 GitHub / Qiita / Notion mermaid.live にコードを貼るだけでブラウザ 上に即描画。インストール不要で最初の動作 確認に最適。公式サイトからリンクあり。 「Markdown Preview Mermaid Support」を入れ ると、.mdファイル内の ```mermaid コードブ ロックをプレビューでそのまま描画できる。 ```mermaid の言語指定でコードブロックを書 けば、投稿・コミット後にそのまま図として 表示される。追加設定は不要。 うまく描画されないときの3大原因 1. 予約語 end を小文字のノード名やラベルに使ってしまっている 2. ラベル内の記号（( ) : { } など）をダブルクォートで囲んでいない 3. 矢印記号 の前後にスペースが抜けている（A-->B ではなく A --> B） 【初心者応援】徹底解説 Mermaid記法の書き方 11

まとめ Mermaidは「頭の中の関係性」を素早くコード化する武器 1 テキストで書ける図＝Gitで管理・レビューできる図。仕様変更にも追従できる。 2 flowchart / sequenceDiagram / stateDiagram-v2 の3種類を押さえれば、業務資料の大半はカバーできる。 3 Mermaid Live Editorで即確認 → VSCode / GitHub / Qiitaにそのまま貼れる。 公式ドキュメント https://mermaid.js.org/ 参考文献 Chasins, S. et al. "Taking ASCII Drawings Seriously: How Programmers Diagram Code." Proceedings of the 2024 CHI Conference on Human Factors in Computing Systems (ACM), 2024.

• https://mermaid.js.org/