3行まとめ
- 実装後の仕様変更やエッジケース漏れによる手戻りは、仕様段階での曖昧さが原因
- 実装前に3者（PdM/Dev/QA）で「実例マッピング」を行い、仕様を具体例で検証する
- 「何を作るか」が具体例レベルで確定することで、手戻りの少ない開発を実現する
はじめに
「実装が終わった後に仕様変更が入る」「エッジケースの考慮漏れで作り直しになる」
こうした手戻りは、エンジニアのモチベーションとプロジェクトの予算を大きく削ります。
自動テストやCI/CDの整備が進んだ現在でも、手戻りはなくなりません。なぜなら、自動テストは「コードが仕様通りか」は教えてくれますが、「そもそも仕様が正しいか」までは教えてくれないからです。
本記事では、チームで実践している「コードを書く前の段階で品質を作り込むアプローチ」について紹介します。
なぜ「上流」で止める必要があるのか
ソフトウェア開発には、Barry Boehmが提唱した**「1:10:100の法則」**があります。欠陥修正にかかるコストがフェーズごとに増大するという考え方です。
- 要件・設計段階: 1
- 実装段階: 10
- リリース後: 100
要件定義の段階で「この仕様だと既存機能と矛盾する」と気づければ、修正はドキュメントの数行を書き換えるだけで済みます。
しかし、これが実装後半で見つかった場合はどうでしょうか。
作り込んだクラス設計、ユニットテスト、それらすべてが無駄になり、修正コストは10倍に跳ね上がります。
何より辛いのは、エンジニアが積み上げた「できた」という達成感が、一瞬で徒労感に変わる瞬間です。
実践編：仕様の検証を前工程で行う
多くの現場では、テストは実装後に行うものという認識があります。しかし、「正しく作れているか」の検証だけでは、「正しいものを作ろうとしているか」は検証できません。
私たちが目指しているのは、仕様の検証を実装前に行うことです。
QAやPdMを巻き込み、PRDの段階で「仕様の整合性確認」を行う。
ここからは、チームで実践している3つのプラクティスを紹介します。
1. 3 Amigos：異なる視点を持ち寄る
仕様を決める際、私たちは「3 Amigos（スリー・アミーゴス）」と呼ばれる3つの役割が集まることを重視しています。
- PdM&デザイナー（ビジネス） / エンジニア（開発） / QA（テスト）
仕様が固まりきる前にこの3つの役割が同じテーブルで議論することで、多角的な視点から仕様の穴を見つけ出します。
2. 実例マッピング：曖昧さを「ルールと実例」に分解する
私たちのチームでは､3 Amigos観点で実例マッピングをしています。
これは、仕様を抽象的なままにせず、「具体的な振る舞い（実例）」に落とし込むワークショップです。
4色の付箋で議論を可視化する
実例マッピングでは、4色の付箋を使って議論を構造化します。
| 色 | 役割 | 説明 |
|---|---|---|
| 🟡 黄色 | Story | 議論対象のユーザーストーリー。一番上に配置する |
| 🔵 青色 | Rule | ストーリーを実現するためのビジネスルール・制約 |
| 🟢 緑色 | Example | 各ルールを説明する具体例。「〜の場合は〜になる」 |
| 🔴 赤色 | Question | その場で答えが出ない疑問点・未決事項 |
具体例で「曖昧さ」を炙り出す
例えば、「書店の在庫管理と注文処理」を題材に考えてみましょう。
まず、エンジニアがPRDや事前の議論を踏まえて、自分の理解を説明しています。
🟡 Story: 顧客が書店で本を注文できるようにしたい
Dev: 「PRDを読んだ理解だと、在庫がある本は注文できて、在庫を超える注文はエラーにする、というシンプルな在庫引き当てだと思っています。この認識で合っていますか？」
PdM: 「はい、その理解で合っています」
QAが具体的な数値を使って確認します。
QA: 「具体例で確認させてください。在庫が5冊ある本を2冊注文したら、残りは3冊になる。在庫2冊に対して3冊注文したらエラー。こういうことですよね？」
PdM: 「はい、その通りです」
これでルールと具体例が明確になります。
🔵 Rule: 在庫数以下の注文は受け付ける
🟢 Example: 在庫5冊 → 2冊注文 → 成功、残り3冊🔵 Rule: 在庫数を超える注文はエラーにする
🟢 Example: 在庫2冊 → 3冊注文 → エラー
ここまでは想定通りです。続けて、エンジニアが技術的な観点から問いかけます。
Dev: 「もう1点確認です。在庫が1冊のとき、AさんとBさんがほぼ同時に注文ボタンを押した場合はどうしますか？」
PdM: 「先に処理された方が成功、後からの方はエラーにしたいです。ただ、エラーメッセージの文言やUXはまだ詰めていないので、そこは持ち帰らせてください」
このように、基本仕様は固まっていても、実装観点で初めて浮かび上がる論点があります。その場で決められない疑問は、赤い付箋に記録します。
🔴 Question: 同時注文で在庫切れになった場合のエラーメッセージとUXは？
補足: 上記はあくまで「異なる視点から新たな論点が見つかるプロセス」の例示です。実際のセッションでは、エンジニア・PdM・QAと認識を擦り合わせながら、各自の専門性を掛け合わせて抜け漏れを防ぎます。
成果物が「開発可否」を教えてくれる
セッションを終えると、以下のようなホワイトボードになりました｡
🟡 顧客が書店で本を注文できる
│
├─ 🔵 在庫数以下の注文は受け付ける
│ ├─ 🟢 在庫5冊 → 2冊注文 → 成功、残り3冊
│ └─ 🟢 在庫2冊 → 2冊注文 → 成功、残り0冊
│
├─ 🔵 在庫数を超える注文はエラーにする
│ ├─ 🟢 在庫2冊 → 3冊注文 → エラー
│ └─ 🟢 在庫0冊 → 1冊注文 → エラー
│
├─ 🔴 同時注文で在庫切れになった場合のエラーメッセージとUXは？
このマップの状態が、そのまま開発可否の判断材料になります。
- 🔴（赤い付箋）が多い → まだ開発に入るべきではない。調査や意思決定が必要
- 🔵（青い付箋）が多い → ストーリーが大きすぎる。分割を検討する
- 1つのルールに🟢が多い → ルールが複雑すぎる。複数のルールに分解できないか検討する
今回の例では赤い付箋が残っているため、エンジニア持ち帰って調査し、疑問が解消されてから開発に着手します。
なぜ「具体例」が重要なのか
「在庫がなければエラー」という抽象的なルールだけでは、チームメンバーの解釈がずれる余地があります。
- 「在庫0冊」はエラー？ それとも「注文数 > 在庫数」のときだけ？
- 部分的な注文（在庫2冊に対して3冊注文 → 2冊だけ確保）は許容する？
具体的な数値を伴う実例があることで、こうした曖昧さが排除され、「この入力に対してはこの出力」という合意が形成されます。
この合意こそが、後続のテストケース設計やBDDシナリオの土台となるのです。
3. 具体例を「BDDシナリオ」へ昇華させる
実例マッピングで洗い出された「Example（緑の付箋）」は、曖昧さが排除された仕様の結晶です。私たちはこれをさらに、自然言語に近い記述でテストケースを書けるGherkin記法を用いて明確なシナリオとして定義し、認識を固定化しています。
先ほどの議論の結果は、以下のような指示書になります。
Feature: 書店の在庫管理と注文処理
Scenario: 在庫がある本の注文
Given 書店に「Kotlin Guide」が5冊在庫としてある
When 顧客Aliceが「Kotlin Guide」を2冊注文する
Then 注文は正常に受け付けられる
And 「Kotlin Guide」の利用可能在庫は3冊になる
Scenario: 同時注文による在庫競合の防止
Given 書店に「Scala Book」が1冊在庫としてある
When 顧客Aliceが「Scala Book」を1冊注文する
And 同時に顧客Bobが「Scala Book」を1冊注文する
Then 先に処理された注文のみが確定される
And 後から処理された注文は在庫不足エラーとなる
余談：Gherkinファイルが「AIの知識」になった話
実は、この実例マッピングから生まれたGherkinファイルが思わぬ形で活躍しています。
社内で運用しているQ&Aエージェントが、ビジネスサイドからの仕様質問に回答する際、このGherkinファイルを参照しているのです。
Gherkin記法の本来の目的は、ビジネス・開発・QAが同じ言葉で仕様を理解するための「共通言語」 です。自然言語に近い形式で書かれているからこそ、非エンジニアでも読めるし、エンジニアにとっては実行可能なテストの土台にもなる。
ソースコードだけだと、ビジネスロジックが複数ファイルに散らばっていたり、技術的な実装詳細に埋もれていたりして、AIが「この機能は何をするのか」を端的に理解するのが難しい場面があります。
一方、Gherkinファイルは「Given（前提）→ When（操作）→ Then（結果）」という構造で、1つの振る舞いが1つのシナリオとして完結している。
「ビジネスと開発の共通理解のために書いたドキュメントが、AIにとっても最良の知識源になる」
これは、良いドキュメントの本質を示しているのかもしれません。人間が理解しやすい形式は、AIにとっても理解しやすい。逆に言えば、AIが答えられない仕様は、人間にとっても曖昧なまま放置されている可能性があるということです。
おわりに
手戻りを減らすには、実装後のテストだけでなく、実装前の仕様検証が重要です。
3 Amigosで異なる視点を持ち寄り、実例マッピングで曖昧さを具体例に落とし込む。このプロセスを経ることで、エンジニアは「何を作るか」が明確な状態で実装に集中できます。
仕様の曖昧さに悩んでいるチームは、ぜひ一度試してみてください。
参考資料
Discussion