1. 導入：なぜ設計図をコードで管理するのか？
皆さんは、システム設計図の更新を忘れて「実装と図が食い違っている」という経験はありませんか？画像ファイル（PNGやJPG）で設計図を管理していると、修正のたびにキャプチャを取り直す手間がかかり、レビュー時も「何が変わったのか」が画像を見比べるだけでは非常に分かりにくいものです。
そこで今回紹介するのが「Mermaid.js」です。Markdown内にテキストで図を記述することで、設計図もコードの一部として管理し、Gitの差分としてレビュー可能にする手法を解説します。
2. 基礎知識：Mermaid.jsとDocs as Code
Mermaid.jsとは、テキスト（コード）から図を描画するライブラリです。GitHubやGitLabなどの主要なコードホスティングサービスは、Markdownの中に特定の構文で記述するだけで、自動的に図としてレンダリングしてくれます。
この手法はDocs as Code（ドキュメントをコードのように扱う）という概念に基づいています。「設計図をテキスト化」することで、Gitの差分表示機能を使って「どの線が追加されたか」「どの要素が変更されたか」を、コードと同じようにレビューできるようになります。
3. 実装・解決策：GitHubでの活用手順
GitHubのPull Request（PR）で図を表示するには、Markdownのコードブロックで mermaid という言語名を指定するだけです。
レビュアーは、PRの「Files changed（変更ファイル）」タブを開くだけで、図の変更内容がテキストの差分として表示されるため、レビューの効率が飛躍的に向上します。
4. サンプルプログラム：まずはシーケンス図を描いてみよう
以下のコードを、GitHubのIssueやPRのコメント欄、あるいはMarkdownファイルにコピー＆ペーストしてみてください。自動的にシーケンス図が生成されます。
sequenceDiagram
participant User as ユーザー
participant App as アプリケーション
participant DB as データベース
User->>App: ログインリクエスト
activate App
App->>DB: ユーザー情報の照会
activate DB
DB–>>App: 結果を返却
deactivate DB
alt 認証成功
App–>>User: ダッシュボードを表示
else 認証失敗
App–>>User: エラーメッセージを表示
end
deactivate App
5. 応用・注意点：現場で失敗しないために
注意点：複雑にしすぎない
Mermaidは便利ですが、あまりに複雑な図を描くとテキストが長くなりすぎて可読性が下がります。図は「要点を絞る」ことに徹し、どうしても複雑になる場合は図を分割しましょう。
陥りやすい罠：環境による非対応
社内ツールや特定のIDEでは、Mermaidのレンダリングに対応していない場合があります。その際は「Mermaid Live Editor」などのWebツールにテキストを貼り付けて確認する運用をチーム内で共有しておくとスムーズです。
まとめ
設計図をコードとして管理すれば、実装変更のたびに「図の更新」もセットで行うという文化が自然に定着します。まずは小さなシーケンス図やフローチャートから、皆さんのPRに導入してみてください。
コメント