バグの多くは「実装ミス」ではなく「仕様の解釈違い」

本番で見つかるバグを分類してみると、意外と「コードが間違っていた」ケースは少ない。多いのは「PM が想定していた挙動」と「エンジニアが受入条件から読み取った挙動」がズレていたケースだ。この手のバグはテストをいくら書いても防げない。テストは受入条件が正しいことを前提に書かれるからだ。

つまり、受入条件そのものが曖昧なら、そこから作られるテストも実装も同じ曖昧さを引き継ぐ。受入条件は仕様の「最後の防波堤」であり、ここでの書き方が甘いと、あとの工程でどれだけ丁寧に作業しても解釈違いは消えない。しかも厄介なのは、書いた本人は曖昧だと気づいていないことが多い点だ。頭の中では前提を補って読めてしまうため、レビューで初めて指摘されることが多い。

曖昧な受入条件、よくある5パターン

1. 主語がない

悪い例:「削除できること」。誰が削除できるのか（本人／管理者／全員）が書かれておらず、実装者が推測で決めてしまう。良い例:「レポート作成者本人は、自分が作成したレポートを削除できる。作成者以外は削除ボタンが表示されない」。

2. 境界値がない

悪い例:「タイトルは入力必須」。文字数上限、空白のみの入力、絵文字の扱いが不明。良い例:「タイトルは1〜100文字（絵文字は1文字として計算）。空白のみの入力はエラーとする」。

3. エラー時の挙動が書いていない

悪い例:「画像をアップロードできる」。アップロード失敗時にどう見せるかが未定義で、実装者ごとに挙動が変わる。良い例:「アップロードに失敗した場合、エラーメッセージを表示し、フォームの入力内容は保持したまま再試行できる」。

4. 非機能要件が抜けている

件数・速度・同時実行など、機能の「量」に関する条件が書かれていないケース。良い例:「一覧は1ページ最大50件まで表示し、それ以上はページネーションする」のように具体的な数値まで落とす。

5. 「完了」の判定基準がない

悪い例:「ステータスを更新できる」。どの状態からどの状態への遷移が許可されるのか、UI上どこで確認できるのかが曖昧。良い例:「未対応→対応中→完了の順にのみ遷移でき、逆方向の遷移はできない。現在のステータスはカンバンボードの列で確認できる」。

Given/When/Then でその場で直す

上記5パターンは、書いている最中に気づくのが難しい。そこで受入条件を書いたら、必ず Given/When/Then の形に分解してみる。分解できない条件は、たいてい主語か境界値が抜けている。分解自体は数十秒で終わる作業なので、レビューの通過条件に組み込んでもコストは大きくない。

Given: 前提条件（誰が、どんな状態で）
When: 操作・トリガー
Then: 期待される結果（数値・文言・遷移先まで具体的に）

例えば「削除できること」を分解しようとすると、Given が書けないことに気づく。これが曖昧さの検出シグナルになる。レビュー時に「これ、Given/When/Then に分解できますか？」と聞くだけで、実装前に半分近くの解釈違いを潰せる。

Bugoon での実践

受入条件を先に固めても、実装後のバグ報告そのものはゼロにはならない。そこで重要なのが、報告された不具合が「仕様通りに実装されていないのか」「そもそも仕様が曖昧だったのか」を早く切り分けることだ。Bugoon はウィジェット経由でスクリーンショット・アノテーション・操作ステップを添えてバグを報告でき、そのまま GitHub Issue に連携できるため、報告内容と実際の挙動を並べて確認しやすい。

報告に「関連する受入条件」を紐づけられれば、報告時点で仕様バグか実装バグかの切り分けがさらにしやすくなりそうだが、これは現時点では実装されていない発想の一つとして触れるにとどめておく。

曖昧な受入条件を5パターンで潰す