1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kigi316782

UML/ER を Prisma 風 DSL で書いて、AI と協業しながら設計を進める ── Umlay 1.6 の紹介

1
Posted at

はじめに

UML や ER 図を「設計の最初に描いて、すぐ嫌われて、PowerPoint の隅で腐る」という経験はないでしょうか。

UML は概念としては今も強力なのに、ツールが古い・テキストで版管理しづらい・AI と相性が悪いという 3 つの理由で実務から消えがちです。

Umlay は、これを直すために作っているオープンな DSL とツール群です。

  • Prisma 風の薄いシンタックス — model User @aggregate_root { id UUID! @id } のように書ける
  • 正規化された IR (JSON Schema 公開) — レビュー / lint / レンダリング / コード生成の単一正本
  • AI エージェント向けの skill カタログ 8 本 — write-uml / review-uml / evolve-schema / reverse-engineer / change-impact-diff / plan-from-diff / codegen-mapping + 相談窓口の umlay
  • 配布: Web エディタ (umlay.keydrop.net)、VS Code 拡張、@umlay/cli (npm)

本記事は Umlay 1.6 時点の概要と、AI と協業する設計フローを 1 本にまとめたものです。

目次

  1. なぜ "AI 時代の UML" が必要なのか
  2. 5 分でわかる Umlay
  3. AI と協業する 8 つの skill
  4. テストできる仕様 — 構造化 @@inv と lint L046–L049
  5. 概念先行の change-impact diff
  6. インストール (CLI / VS Code / skills)
  7. 次のステップ

なぜ "AI 時代の UML" が必要なのか

設計ツールの選択肢は今ふた極化しています:

  • 手書きの図 (PlantUML / Mermaid / draw.io) — テキスト or GUI で描くが、コードと乖離する
  • コード正本 + 図は副産物 (Prisma / Hibernate / SQLAlchemy + 描画) — 図はキレイだが設計判断(なぜ aggregate_root にしたか / どの ADR で決めたか / どの ADR で変えたか)を表現する場が無い

AI エージェント時代に欲しいのは、その間にある仕組み。

  • 構造 (model / 関係 / view) は機械可読
  • 設計判断 (intent / invariant / 所有者 / コンプライアンス / 信頼度) も機械可読
  • AI が書ける、AI がレビューできる、AI が「これ変える?」を計画できる

これを目指したのが Umlay です。

5 分でわかる Umlay

ECサイトの最小モデルを書いてみます。

@@mode(strict)

namespace shop

enum OrderStatus { DRAFT, CONFIRMED, SHIPPED, CANCELLED }

model Customer @aggregate_root
  @intent("購入者。Cognito sub を主キーに使う")
  @inv("contains(email, '@')") {
  +id      UUID!     @id
  +email   string!   @unique
  +createdAt Timestamp!
}

model Order @aggregate_root
  @intent("発注のアグリゲート。draft → confirmed → shipped の片道遷移")
  @inv("total.amount >= 0")
  @inv("status in ['DRAFT', 'CONFIRMED', 'SHIPPED', 'CANCELLED']") {
  +id          UUID!         @id
  +customerId  UUID!         @ref(Customer.id, onDelete: RESTRICT)
  +status      OrderStatus!  @default(DRAFT)
  +totalAmount decimal!      @inv("totalAmount >= 0")
  +createdAt   Timestamp!

  fn confirm() -> void
    @pre("status == DRAFT")
    @post("status == CONFIRMED")
}

view shop-er @er_diagram { include: shop.* }
view customer-class @class_diagram { include: shop.Customer; refs: 1 }

ポイント:

  • @aggregate_root ステレオタイプ + model レベルの @inv で集約の不変条件を宣言
  • @ref(Customer.id, onDelete: RESTRICT) — Prisma の @relation を 1 行で
  • fn confirm() -> void @pre("...") @post("...") — メソッド契約 (UML の OCL 風)
  • refs: 1 (spec 1.5+) — view に書いたモデルから 1 ホップ先の参照を自動展開して描画

これを umlay check で検証 → SVG レンダリング → Prisma / SQL DDL / TypeScript 型に変換、まで 1 つの DSL から派生します。

AI と協業する 8 つの skill

Umlay の skills/ ディレクトリには Claude Code 等の AI エージェント向けプロンプトが 8 本用意されています。役割を直交分割してあるのがポイント。

skill 入力 出力
umlay (相談窓口) 「Umlay 試したい」 2 質問で適切な skill に振り分ける
write-uml 自然言語要件 初版 .umlay
reverse-engineer Prisma / SQL DDL / TS 型 構造のみ取り込み .umlay + TODO ヘッダ
review-uml .umlay 4 層監査 (S / L / R / W+C) の指摘リスト
evolve-schema 既存 .umlay + 改修要件 後方互換を保った差分 DSL
change-impact-diff 旧 + 新 IR Purpose / Touch / Miss + Risk + Impact + Checklist
plan-from-diff impact レポート phase / PR 分割 / rollback 注記つき実装計画
codegen-mapping IR Prisma / SQL / TS 差分

フロー (新規):

要求定義 → 要件定義 → 基本設計 → 詳細設計 → 実装
   ↓          ↓          ↓          ↓        ↓
write-uml  write-uml  review-uml  evolve-   codegen-
                                  schema    mapping

フロー (既存改修 — round-trip):

schema.prisma / DDL / TS
        ↓   reverse-engineer
   current.umlay (構造のみ)
        ↓   review-uml + 人間で intent 補完
   current.umlay (詳細設計レベル)
        ↓   evolve-schema (改修部分だけ差分)
   next.umlay
        ↓   change-impact-diff → plan-from-diff → codegen-mapping

