要件定義と基本設計・詳細設計 — V字モデルの対応表

要件定義と基本設計・詳細設計。要件と設計の文書、設計図と対応するチェックリスト。

ここまでのこのサイトは、ほぼ全部「作る話」でした。動かして、測って、直す。一人で作るぶんには、それで最後まで行けます。

他人と作ると、そこで止まります。 「何を作るか」が自分の頭の中にしか無いので、レビューできず、分担できず、テストの合否も決められません。仕様の食い違いが見つかるのは、たいてい作り終わってからです。

この記事は、すでに作ってある自分の作品に、後から要件定義・基本設計・詳細設計を書いてみる回です。ゼロから書くと「書き方の作法」の話になってしまうので、動いているものを言葉にし直すという順番にします。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • V字モデルが「工程の絵」ではなく、決めたことと確かめることの対応表であること
  • 要件定義・基本設計・詳細設計が何によって分かれているのか(粒度ではありません)
  • 非機能要件を6つの観点で漏れなく出す方法
  • 要件・設計・テストの対応を機械的に検査できること(トレーサビリティ)
  • ウォーターフォールとアジャイルの違いが「決める順番」ではないこと

この記事でやること

  1. V字を1枚描いて、左と右を対応させる
  2. 自分の作品に、後から要件定義書を書く(機能要件と非機能要件)
  3. 基本設計と詳細設計を、境界を意識して分けて書く
  4. 要件IDを振って、テストのない要件を機械的に見つける(山場)
  5. 手戻りの費用を、自分の作業時間で実感する

先に知る言葉

この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめてあります。

言葉意味
要件定義何を作るかを決める。作り方は決めない
基本設計(外部設計)外から見た形を決める。画面・API・データの形・他システムとのやり取り
詳細設計(内部設計)中の作りを決める。処理の分け方・関数・SQL
非機能要件「速さ」「落ちにくさ」「戻せること」など、機能では書けない要求
トレーサビリティ要件 → 設計 → テストが、IDで辿れる状態のこと

① V字は、工程の絵ではなく対応表

V字モデルを「工程が V の字に並んでいる図」だと思っていると、何の役にも立ちません。大事なのは、左右が横一列で対応していることです。

  要件定義  ────────────────────  受入テスト
    ↓        (利用者が困らないか)      ↑
  基本設計  ────────────────────  総合テスト
    ↓        (外から見た形は合うか)    ↑
  詳細設計  ────────────────────  結合テスト
    ↓        (部品どうしは繋がるか)    ↑
     └────── 実装 ──────  単体テスト
                (1つの部品は正しいか)

左で決めていないことは、右で確かめられません。 「速いこと」を要件に書いていなければ、受入テストで「遅い」と言われても、それは仕様変更です。V字の価値は、この一点にあります。

3つの工程を分けているのは、粒度ではない

「だんだん細かくしていく」と説明されがちですが、それだと境界が引けません。誰に見せて合意する文書かで分かれています。

工程誰と合意するかそこに書いてはいけないこと
要件定義使う人実現方法(「MySQL を使う」は要件ではない)
基本設計使う人+作る人内部の処理(画面に何が出るかは書く。関数名は書かない)
詳細設計作る人——(ここは実装の言葉で書いてよい)

「使う人が読んで判断できるか」で切ると、迷いません。tasks テーブルに created_at を持つかどうかは、使う人には判断できません。だから基本設計より下です。

② 作品に、後から要件定義書を書く

個人開発の回で作ったアプリを題材にします。すでに動いているので、「何を作るか」は決まっています。 それを言葉にし直します。

cd ~/hitokoto
mkdir -p docs
nano docs/requirements.md

機能要件 —— IDを振るのが要点

# 要件定義書

## 機能要件

| ID | 要件 | 理由 |
|----|------|------|
| FR-01 | 利用者は、ひとことを投稿できる | これが無いと成立しない |
| FR-02 | 投稿は一覧で新しい順に見られる | 探す手段が他に無い |
| FR-03 | 投稿者は、自分の投稿だけ削除できる | 消せないと投稿しづらい |
| FR-04 | ログインした人だけが投稿できる | 荒らしを防ぐ |

