Mermaid x AST x go:generate = コードとドキュメントの完全同期への道（完結編）

サムネイル

はじめに
TL;DR
この記事を読む前に
この記事で伝えたいこと
ビジネスロジック閲覧サイト
去年の宿題
「ビジネスロジック閲覧サイト」の仕組み
「ビジネスロジック閲覧サイト」の仕組み運用のコツ
- 運用フロー
  - GitHub Actions の最小イメージ（同期検知）
「ビジネスロジック閲覧サイト」採用時の注意点
生成AIの性能
将来の展望
まとめ
参考リンク

はじめに

この記事は、DMMグループ Advent Calendar 2025 の 22 日目の記事です。

データ基盤開発部の CDP（Customer Data Platform）グループで、DMM サービス横断の顧客データシステムの開発・運用・保守を担当している渋谷です。

システム開発時には、ビジネスロジックの説明やレビュー、他チーム連携、引き継ぎなどでドキュメントの鮮度維持と共有コスト削減が大きな課題になります。

設計フェーズで一生懸命ドキュメントを書いたものの、開発フェーズに入ってコードが増えていくにつれて、ドキュメント更新が追いつかなくなります。

その結果、ドキュメントが実態と乖離し、陳腐化してしまいます。

ドキュメントが陳腐化すると、レビューや引き継ぎのたびに「結局コードを読む」しかなくなり、説明コストが雪だるま式に増えていく、という悪循環に陥ります。

去年の DMM グループ Advent Calendar 2024 では、その解決の第一歩として次の記事を書きました。

「Mermaid x AST x 生成AI = コードとドキュメントの完全同期への道」

今年はその完結編として、コード変更と同時に「ナビゲーション機能付きビジネスロジック閲覧サイト」を自動生成し、チーム内外でのコミュニケーションコストを下げた仕組みを紹介します。

ぜひ去年の記事と合わせてご覧ください。

TL;DR

Go のビジネスロジックを AST 解析し、Mermaid 記法のフローチャートを自動生成する
生成したフローチャートを「ナビゲーション機能付きビジネスロジック閲覧サイト」として出力し、ビジネスロジックを辿れる形に可視化
ビジネスロジックの流れや分岐を図で共有できるため、レビュー/引き継ぎ/他チーム連携の会話コストを軽減
go:generate + CI により、コード変更とドキュメント更新を同時に実行することで、ドキュメントが陳腐化しない運用を実現

成果物をすぐご覧になりたい方は「ビジネスロジック閲覧サイトのデモ」に飛んでください。

この記事を読む前に

対象読者

ドキュメントが更新されず、結局コードを読みに行ってしまうことに悩んでいるエンジニア
実装とドキュメントの乖離（陳腐化）に悩んでいるエンジニア
他チーム連携/引き継ぎ/レビューで「口頭説明コスト」が増えているエンジニア
Go のビジネスロジック（ユースケース層など）が複雑で、説明が大変なエンジニア

解決したい課題 (去年の再掲)

コードを見慣れていない相手とコードベースで円滑にコミュニケーションを取りたい
ビジネスロジックとドキュメントの乖離を減らしたい
ドキュメントの更新の手間を減らしたい

この記事で扱わないこと

Go の構文を網羅的にフローチャート化すること（コンパイラ相当の完全対応）
DB/外部 API など I/O を含めた逐語的な可視化（情報量が増えにくい領域）
Mermaid そのものの入門（最低限の前提は去年の記事に寄せます）

この記事で伝えたいこと

ビジネスロジックの流れや分岐を図で共有できると、会話コストを軽減できる
さらにナビゲーション機能を持たせると、理解や認識合わせが速くなる
コードコメントを図に流用できると、コード品質とドキュメント品質の両方が向上する
go:generate + CI によって、ドキュメントの鮮度を無理なく保てる

ビジネスロジック閲覧サイト

デモサイト

www.youtube.com

デモサイトも公開しています。

https://shibuya-mizuho.github.io/logic-mermaid-pages/

コード

ビジネスロジック閲覧サイトのコードは、以下の GitHub リポジトリで公開しています。

https://github.com/shibuya-mizuho/logic-mermaid-pages

メリット

このビジネスロジック閲覧サイトでは、Go のビジネスロジックを 辿れるフローチャート として可視化しています。

具体的には、以下のメリットがあります。