この役割分割が effective なのは、各 skill の description を Claude が読んで適切なものを auto-invoke するため。「この .umlay をレビューして」と言えば review-uml が、「Prisma を取り込みたい」と言えば reverse-engineer が立ち上がります。

テストできる仕様 — 構造化 @@inv と lint L046–L049

Umlay 1.6.1 (RFC 0049) で invariant が string から struct に進化しました。

model Order @aggregate_root {
  // 文字列形式 (1.5 まで) — 人間向けドキュメント
  @@inv("total >= 0")

  // 構造化形式 (1.6.1+) — 機械検証可能
  @@inv(field: total,    op: ge, value: 0)
  @@inv(field: status,   op: in, values: ["DRAFT", "CONFIRMED", "SHIPPED", "CANCELLED"])
  @@inv(field: createdAt, op: present)

  // テストケースを仕様に同居させる
  @@example(input: { total: -1 }, expect: reject, reason: "non-negative invariant")
  @@example(input: { total: 100, status: "DRAFT" }, expect: accept)
}

これに対して L049 lint が @@example × @@inv の整合性を検証します。

expect: accept なのに invariant を破る、または expect: reject なのに invariant を満たしてしまう例があると warn を出す。仕様書が静かに矛盾する事故を防げます。

ほかにも 1.6.1 で 4 ルール追加 (合計 73 ルール):

ID 用途
L046 @@locked 要素を info で常時可視化 + @@adrRef 推奨
L047 @@boundary.exposes / hides の幽霊参照を検知
L048 PII / GDPR / PCI-DSS タグ付き属性を持つ model に reject @@example 不在
L049 @@example × 構造化 @@inv の整合性

@@compliance(tags: ["PII"])、@@locked(reason: "PCI-DSS") 等のメタデータ (1.6 の RFC 0038–0044) と組み合わせて 「コンプライアンス要件が DSL に書かれていて、AI に渡せて、CI で fail させられる」 のが 2.0 までの目標です。

概念先行の change-impact diff

Umlay の差分機能は git の行 diff ではない のがポイント。

umlay check schema.umlay --stats --json | jq '.byRule[] | select(.severity != "info")'

Web エディタの Diff タブ や VS Code の Diff strip が出力するのは:

  1. Risk 分類 — 🔴 Breaking / 🟡 Caution / 🟢 Safe
  2. Impact マップ — 変更モデルが ref / view / sequence participant のどこから参照されているか名前で全列挙
  3. AI ナラティブ (BYOK LLM) — 固定 3 文構造:
    • Purpose: この変更が実現したいビジネス成果
    • Touch points: 具体的な model / view 名で「波及する場所」
    • Do-not-miss: 素朴な diff 読みでは見落とす 1 点 (migration / cascade / 意味論シフト)
  4. Reviewer checklist — Risk × Impact のクロスから AI 不使用で生成
  5. Hotspot overlay — ER / Class 図に「追加 model = 緑ハロー、変更 model = 橙枠」を重ね描き

これは change-impact-diff skill としても切り出してあるので、PR コメント / Slack / リリースノートにも同じ出力を流せます。

インストール (CLI / VS Code / skills)

CLI

npm i -g @umlay/cli
umlay check schema.umlay
umlay render schema.umlay --view shop-er --out shop.svg
umlay check schema.umlay --stats --json   # ルールごとの発火数

VS Code 拡張

[Marketplace 公開準備中]。今は .vsix から:

git clone https://github.com/umlay/umlay.git ~/src/umlay
# .vsix は reference 実装側のリリースから取得
code --install-extension umlay-vscode-0.5.6.vsix

ハイライト + 73 lint 診断 + リアルタイムプレビュー (refresh ボタン付き) + 19 種スニペット。プレビュー右の Problems パネルは severity (errors / warn / info) と source (parse / IR / spec / lint / risk / warn / compat) の 2 軸で絞り込めます。

Skill (Claude Code)

git clone https://github.com/umlay/umlay.git ~/src/umlay
mkdir -p ~/.claude/skills
ln -s ~/src/umlay/skills/ja/umlay              ~/.claude/skills/umlay
ln -s ~/src/umlay/skills/ja/write-uml          ~/.claude/skills/write-uml
ln -s ~/src/umlay/skills/ja/review-uml         ~/.claude/skills/review-uml
ln -s ~/src/umlay/skills/ja/evolve-schema      ~/.claude/skills/evolve-schema
ln -s ~/src/umlay/skills/ja/codegen-mapping    ~/.claude/skills/codegen-mapping
ln -s ~/src/umlay/skills/ja/reverse-engineer   ~/.claude/skills/reverse-engineer
ln -s ~/src/umlay/skills/ja/change-impact-diff ~/.claude/skills/change-impact-diff
ln -s ~/src/umlay/skills/ja/plan-from-diff     ~/.claude/skills/plan-from-diff

git pull ~/src/umlay で skill 最新版が自動反映。英語版は ja/ を en/ に。

Web (インストール不要)

umlay.keydrop.net — そのまま開いて使える。BYOK で AI Review / AI Generate も使えます (Anthropic / OpenAI / WebGPU の 3 プロバイダ)。

次のステップ

Spec 1.6.x は意図的に freeze 中 (release policy) で、ドッグフード期 に入っています。新しい @@directive を増やすより、実利用で見つかった矛盾を直すフェーズ。

予定:

  • Spec 1.7 (RFC 0050): 30 個の block directive を 4 つの umbrella directive (@@review / @@governance / @@lifecycle / @@contract) に統合
  • Spec 1.8: codegen 拡充 — 構造化 @@inv から runtime バリデータを自動生成、@@example から property-based test を自動生成
  • Spec 2.0: legacy 1.x directive alias を drop

興味を持って頂けたら、GitHub Discussions や Buy Me a Coffee からフィードバックお待ちしています。

参考

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?