## 作らないもの(明示的に範囲外)

| ID | 作らないもの | 理由 |
|----|--------------|------|
| NG-01 | 編集機能 | 投稿は短い。消して書き直せば足りる |
| NG-02 | 画像の添付 | 保存先と容量の管理が増える |
| NG-03 | 通知 | 常時接続の仕組みが要る |

「作らないもの」を要件定義書に書くのが一番効きます。 個人開発の回で作らないものリストを先に書いたのと同じで、書いていないと、あとから「当然入ると思っていた」が出てきます。 口約束で外したものほど、後で揉めます。

非機能要件 —— 6つの観点で漏れを潰す

非機能要件は「思いついたものを書く」と必ず漏れます。観点を固定して、1つずつ埋めます。

観点決めることこの作品での例
可用性止まってよい時間・復旧の目標個人利用。停止は許容。復旧目標は 1 日
性能・拡張性同時利用者・応答時間・データ量同時 5 人・一覧 1 秒以内・1 万件まで
運用・保守性監視・バックアップ・ログの保存期間日次バックアップ・ログ 30 日
移行性既存データの持ち込み・切り替え方法移行なし(新規)
セキュリティ認証・権限・通信の暗号化HTTPS・パスワードは bcrypt
システム環境OS・ブラウザ・置き場所Ubuntu 24.04 / VM 1 台
## 非機能要件

| ID | 観点 | 要件 | 確かめ方 |
|----|------|------|----------|
| NFR-01 | 性能 | 一覧の応答が 1 秒以内(1万件時) | 1万件入れて計測する |
| NFR-02 | 可用性 | 復旧目標 24 時間(RTO) | バックアップから復元して測る |
| NFR-03 | 可用性 | 失ってよいデータは 1 日ぶん(RPO) | 日次バックアップの間隔と一致 |
| NFR-04 | セキュリティ | パスワードを平文で保存しない | DB を直接見て確認する |
| NFR-05 | 運用 | ログは 30 日で自動削除 | logrotate の設定を確認する |

「確かめ方」の列が、右側のテストにそのまま化けます。 ここが書けない要件は、たいてい要件になっていません(「使いやすいこと」など)。

RTO と RPO は混同しやすい2つです。 RTO はいつまでに復旧するか、RPO はどこまで戻ってよいか。日次バックアップなら、RPO は最大 24 時間です。「バックアップを取っている」だけでは、この2つのどちらも決まっていません。

③ 基本設計と詳細設計を分けて書く

# 基本設計書

## 画面
| 画面ID | 画面 | 主な項目 | 遷移 |
|--------|------|----------|------|
| SC-01 | 一覧 | 本文・投稿日時・削除ボタン | → SC-02 |
| SC-02 | ログイン | ID・パスワード | → SC-01 |

## API(外部インタフェース)
| API-ID | メソッド | パス | 対応する要件 |
|--------|----------|------|--------------|
| API-01 | GET  | /api/posts      | FR-02 |
| API-02 | POST | /api/posts      | FR-01, FR-04 |
| API-03 | DELETE | /api/posts/:id | FR-03 |

## データ(論理設計)
posts(id, user_id, body, created_at)
users(id, name, password_hash)

ここまでが「使う人と作る人の両方が読む」範囲です。 画面に何が出て、どのURLで何が返るか。それがどう実装されるかは、まだ書きません。

# 詳細設計書

## API-01 GET /api/posts
- 認証: 不要
- SQL: SELECT p.id, p.body, p.created_at, u.name
         FROM posts p JOIN users u ON u.id = p.user_id
        ORDER BY p.created_at DESC LIMIT 100
- 索引: posts(created_at DESC) を使う(NFR-01 のため)
- 異常時: DB 接続失敗は 500。ログに SQL は出さない(NFR-04)

詳細設計に 索引 と「なぜ張るか(NFR-01)」が出てきました。 性能要件は、ここで初めて実装の判断に変わります。要件が設計に効いているという状態が、これです。