ビジネスロジックの流れ・分岐が視覚化され、コードを追うよりも理解してもらいやすい
複雑な条件分岐も図で示せるため、認識ズレが減る
関数コメントや処理コメントが図に出るため、「何をしているか」だけでなく「なぜそうするか」を残しやすい
図の拡大/縮小/リセット機能により、読みやすさが向上
図のノードクリックで呼び出し先へ遷移でき、処理の流れを崩さず追える
関数一覧/検索機能で、目的の処理に素早く辿れる
関数ごとのハッシュ付きURLで共有しやすく、他チーム連携/引き継ぎ/レビューで「ここ見て」を成立させやすい
コード変更と同時にドキュメントが更新されるため、ドキュメントが陳腐化しにくい

実際に運用して得られた効果

1. Go に詳しくない相手との認識合わせが速くなった

Go の書き方（interface の設計やエラーハンドリングの細部）ではなく、「ビジネスロジックの流れ」中心でコミュニケーションが取れるようになり、認識合わせが素早く行えるようになりました。

特に、関数ごとのハッシュリンクを使うことで、実際のコードを読んでもらわなくても「ここを見て」が成立するようになったのが大きいです。

2. 他チーム連携で「複雑な条件分岐」を説明しやすくなった

注文作成ユースケースのように、多くのステップと分岐 があるビジネスロジックでは、複雑な条件分岐 を説明するのが大変です。

この閲覧サイトを使うと、複雑な条件分岐を提示しやすくなり、認識ズレが減りました。

特に、他チームにコードそのものを提供できなくても、ビジネスロジックの流れを図で示せる ため、必要に応じてドキュメントだけ共有して説明できるのが有効でした。

3. コメントを書く癖が"資産化"した

関数コメント・処理コメントが、そのまま図の説明になるため、コメントを書くモチベーションが上がり、結果的に ドキュメントの品質が上がった という効果がありました。

特に、ビジネスロジックの「なぜそうするか」という意図は、コードだけでは伝わりにくいため、コメントで補足できるのは有用です。

4. 「陳腐化しにくい」ことを運用で担保できた

README や Wiki に図を貼るだけだと、どうしても「更新されない」方向に倒れがちです。

go:generate + CI によって、コード変更と同じタイミングで生成物が更新されるため、鮮度の担保を人力の努力から切り離せました。

去年の宿題

去年の記事では、Go コードのビジネスロジックを Mermaid 記法でフローチャート化するコード解析スクリプトを紹介しました。

ですが、Mermaid フローチャートを生成するだけでは、「コード変更時に誰がドキュメントを更新するのか」という根本的な課題は解決できませんでした。

ドキュメントに Mermaid フローチャートを貼り付けるだけでは、ドキュメントが更新する手間 という問題が解決できなかったのです。

さらに言うと、業務時のコミュニケーションで必要なのは、単なるフローチャートではなく、ナビゲーション性を持ったドキュメント です。

例えば、開発や運用時に次のような情報が欲しくなります。

この処理がどこから呼ばれるか（処理同士の関係性）
この分岐の次に何が起こるか（処理の流れ）
関数単位での説明（処理の目的）

そこで今年は、Mermaid フローチャート生成だけでなく、 閲覧UIまで一気通貫で自動生成する 方針を取りました。

「ビジネスロジック閲覧サイト」の仕組み

「ビジネスロジック閲覧サイトの生成」は、下記の四層で構成されています。

トリガー: go:generate（ユースケースに紐づくファイルから起動）
解析: Go AST を走査して Mermaid を組み立てる（Analyzer）
出力: HTML/JS/CSS をテンプレートから生成（Generator）
閲覧 UI: Mermaid レンダリング/関数一覧/検索/クリック遷移/戻る/ズーム

1. トリガー: go:generate で"同期"を強制する

対象ユースケース（例: 注文作成）のファイル先頭に go:generate コメントを置きます。

これにより go generate ./... が走ったタイミングで Mermaid フローチャートも更新される 状態になります。

go:generate 記述例（最小イメージ）

※実際のコマンドはリポジトリ事情に合わせてください。ポイントは「ユースケースに紐づけて生成を起動できる」ことです。

//go:generate sh -c "cd ../../ && go run internal/logic/*.go"
package usecase

import (
    "context"
    "time"

    "github.com/shibuya-mizuho/logic-mermaid-pages/application/service"
    "github.com/shibuya-mizuho/logic-mermaid-pages/application/validator"
    "github.com/shibuya-mizuho/logic-mermaid-pages/domain/entity"
    "github.com/shibuya-mizuho/logic-mermaid-pages/infrastructure/repository"
)

// IOrderCreateUseCase 注文作成ユースケースインターフェース
type IOrderCreateUseCase interface {
    CreateOrder(ctx context.Context, req validator.CreateOrderRequest) (*entity.Order, error)
}

(省略)

2. 解析: Go AST を走査して Mermaid を組み立てる（Analyzer）

