先に要点
- 仕様書があるだけでは、実装は自動ではそろいません。
- ぶれやすいのは、例外処理、優先順位、用語の定義、非機能要件、画面やAPIの境界にある細部です。
- 仕様書が 「完成形の約束」 ではなく 「概要メモ」 に近い状態だと、人ごとの補完で実装が分かれやすくなります。
- 防ぐには、仕様書を増やすことより、受け入れ条件、状態遷移、例外、非対応範囲、更新ルールをそろえる方が効きます。
仕様書は渡してあるのに、実装が思っていたものと違う。
このズレはかなりよく起きます。
でも実際には、誰かが不真面目だから起きるとは限りません。
むしろ、仕様書があることで これで認識はそろっているはず と思い込みやすくなり、仕様書の外に残っていた判断が後からずれとして出ることが多いです。
この記事では、2026年4月29日時点で Atlassian の acceptance criteria、OpenAPI Specification v3.2.0、OpenAPI Initiative の公開情報を確認しながら、仕様書があるのに実装がぶれる理由を実務目線で整理します。
API仕様書の基本
API仕様書の整理そのものから見たい場合は、OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理 もつながります。
プロジェクト全体
プロジェクト全体が途中から崩れる構造まで広げたい場合は、なぜITプロジェクトは途中からぐだぐだになるのか もあわせてどうぞ。
まず結論: 仕様書は「判断をゼロにするもの」ではない
仕様書があっても実装がぶれる一番の理由は、仕様書が 実装判断を完全に固定するもの ではないからです。
多くの仕様書が主に説明するのは上の枠です。でも実装では、それ以外にも大量の判断があります。
この部分が明文化されていないと、人ごとの自然な補完で実装が分かれます。
つまり、ぶれは 仕様書がない からではなく、仕様書の外に残っていた判断が多い ときにも起きます。
仕様書があるのにぶれる理由
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
例外系と状態遷移を書く
正常系以外の状態を先に書き、後からの補完を減らす。
- 3
用語集を作る
危ない語をチーム内で定義する。
- 4
非対応範囲を書く
やらないことを書き、善意の補完を減らす。
- 5
仕様書を正本として更新する
会話で決まった変更を文書へ戻す。
1. 受け入れ条件を別で固定する
仕様の説明だけでなく、この状態なら完了 このケースは未対応 このエラー時はこう見える まで明文化した方がぶれにくいです。
何を作るか と 何をもってOKにするか を分けるだけでも、実装判断はかなりそろいます。
2. 例外系と状態遷移を書く
正常系だけでなく、次の状態を先に書くと、後からの補完が減ります。
画面なら状態遷移、APIならエラーコードや条件分岐まで含めて置くと強いです。
3. 用語集を作る
公開 削除 承認 のような危ない語は、チーム内で定義した方が安全です。
用語のズレは小さく見えて、実装差やテスト差になりやすいです。
4. 非対応範囲を書く
意外と効くのがこれです。
- 今回はCSV出力は対象外
- 監査ログは次フェーズ
- モバイル最適化は対象外
のように、やらないことを書くと、善意の補完を減らせます。
5. 仕様書を正本として更新する
会話で決まった変更が文書へ戻らないと、仕様書はすぐ古くなります。 誰が更新するか、どの文書を正本にするかを決めるだけでも、ぶれ方はかなり変わります。
仕様書と実装のぶれのよくある質問
Q. なぜ仕様書通りに実装されない？
A. 仕様書の解釈差、例外ケース未記述、非機能要件不明確、会話で変更したが文書未更新、実装者が独自判断、です。仕様書だけで完全に伝わると思わない方が現実的。
Q. 仕様書を厳密に書けば解決する？
A. 半分解決します。厳密化で減るぶれもありますが、厳密すぎる仕様書は読まれない 副作用も。重要部分は厳密、その他は判断材料 というメリハリが現実的。
Q. 受け入れ条件(Acceptance Criteria)とは？
A. 機能が完成と判断する条件。Given-When-Then 形式が定番。Given: 既存のXがある、When: Yをした、Then: Zとなる、で記述。実装者と検査者が同じ基準で確認 できます。
Q. アジャイル開発でも仕様書は必要？
A. はい、形は違うが必要。ユーザーストーリー + 受け入れ条件 + Wireframe + 設計メモ、を組み合わせます。仕様書ゼロ のアジャイルは混乱の元。
Q. 仕様書をAIで生成できる？
A. 部分的に可能。要件から仕様書草案 画面モックから仕様書 コードから仕様書 などをAIが補助。ただし、業務知識 + 暗黙の前提 は人間が補完必須。
Q. 仕様書とコードのどちらが正本？
A. プロジェクト次第。Spec-first ならコード変更時に仕様書も更新、Code-first ならコメントとテストが事実上の仕様書。どちらか明示して運用ルール化が必須。
Q. 古い仕様書はどう管理する？
A. バージョン管理 + 廃止表記、現行版へのリンク、変更履歴の保持、定期的な棚卸し、で管理。Confluence、Notion、Git で管理するのが現代的。古い仕様書を残したまま放置 は混乱の元。
まとめ
仕様書があるのに実装がぶれるのは、誰か一人が雑だからとは限りません。
仕様書の外に残った判断、正常系に偏った記述、用語の解釈差、非機能要件の抜け、更新されない文書が重なると、ぶれは普通に起きます。
大事なのは、仕様書を増やすことそのものではありません。
受け入れ条件、例外、状態、非対応範囲、更新ルールをそろえて、どこまで文書で固定し、どこから判断が必要か を見えるようにすることです。
仕様書は大事ですが、仕様書だけで実装がそろうわけではない。
この前提を持つだけでも、レビューや合意の置き方はかなり変わります。
参考情報
- Atlassian: Acceptance criteria explained
- OpenAPI Specification: OpenAPI Specification v3.2.0
- OpenAPI Initiative: Home