ユースケース駆動で要件定義ドキュメントを作成する

本記事について

最近この本を読んで、実際のプロジェクトで使ってみているところです。試行錯誤の真っ最中です。
良さそうな感触はありつつ、結構大変だな〜と思うところもあったので、体感したみた感想を交えて実際の作成方法も紹介していきます。

『ユースケース駆動開発実践ガイド オブジェクト指向分析からSpringによる実装まで』
https://www.amazon.co.jp/dp/B01B5MX2TC/

また、ユースケース駆動開発（ICONIXプロセス）自体は別の方が紹介してくれているので、本記事では詳細は割愛した上で、詳細設計や実装の話は完全に省き、要求定義〜基本設計までの流れについて書いていきます。

https://zenn.dev/tomoeine/articles/2babb554aa0478

前提

• ドキュメントの管理はGithubで行なってます
• VScodeを使ってMarkdownやdrawioで書いてます

ざっくりICONIXプロセス

ICONIXプロセスとは、UMLを描きながら、ユースケースを中心に設計していく手法のことです。
以下の手順で行います。

1. ドメインモデリングを行う：要求事項から簡単な「ドメインモデル図」を、不完全な状態でも良いので素早く作成する
2. ユースケースモデリングを行う：アクター（いわゆるユーザー）が取りうるユースケース全体を「ユースケース図」として作成し、各ユースケースごとの詳細な振る舞いは「ユースケース記述」としてを作成する
3. ロバストネス分析を行う：「ロバストネス図」を作成して要求定義と詳細設計の間を埋める
4. このあとは「テクニカルアーキテクチャ」「詳細設計」「実装」「テスト」と続いていきます

まずは「ドメインモデル図」を作成

VScodeの拡張機能で、drawioで作成しました。
詳細化されていないし不完全な状態ですが、書籍によればこれでOKで、このあと詳細なユースケースを記述していくときに必要に応じてアップデートすれば良いみたいです。

描くまでもないかな〜と思ってましたが、描いてみたら頭の中が改めて整理できたので描いてよかったです。

PlantUMLやMermaidではだめか？
慣れてるならそちらの方が良いと思います。UMLをアップデートしながら設計していくプロセスなので、追加や修正が割と発生しますのでdrawioだと大変かもしれないです。
ただ、私は慣れてなかったですし、処理が複雑だったり図が大きくなりすぎると見辛くなってレイアウトの微調整が大変でした。なので直感的にかつ柔軟にレイアウトを微調整しやすいdrawioに落ち着きました。

次に「ユースケース図」の作成

ドメインモデル図と同様にdrawioで作成しました。
「そのユースケースは、このユースケースの後にできるようになる」といった、ユースケース間の関係を図示できるようになり、UIデザインとの整合性や流れがわかるようになりました。

フォルダ構成を決めてなかった...

このあとは「ユースケース記述」と「ロバストネス図」を作成していくのですが、どのようなフォルダ構成で管理するか設計していませんでした。

色々記事も探しましたが見つからなかったので、自分なりに考えた結果、以下の通りになりました。

docs/
└── requirement/
    ├── image/
    ├── uml/
    │   ├── 1.domainmodel.drawio.png            //ドメインモデル図
    │   ├── 2.usecase.drawio.png                //ユースケース図
    │   ├── ユーザーが〜を新規作成する.drawio.png    //ユースケース別のロバストネス図
    │   ├── ユーザーが〜一覧を開く.drawio.png        //ユースケース別のロバストネス図
    │   └── ...
    ├── README.md                        //ドメインモデル図＋ユースケース図　など
    ├── ユーザーが〜を新規作成する.md         //ユースケース記述
    ├── ユーザーが〜一覧を開く.md             //ユースケース記述
    └── ...

• 何か仕様を確認したいときにrequirementに来たら、ユースケース記述のドキュメントが並んでいる
• READMEにドメインモデル図とユースケース図を埋め込んでおくことで要件の全体感がパッと分かる

というのを意識した結果です。こんな見た目になります↓

「ユースケース記述」と「ロバストネス図」

どちらもユースケースごとに作成し、それぞれを行き来しながら更新していくことで要件定義と詳細設計の間を埋めていくことができます。

「ユースケース記述」の作成

以下のフォーマットに沿ってMarkdownで記述していきました。
これに沿って記述するテキストと、このあと触れるロバストネス図は１枚のドキュメントで見られると良いとのことなので、Markdownファイルの中に画像を埋め込む形にしました。
加えて、「ロバストネス図」だとぱっと見よく分からない人もいそうなので「処理フロー図」と勝手に呼ぶことにしました。

# {ユースケース名}

<details><summary>目次</summary>
<p>

- [{ユースケース名}](#{ユースケース名})
  - [処理フロー図](#処理フロー図)
  - [UI デザイン](#ui-デザイン)
  - [基本コース](#基本コース)
  - [代替コース](#代替コース)

</p>
</details>

## 処理フロー図

![](./uml/{ユースケース名}.drawio.png)

## UIデザイン

- [画面名](Figmaのリンク)
- [画面名](Figmaのリンク)
- [画面名](Figmaのリンク)

## 基本コース

## 代替コース

このとき「ユーザーが〜すると、システムは〜を取得して表示する」といった感じで、ユーザーとシステムの対話になるような記述にするのが大事みたいです。

対話形式で書いてみて良かった点として、システムの振る舞いなのかユーザーの行動なのかが明確になったこと、適当にぼやかして書くと伝わりにくくなり自然と細かく書くようになったこと、設計まで考慮して考える時間が増えたことがあげられます。

「ロバストネス図」の作成

先ほども触れた通り「処理フロー図」と呼ぶことにしています。

ユーザーがそのユースケースを完了させるまでの流れを画面、処理、エンティティで書き、関連しているユースケースと紐付けて相互にリンクさせています。関連するユースケースを紐づけることで、それぞれのユースケース間の関わり方や呼び出し関係なども整理できました。

第１弾を描いて、エンジニアと詰めて、絵を更新して、テキストも直して、デザイナーとも議論して、、、というのを繰り返してブラッシュアップしたので精度は割と高いのかなと思ってます。

ひと通りやってみた感想

良かった点

• 基本的にビジュアルで仕様を整理するので、自分の理解も深まるしメンバーへの説明もしやすい
• 詳細設計の途中まで踏み込むので抜け漏れも少ない（はず）
• UIデザインと処理との整合性チェックがしやすかった
• ユースケース記述ではユースケースの開始から終了まで順番にテキスト化＋ビジュアル化していくので、それ自体がマニュアルにもなるくらいまで記載されることになる（そしてテストケースにもそのまま流用できるはず）

悪かった点

• UMLのレイアウトの微調整が大変（体感的にはほとんどが絵を描く時間）
• ユースケースごとに切り出すことでその機能の全体感が掴みにくくなる
  • 例えば「社員データを新規登録する」「社員データを削除する」と分かれていても、新規登録の部分だけで設計はせず、削除も含めた全体で設計を行うことになった
  • ユースケースのモデリング自体が悪かった可能性もあるが正直よく分からない

まとめ

悪かったこ点にも書きましたが、UMLを描くのが結構大変です。
どの規模でもある程度いけそうな手法だと思いますが、ユースケース数が多かったりそもそも複雑だったりするとかなり時間取られます。

ですが個人的には好感触だったので、引き続き運用も含めてブラッシュアップしていこうかなと思います。