· design / rfc
なぜ Umlay を作ったか — UML を Git/クラウド/AI 時代に合わせて置き直す
課題 — 既存 UML ツールの 3 つの不便
UML / ER を図として描くツールは昔から山ほどあります。Mermaid、PlantUML、dbdiagram、 draw.io、Enterprise Architect … それぞれ強みがある一方、ソフトウェアを日々 Git/PR で レビューしている現場では次の3つに不満が残ります。
- バイナリ or 独自形式 — 差分が読めず PR レビューにかけられない。 レビュー対象は最終的に「コード」ではなく「設計図」であるはずなのに、設計図だけが Git ワークフローから外れている。
- 形状情報と意味が混在 — Mermaid/PlantUML のテキストは描画指示であって、 「これは何を表しているか(intent/invariants)」の情報が落ちる。結果、LLM に食わせても 「綺麗に描画できるテキスト」は返ってくるが、その妥当性はレビューできない。
- コード生成と分離 — 図は図で、Prisma / SQL / TS は別々に書く。 設計と実装の乖離が静かに溜まっていく。
Umlay の設計仮説
Umlay は、3つの選択で上の不満に答えています。
- DSL は形状ではなく「正規 IR」を記述する — テキスト DSL (
.umlay) は Prisma ライクで人間が書きやすい形をしていますが、 パース直後に JSON Schema で厳格に定義された 正規 IR に変換されます。可視化も・コード生成も・lint も・AI レビューも、 すべて同じ IR に対して行われる。 - 意図を属性として残す —
@intent("...")、@@doc("""...""")、@@md("""...""")のような注釈が「何のためにあるモデルか」「どういう不変条件を守らないといけないか」を 保存します。これらは後段の lint や AI プロンプトに流れます。 - 最初からコード生成器と同居 — Prisma / SQL / TypeScript / tRPC / OpenAPI を同じ IR から出力。図と実装が同じ「ひとつの真実」を参照します。
なぜ Mermaid を fork ではなく新規 DSL なのか
Mermaid は描画 DSL としては素晴らしいですが、上で書いた 「形状ではなく IR」という発想から外れます。fork するより別の層として足したほうが、既存 Mermaid ユーザに 迷惑をかけない設計になりました。Mermaid と Umlay は敵対的ではなく、重なるユースケース では好きな方を使えば良い、と思っています。
AI 協働ループ
LLM に「この仕様で作って」と言うと、だいたい 7〜8割のコードは書けます。残りの 2割は、 言語化されていない intent / invariants / ADR に依存しています。Umlay では これらが @intent / @@md / @@doc として DSL に表現されているので、LLM プロンプトに自動で流し込める。生成されたコードの レビューも、IR の diff を見れば「意味が変わった」「名前だけ変わった」を区別できます。
次の一歩
試すには ブラウザ版エディタ を開いて、 デフォルトサンプルをそのまま編集してみてください。データは端末の外に出ません。 文法や正規 IR の仕様は GitHub で Apache-2.0 公開しています。VS Code 拡張も 0.4.x で、Web エディタと同じビューアを備えています。