Go の AST パッケージを使って、ビジネスロジックコードを解析し、Mermaid フローチャートを書き出します。

ここの基本的なロジックは去年の記事で紹介したとおりですが、いくつか改良を加えています。

今年は Gemini 3 Pro を使って、解析ロジックをより洗練させ、複雑なコードにも対応できるようにしました。

この時に、コメントをノードに埋め込むことで、「何をしているか」だけでなく「なぜしているか」などの意図も図に残せるようにしました。

3. 出力: HTML/JS/CSS をテンプレートから生成（Generator）

解析で得られた Mermaid フローチャートのテキストを、静的サイトのテンプレートに埋め込み、HTML/JS/CSS を生成します。

今年の肝はここです。

図のノード（例: pricingService.Calculate(...)）をクリックすると
対象関数のページへ遷移できる

これを実現するために、下記の仕組みを導入しました。

解析側で「このノードはどの関数呼び出しを含むか」を記録する
Mermaid の click ディレクティブを出力に追加する
フロント側で navigateToFunction() を受けて該当関数を表示する

また、関数への直接リンクを URL ハッシュで実現し、外部共有やドキュメント内リンクも可能にしました。

そのほかに、以下の機能も実装しています。

関数一覧（パッケージ単位でグルーピング）
検索（関数名だけでなくコメントも対象）
Backspace で戻る（読み進め→戻るを高速化）
ズーム（SVG をスケールして読みやすくする）
「ドキュメント化されていない関数」へ飛ぼうとしたときの通知

これらの機能は実際に運用しながら Gemini 3 Pro に相談して実装してもらいました。

※クリック遷移のため、Mermaid の securityLevel は loose にしています。

社外公開や不特定入力を扱う場合は、ここは必ず見直しが必要です（後述）。

4. 閲覧UI: "静的サイト"として出力する（HTML/JS/CSS）

生成物を「単一HTML + アセット」に寄せると、配布とホスティングが急に楽になります。

docs/logic/
  index.html ... 関数一覧・表示領域
  assets/
    functions.js ... 関数メタデータ + Mermaid コード
    navigator.js ... 関数検索・遷移・ズーム・履歴
    mermaid-init.js ... Mermaid初期化
    styles.css ... UI整形

「関数メタデータ（名前/コメント/呼び出し関係）+ Mermaidコード」を JS 内にまとめたことで、検索/遷移/ハッシュリンクが実装しやすくなりました。

  // assets/functions.js
  // 関数メタデータ（検索・遷移用）と Mermaid コードをひとまとめにします。
  "service.CartService.ValidateCartItems": {
    "calledFunctions": [
      "s.inventoryRepo.GetStock"
    ],
    "comments": "ValidateCartItems カートアイテムの有効性を検証",
    "fileName": "application/service/cart.go",
    "fullName": "service.CartService.ValidateCartItems",
    "functionName": "ValidateCartItems",
    "mermaidCode": "flowchart TD\n    N1([\"`**CartService.ValidateCartItems**`\"])\n    N2{{\"for _, item := range cart.Items\"}}\n    N3{{\"商品が利用可能かチェック\\nitem.Product == nil\"}}\ (省略) \"\n",
    "packageName": "service",
    "receiverType": "CartService"
  },

CartService.ValidateCartItems 1

※現時点では、フローチャートのエクスポート機能がなくスクリーンショットに頼っているため、上図のように長い図が切れてしまいます。

　将来的には、Mermaid フローチャート全体の画像エクスポート機能を追加したいと考えています。

「ビジネスロジック閲覧サイト」の仕組み運用のコツ

フローチャートの読みやすさは、コードの書き方にも依存します。

ユースケースは "上から順" を意識して書く（ステップ番号は強い）
失敗時は早期 return（分岐が整理される）
ループや複雑な条件式を肥大化させない（図が壊れる）
重要な判断（在庫引当/確定、ロールバック、通知の扱い）はコメントで意図を書く

結果として、読みやすいコード = 読みやすい図になります。

デモの注文作成ユースケースも、意図的に「順番が読める」ようにしています。

バリデーション
顧客取得
カート取得
カート検証
在庫引当
価格計算
クーポン検証・適用
決済
配送手配
注文作成・保存
在庫確定
クーポン使用済み
カートクリア
通知（非同期）

この「番号付きステップ」は、そのまま図になったときに強いです。

（図のノードが"何のための処理か"を説明できる）

運用フロー

ドキュメントを「善意で更新する」運用にしないため、CI側で同期を強制します。

開発者はビジネスロジックを修正する（コメントも更新する）
PR をマージするときに CI が走る
CI が go generate ./... を実行し、生成サイトを更新する
生成物を GitHub Pages へデプロイする