④ テストのない要件を、機械で見つける

ここまでは文書を書いただけです。文書は、書いた瞬間から実物とずれ始めます。 ずれを人の目で見つけるのは無理なので、IDの対応を機械に確かめさせます。

cat > docs/trace.csv <<'EOF'
要件ID,設計ID,テストID
FR-01,API-02,TC-001
FR-02,API-01,TC-002
FR-03,API-03,TC-003
FR-04,API-02,TC-004
NFR-01,API-01,TC-010
NFR-02,,TC-012
NFR-03,,TC-013
NFR-04,,TC-011
NFR-05,,
EOF
cat > docs/check_trace.sh <<'EOF'
#!/bin/bash
# 要件定義書に書いた ID が、対応表とテストに全部現れているか調べる
set -euo pipefail
cd "$(dirname "$0")"
ng=0

# 1) 要件定義書にあるのに、対応表に無い ID
grep -oE '\b(FR|NFR)-[0-9]+' requirements.md | sort -u > /tmp/req.txt
cut -d, -f1 trace.csv | grep -oE '\b(FR|NFR)-[0-9]+' | sort -u > /tmp/trace.txt
if ! diff -q /tmp/req.txt /tmp/trace.txt >/dev/null; then
  echo "❌ 要件と対応表が食い違っています"
  diff /tmp/req.txt /tmp/trace.txt || true
  ng=1
fi

# 2) テストIDが空の要件
awk -F, 'NR>1 && $3 == "" { print "❌ テストが無い要件: " $1 }' trace.csv
awk -F, 'NR>1 && $3 == "" { found=1 } END { exit !found }' trace.csv && ng=1

exit $ng
EOF
chmod +x docs/check_trace.sh
./docs/check_trace.sh; echo "終了コード: $?"
❌ テストが無い要件: NFR-05
終了コード: 1

「ログを30日で消す」という要件に、確かめる手段が無いと分かりました。 目で見て気づける量ではないので、この検査が無ければ、リリースまで誰も気づきません。

設計書が腐る問題への答えは「書かない」ではありません。 UML の回で「図はすぐ嘘になる」と書いたのと同じで、コードと突き合わせる仕掛けを1つ持つことです。ここでは ID の対応表がその役をしています。CI に載せれば、ずれた瞬間に落ちます。

⑤ 手戻りが高くつく理由を、自分の時間で確かめる

「後工程ほど修正が高い」と言われても、実感が湧きません。自分で測ってみます。

「削除は論理削除にしたい」と言われた時期直す範囲
要件定義のとき要件定義書の1行
基本設計のとき要件+API 仕様+データ設計
実装のあと上に加えて、SQL・一覧の絞り込み・テスト・投入済みデータの移行
本番稼働のあとさらに、切り替え手順・切り戻し手順・利用者への周知

増えているのは作業の難しさではなく、影響する場所の数です。 だから「早く決める」ことに価値があります。逆に言えば、影響する場所が少ないうちは、決め直しても安い——これがアジャイルの発想です。

ウォーターフォールとアジャイルの違い

ウォーターフォールアジャイル
工程同じ(決める → 作る → 確かめる)
1周の大きさシステム全体で1周機能ごとに小さく何周も
決め直し変更管理の手続きを通す周ごとに決め直す前提
向く場面要件が動かない・関係者が多い要件が動く・小さく出せる

「アジャイルだから設計しない」ではありません。 1周が小さいだけで、V字は毎周まわっています。要件定義を飛ばすと、どちらのやり方でも同じ場所で詰まります。

完成の判定

#確かめること合格の形
1要件にIDが振ってあるFR- と NFR- が全件に付いている
2作らないものが書いてあるNG- が 1 つ以上ある
3非機能が6観点そろっている可用性・性能・運用・移行・セキュリティ・環境
4テストのない要件が無いcheck_trace.sh が 終了コード 0
5設計に「なぜ」が書いてある索引や制約に、対応する要件IDが添えてある

つまずいたところ

要件定義に「MySQLを使う」と書いてしまう

