設計判断を属人化させないために、DDDの判断フローをWebアプリにしてみた
設計やアーキテクチャについての判断は、結論だけを口頭で共有しても再利用できません。
背景や判断の流れがたどれなければ、組織やチームの知見として残らないからです。
「今回はドメインモデルを作りましょうか」「ここはCQRSまでは不要だと思います」という会話はそのときは納得感があっても、聞いた人が後から別の機能で同じ判断をしようとすると、前提や分岐条件が抜け落ちているため詰まってしまいます。
問題は決定内容を記録していないことではなく、どの条件を見て、どの選択肢を外し、どの状態になったら再検討するのかという判断の流れを、後から別の人がもう一度たどることができないことです。
これを解決するために、必要なときに誰でも同じ条件を選び直し、判断の流れをたどることができるWebアプリを作りました。
設計判断は、口頭説明やドキュメントだけでは伝わりきらない
設計判断を伝える手段として、口頭説明もドキュメントも必要です。ただし、それだけでは扱いづらい情報があります。
- 条件によって判断が分岐する
- 似た方式でも、採用する条件と採用しない条件が違う
- 読み手の状況によって必要な詳細度が変わる
- コード例を見たい場面と、結論だけ知りたい場面が分かれる
これらをすべて文章にすると長くなり、複雑になります。
長いドキュメントは、作っても必要な場面で読まれにくく、結局詳しい人への確認に戻ります。短くすると、今度は判断の根拠が落ちます。
再利用したいのは、単なる方式名ではありません。入力条件、推奨理由、採用しない案、リスク、再検討条件まで含めた判断の流れそのものです。
ここが共有されないと、同じ議論を別の機能で繰り返してしまいます。だから、判断の流れを順にたどれる形にしたいと考えました。
ドメイン駆動設計の判断フローをたどれるWebアプリを作った
作ったのは Design Decision Toolkit という静的Webアプリです。
スマートフォンでも読めるようにしていますが、フローチャート、処理シーケンス、コード例まで確認する場合はPCで見る方が扱いやすいです。
このアプリには、現在2つの入口があります。
- これから方式を決めるための
設計方式判断 - 既存設計を見直すための
設計変更診断
どちらも、入力条件に基づいて判断材料を整理するためのツールです。
設計の正解を自動で出すものではありません。ドメイン駆動設計の考え方を参考にした非公式の判断支援ツールです。
新しく方式を決めるときと、既存設計を見直すときに使う
設計判断で混ざりやすいのは、「これから何を採用するか」と「いまの設計をどう変えるか」です。
新規開発では選びやすい方式でも、既存設計がある場合は、既存データ、公開API、切り戻し、段階移行まで含めて判断する必要があります。
そのため新規の方式選定では、業務領域、業務ロジックの置き方、アーキテクチャ、テスト方針を整理します。一方で既存設計の見直しでは、現行方式を維持できるのか、局所改善で足りるのか、段階的な設計変更が必要なのかを確認します。
同じドメイン駆動設計の話でも、入口を分けないと、初期選定の話なのか、既存設計の移行判断なのかが分かりにくくなるため、アプリ上でも2つの入口を分けました。
これから方式を決めるなら、設計方式判断
設計方式判断 は、これから業務ロジックの実装方式やアーキテクチャを決める時に使います。
たとえば、次のような観点を順に確認します。
- その機能が顧客の選択理由や収益性に直接影響するか
- データ構造や業務ルールが単純か複雑か
- 現在値だけで判断できるか、過去の順番が必要か
- 読み取りと書き込みを分ける必要があるか
- どのテスト方針で守るべきか
ここでは、最初から方式名を選ばせないようにしています。ドメイン駆動設計を知っている人でも、最初に「これは中核領域ですか」「CQRSですか」と聞かれると、答えが方式名に引っ張られます。
先に観察できる事実を確認し、その後で候補を出す形にしました。
既存設計を見直すなら、設計変更診断
設計変更診断 は、すでに動いている設計に違和感が出てきた時に使います。
入口は、現場で起きている課題です。
- 業務ルール変更時に、修正箇所を把握しきれない
- 検索、一覧、集計が目標時間に収まらない
- 業務データの変更理由や経緯を求められる場面が増えている
- 外部送信の失敗対応が、手作業では回らなくなっている
- 内部モデルを変更すると、公開APIや連係データまで変わってしまう
課題を選ぶと、確認候補が絞られます。たとえば業務ルールが散らばっている場合は、現行方式のまま改善できるか、ドメインモデルへ移すべきかを段階的に確認します。
診断結果では、今回の判断、理由、変更前に確認する条件、再判定する条件、次に進む変更手順を出します。ここでも、いきなり設計変更を提案するのではなく、現行方式で整理できる範囲や、まだ判断できない条件も残します。
なぜ操作できる画面にしたのか
この内容は、記事やドキュメントとして書くこともできます。実際、設計判断の考え方は文章で説明できます。
ただし、設計判断は分岐が多く、すべての分岐を文章で並べると読みづらくなります。逆に、主要な分岐だけに絞ると、実務で迷う細部が落ちます。
Webアプリにした理由は、詳細度をUI側で調整できるからです。
- ラジオボタンやチェックボックスで、今の条件だけを選べる
- 必要な条件がそろった時だけ、重い方式を候補に出せる
- 詳細説明、コード例、移行手順を必要な時だけ開ける
- 結果をMarkdownメモとして持ち帰れる
これは、ドキュメントを不要にするという話ではありません。ドキュメントに残す前の判断材料を、読者の状態に合わせて組み立てるための画面です。
判断フローで守った設計方針
このアプリで一番避けたかったのは、ドメイン駆動設計の用語を覚えた人が、方式名だけを早く選んでしまう状態です。
ドメイン駆動設計の用語は重要です。ただし、判断の最初に置くと、現場の事実よりも用語の印象が先に立ちます。そこで、判断フローでは次の方針を置きました。
用語ではなく、観察できる事実から始める
最初の選択肢では、なるべく方式名を出さないようにしました。
たとえば「中核領域か」と聞く前に、顧客が選ぶ理由、収益性、コスト優位に影響しているかを確認します。「イベント履歴式ドメインモデルか」と聞く前に、過去の出来事の順番がないと判断できないかを確認します。
初心者がドメイン駆動設計の用語を知らなくても答えられる状態にしないと、判断フローは学習済みの人だけの道具になります。
重い方式をすぐには提案しない
ドメインモデル、CQRS、イベント履歴式ドメインモデル、送信箱、サーガ、プロセスマネージャーは、いずれも影響範囲の大きい方式です。導入条件を外すと、設計変更そのものが負債になります。
そのため、課題を選んだだけでは重い方式を確定しないようにしました。
たとえば検索が遅い場合でも、最初にCQRSを出すのではなく、SQL、インデックス、取得項目、ページング、キャッシュ、目標応答時間、反映遅延を確認します。外部送信が失敗している場合でも、いきなり送信箱を出すのではなく、保存後の外部送信だけが失敗しているのか、再送が運用で回らない規模なのかを確認します。
方式名は、条件を確認した後に出した方が、過剰な選択を避けやすくなります。
非採用案と再検討条件も出す
設計判断で重要なのは、採用した案だけではありません。
レビューで問われるのは、むしろ次のような点です。
- なぜ別の方式を採用しなかったのか
- いまは過剰だと判断した理由は何か
- どの条件が変わったら再検討するのか
そのため、結果画面では推奨だけでなく、採用しない案、リスク、再検討条件も出します。
これは、判断を硬直させるためではありません。あとから前提が変わった時に、どこから再判定すべきかを明確にするためです。
コード例とメモで持ち帰れるようにする
設計判断は、概念だけでは実装へつながりません。
そこで、代表的なルートではコード例を出すようにしました。コード例は本番コードを生成するためのものではなく、責務の置き場所を確認するための最小例です。
設計変更診断では、変更手順や移行前に決めることも出しています。ドメインモデルへ移す、読み取り用データを追加する、イベント履歴式ドメインモデルへ段階移行する、外部連係を送信箱で扱う、といった判断は、方式名だけでは実装に移せません。
結果はMarkdownメモとしてコピーできます。設計レビュー、ADR、タスク分解の下書きに使う想定です。
実装は静的Webにした
実装は、HTML、CSS、vanilla JavaScriptを中心にした静的Webにしました。フローチャートはSVGを直接描画し、コードのハイライトにはhighlight.js、処理シーケンスにはMermaidを使っています。
理由は、判断ロジックが決定的で、サーバー側の状態を持つ必要がないからです。
このツールで必要なのは、入力条件に対して同じ判断フローを返すことです。ユーザー登録、認証、データベース、アプリケーションフレームワークを入れると、設計判断をたどるという主目的に対して、保存、運用、依存関係の更新という保守対象が増えます。
バックエンド、データベース、認証、ユーザー登録、アプリケーションフレームワークはありません。LLMによる自由診断も使っていません。
現在の実行面は、主に次のファイルで構成しています。
web/index.html
web/styles.css
web/design-change-diagnosis-*.js
web/analytics.js
一方で、静的Webに寄せたデメリットもあります。フローチャート、処理シーケンス、コード例をブラウザ側で表示するため、スマートフォンでは画面が狭く、描画やスクロールが重く感じる場面があります。アカウントや保存機能もないため、前回の判断を後から復元する用途には向きません。
今回は、履歴保存や共有機能よりも、誰でもすぐ開けて、同じ条件から同じ判断の流れをたどれることを優先しました。
設計判断を、説明できる形で持ち帰る
このアプリは、設計の最終決定を置き換えるものではありません。
狙いは、設計判断を説明できる形に分解することです。入力条件、推奨理由、採用しない案、リスク、再検討条件、コード上の責務配置をそろえれば、レビューやADRで議論しやすくなります。
新しく方式を決めるなら、設計方式判断 から始めます。既存設計に違和感があるなら、設計変更診断 から始めます。
設計判断は、頭の中だけに置くと属人化します。文章だけにすると、分岐と詳細度の調整が難しくなります。操作できる判断フローにすると、必要な条件だけを選び、必要な説明だけを開き、結果を持ち帰れます。
設計やドメイン駆動設計に悩む時間を、方式名の暗記ではなく、目の前の業務ルールと変更条件を整理する時間に寄せましょう。
Discussion