アーキテクチャ図が「古い」と気づくのは、たいてい最悪のタイミングです。
新しいメンバーがオンボーディング中に「この図、今も合ってますか？」と聞いてくる瞬間。
あるいはインシデント対応の最中に、構成図と実態が違うことに気づく瞬間。
LikeC4 という DSL ツールを使って「コードと乖離しないアーキテクチャ図」をワークフローに組み込む方法を、DSL の書き方・VSCode でのライブプレビュー・GitHub Actions での自動出力まで、実際に動くコード例を交えて紹介します。
読み終わったあとに自分のプロジェクトへ持ち帰れる状態を目指します。
なぜアーキテクチャ図は腐るのか
正直なところ、図が古くなる原因を「エンジニアの意識の問題」にしてしまうのは、診断として間違っています。
意識が高いチームでも図は腐ります。
それはワークフローの設計ミスだからです。
原因は三つに絞れます。
一つ目は 更新コストの非対称性 です。
コードを書き換えるのは開発の本流ですが、図を更新するのは「ついでにやること」です。
draw.io で図を開いて、要素を追加して、PNG に書き出して、Confluence にアップロードして……という手順は、コードを一行直すより何倍も手間がかかります。
この非対称性がある限り、図の更新は後回しになり続けます。
二つ目は レビューフローから切り離されている という問題です。
PR に draw.io ファイルが含まれていなければ、レビュアーは図の変化を差分として見られません。
「コードは変わったけど図は変わっていない」状態がマージされても、誰も気づかない。
Confluence に置かれた図は、PR のライフサイクルとは完全に別の世界で生きています。
三つ目は ツールがリポジトリの外にある ことです。
これが一番根深い問題です。
Git の管理外にあるものは、Git のワークフロー（ブランチ・PR・レビュー・マージ）の恩恵を受けられません。
「誰かがいつか直すはず」という期待は、責任の所在が曖昧なまま時間だけが過ぎる構造を生みます。
図をコードと同じリポジトリに置いて、同じ PR フローに乗せる。
それだけで、この三つの問題は一気に解消に向かいます。
LikeC4 はその「乗せ方」を具体的に提供してくれるツールです。
LikeC4 の三層構造——「図を描く」から「モデルを定義する」へ
LikeC4 は C4 モデルにインスパイアされた DSL で、ソースファイルの拡張子は .likec4 または .c4 です。
発想の核心は「図を描くのではなく、モデルを定義してそこから図を生成する」という点にあります。
DSL は三つの層で構成されています。
specification で要素の種類（actor・system・service など）を定義し、 model で実際の要素と関係を記述し、 views で「どの切り口で可視化するか」を指定します。
この三層が単一の構造化データとして機能するため、model を変えれば全ての views に変更が反映されます。
以下は Web アプリ・DB・外部 API を持つシステムの最小構成例です。
specification {
element actor
element system
element service
element database
}
model {
customer = actor 'Customer' {
description 'サービスを利用するエンドユーザー'
}
saas = system 'SaaS Platform' {
description '自社プロダクト'
api = service 'API Server' {
technology 'Node.js'
}
db = database 'PostgreSQL' {
technology 'PostgreSQL 15'
}
}
payment = system 'Payment API' {
description '外部決済サービス'
}
customer -> saas.api 'リクエストを送る'
saas.api -> saas.db 'データを読み書きする'
saas.api -> payment '決済処理を依頼する'
}
views {
// ランドスケープビュー: システム全体の鳥瞰図
view landscape {
title 'システム全体'
include *
}
// コンテナビュー: SaaS Platform の内部構造に絞る
view saas_detail of saas {
title 'SaaS Platform の内部'
include *
}
}
注目してほしいのは views のブロックです。
landscape と saas_detail という二つのビューを定義していますが、どちらも同じ model ブロックのデータを参照しています。
saas.api -> payment という関係を model に追記すれば、その関係が両方のビューに自動で反映されます。
「図ごとに同じ要素を描き直す」という作業が、構造的になくなります。
プロジェクトが大きくなっても、ファイルを分割して管理できます。
たとえば specs.c4 に specification を、model.c4 に model を、views.c4 に views を置くといった構成です。
全ソースは自動的にマージされて単一のモデルとして扱われるので、チームでファイルを分担して書いても整合性が保たれます。
VSCode 拡張と GitHub Actions で「図の鮮度」をワークフローに組み込む
LikeC4 の VSCode 拡張をインストールして .c4 ファイルを開くと、エディタの横にプレビューペインが現れます。
ファイルを保存するたびに図が即座に更新される、あの感覚はなかなか気持ちいいです。
model に要素を一つ追加してセーブした瞬間、ランドスケープビューにその要素がひょっこり現れる。
Mermaid をローカルでプレビューするより体験がずっとリッチで、インタラクティブに要素をクリックして詳細を確認することもできます。
ただ、ローカルで図がきれいに見えるだけでは「腐らない仕組み」にはなりません。
PR に図の変化が含まれていて、レビュアーが差分を確認できる状態にする必要があります。
そのための最小構成が、GitHub Actions で PNG をエクスポートして成果物として保存するワークフローです。
name: Export LikeC4 Diagrams
on:
pull_request:
paths:
# .c4 ファイルが変更されたときだけ実行する
- 'architecture/**/*.c4'
jobs:
export:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Export diagrams to PNG
uses: likec4/actions@v1
with:
export: png
# .c4 ファイルが置いてあるディレクトリ
path: architecture
# PNG の出力先
output: out/diagrams
# Graphviz のシステムバイナリを使う（CI 環境での安定動作に必要）
use-dot-bin: 'true'
- name: Upload diagram artifacts
uses: actions/upload-artifact@v4
with:
name: architecture-diagrams
path: out/diagrams
このワークフローのポイントは paths フィルターです。
.c4 ファイルが変更された PR だけでトリガーされるので、無関係なコミットで毎回実行されることを防げます。
生成された PNG をアーティファクトとして保存しておけば、PR のページから「この変更でアーキテクチャ図がどう変わったか」を確認できます。
図の更新が PR に含まれる状態になれば、レビュアーは「コードの変更と整合しているか」をレビューの一部として見られます。
これが「図をレビューフローに乗せる」ということの実体です。
Mermaid・draw.io・LikeC4——どの場面でどれを選ぶか
「LikeC4 が一番優れている」という話をしたいわけではありません。
ツールには得意な文脈があるので、プロジェクトの状況に合わせて選ぶのが正直なところです。
Mermaid が向く場面
- README や GitHub の Issue・PR に図をそのまま埋め込みたい
- シーケンス図・フローチャートなど、単一の図を素早く書きたい
- チームの誰もが追加ツールなしで図を読み書きできる状態を維持したい
- 小規模なサービスで、ビューの数が 1〜2 枚程度に収まる
draw.io が向く場面
- 非エンジニアのステークホルダーと一緒に図を編集・レビューする
- 既存の視覚的な資産（過去に作った図）を流用・改変したい
- 自由なレイアウトや細かいデザイン調整が必要な場面
LikeC4 が向く場面
- 複数のビュー（全体・サービス単位・コンポーネント単位）を同一モデルから生成したい
- CI に組み込んで図の自動出力・差分確認をワークフローに乗せたい
- サービスが増えてきて、Mermaid の一枚絵では管理しきれなくなってきた
- インタラクティブな図（クリックして詳細を掘り下げられる）を共有したい
一つ知っておくと便利なのは、LikeC4 の CLI が Mermaid・DrawIO・D2・DOT（Graphviz）へのエクスポートに対応していることです。
「LikeC4 で管理して、Mermaid 形式で出力して README に貼る」という使い方もできます。
「LikeC4 に移行するか Mermaid を続けるか」という二択ではなく、共存させながら段階的に移行する選択肢があります。
実務に持ち込むときの現実的なハードル
ここまで読んで「よし導入しよう」と思ったとしても、実際にチームに持ち込むときにはいくつかの摩擦があります。
正直に書いておきます。
まず DSL の学習コスト です。
specification・model・views の三層構造は、慣れれば直感的ですが、最初は「なぜ specification が必要なのか」というところで手が止まりがちです。
Mermaid のように「書いたらすぐ図になる」感覚とは少し違い、「種類を定義してから要素を作る」という手順を踏む必要があります。
チームに展開するなら、まず自分が一週間使ってみて、よく使うパターンをチームの雛形として用意しておくと摩擦が減ります。
次に 既存の Mermaid 資産との共存 です。
すでに Mermaid で書かれた図がリポジトリに散らばっている場合、全部を .c4 に書き直すのは現実的ではありません。
Mermaid と .c4 は同じリポジトリに共存できるので、「新規サービスの図は LikeC4 で書く」「既存の Mermaid はそのまま残す」という段階的なアプローチが現実的です。
そして チームへの導入ハードル です。
VSCode 拡張を入れてもらう・.c4 ファイルの書き方を共有する・CI の設定を整える、という初期コストは確かにあります。
ただ、これは一度やれば終わりのコストです。
一方で「図が腐り続けるコスト」は毎日じわじわ積み上がります。
冒頭で「図が古いのは意識の問題ではなくワークフローの設計ミスだ」と書きました。
LikeC4 はその設計を直す一手段であって、銀の弾丸ではありません。
DSL を導入しても、誰も .c4 を更新しなければ図は腐ります。
大事なのは「更新しやすい構造を作ること」と「更新が PR フローに乗ること」の両方が揃うことです。
まず一つ、手元にある小さいサービスの構成を .c4 で書いてみてください。
specification に三種類の要素を定義して、model に五つの要素と三つの関係を書いて、views に一枚のランドスケープを作る。
それだけで、LikeC4 が何者かはかなり掴めます。
公式サイト（likec4.dev）にブラウザで動くプレイグラウンドがあるので、インストール不要で試せます。
株式会社ホコサキは山口県宇部を拠点に、Web 制作・業務システム開発・AI 活用支援・DX 推進に取り組んでいます。
アーキテクチャ管理の改善や開発ワークフローの整備について相談したい方は、お気軽にどうぞ。
詳しくは お問い合わせページ からご連絡ください。