ソフトウェア設計のい・ろ・は

ソフトウェア設計のい・ろ・は

【対象外あり】注意事項

本記事で紹介する方法は 自社開発向け です。 受諾開発などの場合、基本的な考え方は共通していると思いますが具体的な仕様書の書き方は各々独自の方法があるかと思われます。先方の指示に従ってくださいね。

最も伝えたい、10秒で読める結論

ソフトウェア設計をする際は 「そもそもなぜ作らなければいけないのか?」 から考え始めましょう。仕様書に残しておくのもお忘れなく!

そもそもなぜ「設計」する必要があるの?

プロジェクトが成功するか否かは「なぜ・何を・いつ・どうやって作るのか」を開発に関わる人全員がどれだけ解釈の齟齬なく共有できるかにかかっているためです。この中には開発チームだけでなくユーザー等の「開発知識はないけどそのプロジェクトに関わっている人」も含まれます。開発に関わる人全員が理解・共有するためにドキュメントが作成され、これがいわゆる仕様書となります。それっぽく言うと「仕様書を作ってドメイン駆動開発しましょう」となるハズです。
運用・保守面の観点から見ても仕様書のある・なしで作ったモノの寿命は大きく変わります。設計から運用・保守まで全てのフェーズにおいて仕様書の存在は欠かせません。理想論ですけれどね!

具体的な流れ

大きく分けて 4 段階。
  1. 要求獲得(一番大事。いちばんだいじ。)
  2. 要件定義
  3. 外部設計
  4. 内部設計

1. 要求獲得

大事なことなのでもう一度。 一番大事なフェーズです。カジュアルに言えば「ユーザーヒアリング」具体的にはユーザーの潜在的な欲しい物をこちらが引き出すことが目的です。
なぜ大事なのでしょう?ユーザー自身が本当に必要としているモノを全て言語化できているとは限らないからです。例えばあなたは今すごく疲れていて甘いものが食べたい気分だとします。コンビニで裏面のカロリー表記を見ないようにしながらチョコと生クリームたっぷりのスイーツを買ってたらふく食べてお腹いっぱい。するとどうなるでしょう。20分後ぐらいに血糖値の乱高下が起きてもっと眠くなる & 疲れて目も開けられなくなるに違いありません。あなたに真に必要であったものは適度な休息とリポビタン D だったのでした・・・(実話)。
上記の例で言うなら要求獲得はユーザーが今欲しがっている「チョコと生クリームたっぷりのスイーツ」は 本当に必要か?なぜほしいのか?他に手段はないのか? をユーザーと共に探っていき最終的に「本当に必要なものは適度な休息とリポビタン D なんだ!!」と着地することが目標と言えます。その過程を仕様書に残しておくのが要求獲得。
必要な内容は主に以下となります。上から順に考えていくと ◎。
  • 概要(まとめ)
  • 背景(要求獲得したい経緯の説明)
  • 目的(要求獲得で何を「決めたい」か)
  • 対象ユーザー
  • 解決したい課題
  • 目標(何を作るのか)
  • 動機(なぜ作るのか)

要求獲得を怠った場合の「最悪のシナリオ」

ユーザー「本当に欲しい物って実はコレだったわ。仕様から全部直しといて^^」
文字に起こすだけでゾッとするちゃぶ台返しが発生します。それがいつ発生するかはわかりません。運が良ければ設計中の段階で気付くかもしれないし最悪の場合は実装もテストも終わったリリース直前に起きるかも。そうなれば結果は想像するだに容易いですね。納期は間近で仕様書からやり直し、プロジェクトに関わった人数分の屍の山が・・・
こうならないための要求獲得。

誰でも再現可能!?要求獲得をマスターできる「魔法の言葉」

ソースは弊社会長吉崎(以下敬称略)から伺った同じく弊社開発事業部 PM 丸山発のエピソード(素敵でした!)。
ユーザーの期待を超えるアウトプットができれば要求獲得は 200 点満点と言えます。それをどう実現するか?その答えはユーザーの心の中にあり、私達の心の中にはありません。
ユーザーの心の中を聞き出す魔法の言葉が「そもそも」。「そもそもなぜそう思うの?」「そもそもどうしてこのプロダクトが欲しいの?」とユーザーへ深掘りの質問をすることで誰でも再現可能な要求獲得ができるようになります。前の例で言うなら「そもそもなんでチョコと生クリームたっぷりのスイーツが欲しいの?」→「疲れてるから・・・。」→「疲れているなら疲労回復効果の高いものの方がいいね!」という流れが自然とできます。これができるエンジニアはつよつよになれること間違いなし。私もなりたい。