使う人が判断できないものは、要件ではありません。 「1万件で1秒以内」が要件で、そのために MySQL と索引を選ぶのが設計です。ここを混ぜると、あとから「もっと速い別のものに変えたい」となったときに、要件定義書ごと直すことになります。

非機能要件が「安定して動くこと」で終わる

確かめ方が書けないものは、要件になっていません。数字か、手順にします。

✗ 安定して動くこと
✓ 24時間の連続稼働でエラーログが 0 件(負荷は 1 分あたり 60 リクエスト)

設計書を書いたら、実装と食い違った

必ず食い違います。 大事なのは、食い違いに気づける仕掛けがあることです。この記事では ID の対応表がそれで、UML の回では図とコードの突き合わせがそれでした。「更新を忘れない」という気合いは仕掛けではありません。

全部を文書にしようとして終わらない

個人開発なら、要件定義(作らないもの込み)と非機能要件だけで十分に効きます。基本設計は API の表 1 枚、詳細設計は「なぜその索引か」のメモで足ります。文書を増やすほど、腐る面積が増えます。

後片づけ

# docs/ は残しておいてください。次のテスト工程の回でそのまま使います
ls ~/hitokoto/docs

よくある質問

個人開発でも要件定義書は要りますか
全部は要りませんが、作らないものリストと非機能要件の2つは書いておくと効きます。作らないものを書いておくと、途中で機能を足したくなったときに、決めたときの理由と突き合わせて判断できます。非機能要件は、書いていないと「速さ」や「戻せること」を誰も確かめないまま完成にしてしまうためです。逆に画面設計書のような分量の多い文書は、一人なら省いて構いません。
基本設計と詳細設計の境界が、どうしても曖昧になります
「使う人が読んで判断できるか」で切ってください。画面に何が表示されるかは使う人が判断できるので基本設計、その値をどのSQLで取るかは判断できないので詳細設計です。粒度の細かさで分けようとすると、書く人によって境界が動いてしまいます。判断する相手で分けると、レビューを誰に依頼すればよいかも同時に決まります。
アジャイルなら設計書は要らないのではありませんか
1周が小さいだけで、決めてから作るという順番は変わりません。要件定義に相当するものはユーザーストーリーや受入条件として残りますし、非機能要件はむしろ最初に決めておかないと後から入れられません。省けるのは、変更が頻繁な部分の詳細な文書です。何を残して何を省くかを決めているだけで、設計そのものを飛ばしているわけではありません。
トレーサビリティの表は、どこまで細かく作るべきですか
要件IDとテストIDの2列だけでも効果があります。設計IDまで入れると保守が重くなるので、最初は要件とテストの対応だけにしておき、抜けが見つかるようになってから列を足すのが現実的です。大事なのは網羅性ではなく、テストのない要件を機械が見つけてくれる状態を作ることです。
非機能要件の観点は、この6つで足りますか
個人開発や小規模なシステムなら足ります。公的に整理されたものではもっと細かい分類がありますが、最初から細かくすると埋めること自体が目的になります。6つの観点それぞれに1行でも書いてあれば、まったく書かれていない状態より格段に良くなります。足りないと感じた観点だけ、あとから細かくしてください。

まとめ — 理解できたこと

  • V字は工程の絵ではなく、決めたことと確かめることの対応表。 左に無いものは右で確かめられない
  • 3工程を分けるのは粒度ではなく「誰と合意するか」。 使う人が判断できるかで切る
  • 作らないものを書くのが一番効く。 口約束で外したものほど、あとで揉める
  • 非機能要件は観点を固定して埋める。 確かめ方が書けないものは要件になっていない
  • 文書は必ず腐る。 だから、ずれに気づく仕掛け(ID の対応表)を1つ持つ
  • 手戻りが高いのは、影響する場所が増えるから。 アジャイルは1周を小さくして、その数を減らしている

参考リンク

次に読む

この記事は 【第8段階】深掘り の 22 / 30 本目です。

記事
← 前の記事障害対応は切り分けの順番がすべて — わざと壊して直す
→ 次の記事単体・結合・総合・受入テストの違い — 工程ごとの根拠と境界値

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次