GitHub Actions の最小イメージ（同期検知）

「生成物の差分が出たら落とす」を入れるだけでも、陳腐化はかなり抑えられます。

- name: Generate docs
  run: |
    go generate ./...
    git diff --exit-code

※「生成物をリポジトリにコミットするか」「Pages用ブランチへデプロイするか」は、チームの運用ポリシーに合わせて選んでください。

「ビジネスロジック閲覧サイト」採用時の注意点

1. Mermaid `securityLevel: 'loose'` のリスク

クリック遷移のために JavaScript 呼び出しを許可しています。

また、< > などの特殊文字も大小比較などで使うため、あえてエスケープせずに流し込んでいます。

生成対象が信頼できない場合、XSS の入口になり得るので、社外公開や入力混在で注意が必要です。

実運用では、最低限次を押さえると安全側に倒せます。

生成対象を限定する: 生成対象は「自リポジトリ内の Go コード + コメント」のみに絞り、外部入力を混ぜない
コメントをエスケープする: Mermaid へ流し込む文字列（コメント含む）は必ずエスケープする（<, > など）
公開範囲を分ける: 社外公開が必要なら、認証付きで配布する / securityLevel: 'strict' に戻してクリック遷移を諦める、などの判断をする
CSP を入れる: 可能なら Content Security Policy を設定し、スクリプトの実行元を制限する（静的ホスティングでも有効）

2. 全てのGoコードを完全に解析するわけではない

Analyzer によって解析できる流れや分岐の表現は、ビジネスロジックコードに特化させています。

去年の記事でも述べたとおり、DB や外部 API 呼び出しなど、外部I/O 周りのコードは解析しても情報量があまり増えないため、対象外としています。

3. 導入コストは「図が壊れないコード規約」をチームで持てるかに依存する

この仕組みは「読みやすいコードほど図も読みやすい」性質があるため、裏返すと「読みづらいコードは図も読みづらい」です。

導入するなら、最低限の規約（早期 return、巨大条件の分割、コメントの粒度など）をチーム内で合意しておくのが安全です。

生成AIの性能

生成AIによるコード生成支援は、今年も大いに役立ちました。

去年は「ビジネスロジックの解析」の精度を上げるのに苦労しましたが、今年はサラッと乗りこなせるようになっていました。

ただし、最終的に価値を出すのは設計側であることをあらためて痛感しました。

どこを自動化し、どこを人が読む導線にするか
生成物の UX をどう定義するか
セキュリティと運用上の落とし穴をどう潰すか
チームに浸透させるための運用ルールをどう設計するか

などは、AI に任せきりにできるものではなく、人間側の設計力・運用力が最終的な価値を決める ことを再認識しました。

将来の展望

実際に運用してみて、さらに次のような改善点が見えています。

フローチャートのコピー＆ペースト
- Mermaid コードをテキストで直接コピーできるようにし、レビューコメントや他チームへの説明で使いやすくしたい
- Mermaid フローチャートを画像としてエクスポートできるようにしたい
ビジネスルールの可視化
- 例えば「クーポンは1注文につき1回のみ適用可能」「在庫引当は注文確定後にのみ行う」などのビジネスルールを、図に注釈として追加できるようにしたい
バージョン管理との連携
- 現時点では最新のコード状態のみを可視化していますが、過去の版も辿れるようにしてロジックの変更履歴を追いやすくしたい
- Issueなどと紐付けることで「その時点でのビジネスロジックがどうなっていて、なぜ変更されたか」を追いやすくしたい
他チームへの展開
- 他チームでも使ってもらえるように、汎用的な CLI ツールとして切り出したい
- どのようなコードを書けば図が綺麗に出るかのガイドラインを整備したい

まとめ

ドキュメントの陳腐化は意志と努力では止められません。コード変更時に強制的に同期する仕組み作りが重要です。

ビジネスロジックをフローチャート化することで、「ビジネスロジックで会話する」ための共通認識基盤ができます。

AST → Mermaid → 静的サイトまで go:generate でCIに乗せると、ドキュメントの鮮度を無理なく保てます。

コメントは「後回しの贅沢品」ではなく、ドキュメントの品質を上げる資産になります。

ドキュメントが鮮度を保てると、レビュー/引き継ぎ/他チーム連携の会話コストが軽減され、開発効率が上がります。

今後も改善を続け、より良い仕組みを目指していきます。

Merry Christmas & Happy New Year !

参考リンク

Mermaid: https://mermaid.js.org/
go generate / go:generate: https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source
GitHub Pages: https://docs.github.com/en/pages
Content Security Policy (CSP): https://developer.mozilla.org/ja/docs/Web/HTTP/CSP