2. 要件定義

なぜそのモノが欲しいのか、何がしたいのかは要求獲得でわかりました。次に「それ、どうやって作ろうか?」を決めていくのが要件定義です。そのモノには何が含まれていて何が含まれないのか?を細かく仕様書に落とし込んでいきます。要求獲得で設定した「解決したい課題」をどう解決するか構想し共有することが目標です。
必要な仕様書の中身はざっと以下のようになるでしょう。
  • 対象ユーザーの種類別に作られたペルソナ
  • ユースケース図
  • (ユースケース記述)※自社開発・100 人未満の開発規模であれば省略可
  • 機能要件(システムの機能に関する要件)
  • 非機能要件(性能、拡張性、運用・保守性、セキュリティなど)
  • 開発計画書(予算の設定・SWOT 分析・コミュニケーションのルール化・コード規則のルール化・チーム内での役割の明確化・マイルストーン、アクティビティ、時間設定・倫理規定・リスクマネジメント等を含む)

3. 外部設計

見た目の設計。この段階で状態管理や各コンポーネントの定義も行っておくと実装がぐっと楽になります。fwywd チームではワイヤーフレーム・デザインカンプ作成に Figma を使用しています。サイトマップは mermaid-js を使用するとリアルに 3 分で完成(※ 実際はプロダクトのボリュームによって前後)します。おすすめ。
  • サイトマップ
  • サイトマップ文章版
  • ワイヤーフレーム
  • デザインカンプ

4. 内部設計

ロジックの設計。UML で対応できる範囲で書くと労せず完成するのでコストパフォーマンス抜群です。
mermaid-js を使用すると Markdown で記述できて大変便利です。作成コストがぐっと小さくなります。
  • DB 設計= ER 図
  • Model ・ ViewModel ・ React Hooks で扱う State = クラス図
  • API を叩いたときの流れを表現する = シーケンス図
  • Unit ・ Integration ・ E2E テストケース
各仕様書の中で最もボリュームが多くなりますが、ここでしっかりロジックを組み立てておくと実装がめちゃくちゃ楽になります。考えも整理でき保守・運用も楽になり一石三鳥です。

5. 用語集

チーム内で認識のすり合わせをしておくべき用語の解説リスト。Markdown でテーブル作ってぽんぽん書いていくと非常に楽です。

これだけは抑えておくべき重要なポイント3か条【※自社開発の場合】

※ あくまで社内で仕様書のルールを決められる場合に限ります。 受諾開発など自社開発以外の環境では先方と定めたお作法に従ってください!

1. レビューの粒度を予め決めておく

各段階でレビューを挟むとよりよい仕様書が生まれます。レビューの粒度を予め決めておけばより効率的に作業できること間違いなし。実際に試してみたところ各フェーズにおいて仕様書が 20・80・100%完成した時点でレビューを行うといい感じでした。

2. 「全て」仕様書に残す

採用したものはもちろん、検討したけれど採用には至らなかったものも「全て」記録して残しておくとあとあと読み返したとき非常に参考になります。採用・不採用に至った経緯や理由も書いておくとより良き仕様書に。

3. 仕様書を GitHub に残す

仕様書は共有されてこそ意味があります。バージョン管理や各種便利機能が利用できることを考えると GitHub に残しておくのがコストパフォーマンス最高の選択肢と言えそうです。
各項目毎にディレクトリを切って README.md を作成しその中に Markdown 方式で書いていくと書く方も読む方も非常に快適。

おすすめ参考図書

全体像・ポイントを掴んで共に設計上手なエンジニアになっていきましょう! 最後におすすめの参考図書を紹介して〆たいと思います。
「設計にチャレンジしてみたくなってきた!もう少し全体的な流れを詳しく知りたいな」というアナタに。
こちらは UML の書き方入門。仕様書を漏れなく網羅する必要のある受諾開発にも完全対応。初めての方でも読みながら作ることができる実践的な一冊です。

【無料配信】fwywd radio で起業家のリアルを配信中!

fwywd radio

キカガク創業者で代表取締役会長の吉崎が 2022 年の 4月から始動した fwywd in 淡路での起業家育成プログラムの裏側を話します。

絶対にここでしか聴くことのできない起業家の裏側をリアルな情報と共に配信しています。