仕様書があるのに実装がぶれるのはなぜか？

仕様書は渡してあるのに、実装が思っていたものと違う。
このズレはかなりよく起きます。

でも実際には、誰かが不真面目だから起きるとは限りません。
むしろ、仕様書があることで これで認識はそろっているはず と思い込みやすくなり、仕様書の外に残っていた判断が後からずれとして出ることが多いです。

この記事では、2026年4月29日時点で Atlassian の acceptance criteria、OpenAPI Specification v3.2.0、OpenAPI Initiative の公開情報を確認しながら、仕様書があるのに実装がぶれる理由を実務目線で整理します。
API仕様書の整理そのものから見たい場合は、OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理 もつながります。
プロジェクト全体が途中から崩れる構造まで広げたい場合は、なぜITプロジェクトは途中からぐだぐだになるのか もあわせてどうぞ。

まず結論: 仕様書は「判断をゼロにするもの」ではない

仕様書があっても実装がぶれる一番の理由は、仕様書が 実装判断を完全に固定するもの ではないからです。

多くの仕様書は、主に次を説明します。

• 何を作るか
• どんな入力と出力か
• 画面やAPIの大枠は何か

でも実装では、それ以外にも大量の判断があります。

• 例外時にどうするか
• 空データのとき何を見せるか
• 権限不足のとき何を返すか
• 同時更新をどう扱うか
• どこまでを今回の範囲にするか

この部分が明文化されていないと、人ごとの自然な補完で実装が分かれます。
つまり、ぶれは 仕様書がない からではなく、仕様書の外に残っていた判断が多い ときにも起きます。

仕様書があるのにぶれる理由

1. 仕様書が主に「正常系」しか書いていない

かなり多いのはこれです。
仕様書には、入力して保存して完了する流れは書いてある。
でも実装では、正常系より周辺の方が時間を使います。

たとえば、

• 必須項目が欠けていたらどうするか
• 権限が足りない人が開いたらどうするか
• データが0件なら何を出すか
• 既存データが壊れていたらどうするか

のような論点です。

この部分が抜けていると、開発者、QA、デザイナーがそれぞれ妥当だと思う補完を入れます。
その結果、全部それっぽいがそろっていない 実装になります。

2. 用語がそろっていない

仕様書に書かれた言葉が、人によって違う意味で読まれていることも多いです。

たとえば、

• 公開
• 下書き
• 承認
• 管理者
• 削除

のような言葉です。

これらは一見分かりやすいですが、実装では

• 本当に消すのか、論理削除なのか
• 一般公開なのか、社内だけ見える状態なのか
• 承認済みだが未公開なのか

など、細かい差が効きます。

言葉がそろっていないと、仕様書を読んでも同じ完成形を思い浮かべにくくなります。

3. 優先順位が書かれていない

仕様書に要件は並んでいても、どこまで守るべきか の強弱がないことがあります。

例えば、

• 速度よりも厳密さを優先するのか
• 見た目の整合性より入力完了を優先するのか
• まず社内運用を回すことが目的なのか、外部公開品質まで求めるのか

が不明だと、実装判断は人の価値観に寄ります。

同じ仕様書でも、

• Aさんは保守性を優先
• Bさんは画面体験を優先
• Cさんは納期優先で簡略化

と補完するので、結果がぶれやすいです。

4. 非機能要件が抜けやすい

仕様書は画面やAPIの振る舞いを書きやすい一方で、非機能要件が後回しになりがちです。

たとえば、

• どれくらい速くあるべきか
• ログをどこまで残すか
• 監査が必要か
• どの権限で誰が触れるか
• 障害時に何を優先するか

のような点です。

これがないと、見た目の仕様は合っていても、実装の方向はそろいません。
特に業務システムや管理画面では、機能要件より運用要件でぶれやすいことが多いです。

5. 仕様書が更新されず、口頭の方が新しくなる

仕様書が最初に作られたあと、

• 打ち合わせで方針が変わる
• Slack やチャットで補足が入る
• 現場都合で一部だけ先に変わる

ことはよくあります。

このとき、文書が更新されないままだと、仕様書は 正本 ではなくなります。
すると、

• 仕様書を信じて実装する人
• 直近の会話を信じる人
• 以前の画面を真似る人

が混ざります。

これでは、ぶれない方が難しいです。

6. 仕様書が「共有資料」であって「受け入れ条件」になっていない

Atlassian の acceptance criteria の説明でも、受け入れ条件はステークホルダー間の shared understanding を作るものとして扱われています。
つまり、仕様の説明 と 完了判定 は少し役割が違います。

仕様書があっても、

• 何を満たせば完了か
• どこまでが今回の範囲か
• 何が未対応で許容されるか

が明確でなければ、実装は揺れます。

特に危ないのは、仕様書を読んだ全員が だいたい分かった と感じているが、完了条件を言葉にすると微妙に違う状態です。

API仕様書があってもぶれるのはなぜか

APIでは、OpenAPI のような機械可読な仕様書があるぶん、そろいやすそうに見えます。
実際、OpenAPI Specification も、人間とコンピューターの両方がAPIの能力を理解できるようにする標準として位置づけられています。

それでも、次のような点はぶれやすいです。

• エラーメッセージの粒度
• 省略時のデフォルト挙動
• 権限不足と存在しないIDの返し分け
• 後方互換性の扱い
• 説明文にしか書いていない運用ルール

つまり、形式化された仕様書があっても、境界条件 と 運用判断 が残っていると実装差は出ます。
OpenAPI が弱いのではなく、契約化できていない部分が残るとそこからぶれます。

どうするとぶれを減らしやすいか

1. 受け入れ条件を別で固定する

仕様の説明だけでなく、

• この状態なら完了
• このケースは未対応
• このエラー時はこう見える

まで明文化した方がぶれにくいです。

何を作るか と 何をもってOKにするか を分けるだけでも、実装判断はかなりそろいます。

2. 例外系と状態遷移を書く

正常系だけでなく、

• 失敗時
• 空状態
• 権限違い
• 再実行時
• 更新競合時

を先に書くと、後からの補完が減ります。

画面なら状態遷移、APIならエラーコードや条件分岐まで含めて置くと強いです。

3. 用語集を作る

公開 削除 承認 のような危ない語は、チーム内で定義した方が安全です。
用語のズレは小さく見えて、実装差やテスト差になりやすいです。

4. 非対応範囲を書く

意外と効くのがこれです。

• 今回はCSV出力は対象外
• 監査ログは次フェーズ
• モバイル最適化は対象外

のように、やらないことを書くと、善意の補完を減らせます。

5. 仕様書を正本として更新する

会話で決まった変更が文書へ戻らないと、仕様書はすぐ古くなります。
誰が更新するか、どの文書を正本にするかを決めるだけでも、ぶれ方はかなり変わります。

まとめ

仕様書があるのに実装がぶれるのは、誰か一人が雑だからとは限りません。
仕様書の外に残った判断、正常系に偏った記述、用語の解釈差、非機能要件の抜け、更新されない文書が重なると、ぶれは普通に起きます。

大事なのは、仕様書を増やすことそのものではありません。
受け入れ条件、例外、状態、非対応範囲、更新ルールをそろえて、どこまで文書で固定し、どこから判断が必要か を見えるようにすることです。

仕様書は大事ですが、仕様書だけで実装がそろうわけではない。
この前提を持つだけでも、レビューや合意の置き方はかなり変わります。

参考情報

• Atlassian: Acceptance criteria explained
• OpenAPI Specification: OpenAPI Specification v3.2.0
• OpenAPI Initiative: Home