海外の開発担当へ詳しい仕様書を渡したのに、完成した機能が想定と違う。原因を言語の違いだけに求める前に確かめたいのは、文書が実装とテストの判断に使える形になっているかです。画面項目を細かく書いていても、なぜ必要なのか、何を変えてはいけないのか、どの状態なら完了なのかがなければ、担当者は書かれていない部分を推測することになります。

仕様書は、発注側の説明を保存するための文書ではありません。開発担当者が次の作業を選び、テスト担当者が結果を判定し、変更が発生したときに関係者が影響を確かめるための共通の基準です。その役割から逆算すると、必要な情報と、別の資料へ分けた方がよい情報が見えてきます。

実装・検証・変更の判断に使う共通の基準

「誰が読んでも分かる仕様書」を目指すと、すべての背景を一つの文書へ詰め込みやすくなります。しかし、利用者の目的、業務上の決まり、画面の挙動、データ項目、技術方式、テスト方法では、読む人と更新する時期が異なります。一つの長い文書にまとめるより、情報の役割を分け、相互に参照できる形へします。

海外開発で特に意識したいのは、会議へ参加していない人でも判断できることです。口頭説明を前提にせず、仕様書だけで最初の質問と作業を始められる状態を目指します。一方、まだ決まっていない点まで決定済みのように埋めてはいけません。候補、決める人、期限とともに、未確定であることを残します。

仕様書を構成する六つの情報

仕様書の形式は、開発方法や製品によって変わります。以下の六つは固定のテンプレートではなく、情報の漏れや混在を確認するための区分です。

1. 背景と解決したい問題

最初に、誰がどの場面で困っているのか、今回の変更で何を変えたいのかを書きます。「検索機能を追加する」だけでは、何を実装するかしか分かりません。「サポート担当者が問い合わせ中に契約履歴を探す時間を減らすため、顧客名と契約番号から履歴へ移動できるようにする」と書けば、利用者、状況、目的を確認できます。

英国政府のService Manualは、User Storyに利用者、必要なこと、その理由を含めるよう定めています。形式をそのまま使う必要はありませんが、機能名より先に利用者と目的を置く考え方は、仕様の優先順位や代替案を判断する材料になります。

参考：英国政府 Service Manual「Writing user stories」

2. 対象範囲と範囲外

今回作るものだけでなく、作らないものも書きます。たとえば、顧客名と契約番号で検索できるが、住所のあいまい検索は対象外、検索結果から契約内容は編集できない、といった境界です。対象外を省くと、実装を担当する人が善意で機能を広げるか、発注側が後から当然含まれると考える可能性があります。

対象範囲には画面、利用者、データ、対応端末、権限を含めます。範囲外には、今回扱わない操作、将来検討する機能、別システムの責任範囲を置きます。将来案は要件へ混ぜず、別の候補一覧へ分けます。

3. 前提と制約

前提は、仕様を作る時点で正しいとみなしている条件です。制約は、実装を担当する人が自由に変えられない条件です。既存の認証方式を使う、個人情報をログへ出さない、指定した外部サービスの呼び出し上限を超えない、公開日は変更しないなどが該当します。

前提が崩れた場合の連絡先も書きます。「外部のアプリケーション・プログラミング・インターフェース（API）は常に応答する」と置くのではなく、応答しない場合の表示、再試行、記録、相談先を決めます。前提と例外を同じ場所に置くと、異常時の実装を推測へ任せずに済みます。

4. 機能とデータの挙動

機能の説明では、入力、処理、出力、エラー、権限、記録を分けます。画面の文言や配置だけでなく、入力できる値、空の場合、上限を超えた場合、同じ操作を繰り返した場合、権限がない場合の結果を示します。

データ項目には、名称、型、必須か任意か、許容する値、表示形式、保存期間、更新者を付けます。専門用語や社内略語は用語集を作り、同じ概念へ複数の言葉を使わないようにします。日本語と英語を併記する場合は、どちらを正本とするかも決めます。

5. 受け入れ条件

受け入れ条件は、「正しく表示される」「使いやすい」といった評価者によって変わる言葉ではなく、操作後に観測できる結果で書きます。誰が、どの前提で、何をしたとき、何が起きるかを示します。

前提：サポート担当者が検索権限を持ち、顧客Aに有効な契約が2件ある
操作：顧客Aの契約番号で検索する
結果：2件の契約が更新日の新しい順に表示され、編集操作は表示されない

CucumberのGherkin Referenceは、Givenで既知の状態、Whenで操作、Thenで観測できる結果を表します。受け入れ条件をすべて自動テストにする必要はありませんが、前提・操作・結果を分けると、実装者と確認者が同じ例を使えます。

参考：Cucumber「Gherkin Reference」

6. まだ決まっていない点と決定期限

まだ決まっていない点には、問い、選択肢、推奨案、決める人、期限、期限までに決まらない場合の扱いを入れます。「確認中」とだけ書くと、誰が動くか分かりません。「検索履歴の保存期間を30日と90日から選ぶ。情報管理責任者が8月25日までに決定し、決まらなければ保存機能の実装を止める」と書きます。

決まっていない点は仕様書の本文へ散らさず、一覧から関係する箇所へリンクします。決定後は結論だけでなく、選ばなかった案と理由を短く残します。後から同じ議論を繰り返さないためです。

必須・推奨・任意を定義した要求レベル

「できれば」「原則」「必要に応じて」は、書き手と読み手で強さが変わります。仕様書の冒頭で、要求の段階を定義します。たとえば、必須は受け入れに必要、推奨は理由がある場合だけ外せる、任意は実装しなくても受け入れ可能、とします。

インターネット技術の標準文書「Request for Comments 2119」は、要求を必須、推奨、任意などの段階で区別しています。必須は絶対に必要な要件、推奨は外す正当な理由があり得るものの影響を十分に検討する要件、任意は実装しなくても受け入れられる項目です。同文書は、強い要求語を相互運用や危害の防止に本当に必要な場合へ慎重に使うよう求めています。

参考：Request for Comments 2119

日本語の仕様書で英語の大文字を使う必要はありません。「必須・推奨・任意」など、チームが読める表現へ置き換え、意味を先頭で固定します。重要なのは語の見た目ではなく、外した場合に受け入れられるかを同じように判断できることです。

測定と検証ができる要求文

要求文には、主体、動作、対象、条件、測定方法を含めます。「画面はすばやく表示される」ではなく、「利用者が検索を実行してから、結果一覧の先頭10件を2秒以内に表示する。測定環境と対象データは別表に定める」とします。数値を置く場合は、根拠と測定条件も必要です。

米国航空宇宙局（NASA）が公開するSystems Engineering Handbookは、要求を「責任を持つ主体が何を行うか」という能動形で書くよう示しています。さらに、実現を測定・検証できるか、試験の成功基準を記述できるかを確認するチェックリストを公開しました。flexible、easy、sufficient、user-friendly、quicklyなど、検証しにくい語を要求から外す方針も示しています。

参考：米国航空宇宙局「Systems Engineering Handbook Appendix C」

ソフトウェアの仕様でも、「適切に処理する」「柔軟に対応する」という表現だけでは合否を決められません。エラーコードを返す、入力欄の近くに理由を表示する、再試行できる時刻を示すなど、利用者または外部システムから観測できる状態に変えます。

図・動画・外部の資料を正本と結び付ける方法

画面遷移、データの流れ、操作の動きは、文章だけより図や動画の方が短く伝わる場合があります。ただし、画像を貼るだけでは、本文と食い違ったときにどちらが正しいか分かりません。

各資料には、名称、版、更新日、更新者、仕様書の本文との優先関係を付けます。デザインのリンクは特定のページやフレームへ向け、動画には確認してほしい時刻を添えます。外部サービスの公式文書へリンクする場合は、参照した版や取得日を記録します。

図は「文章を読まなくても分かる装飾」ではなく、状態や関係を表す資料です。画面遷移図なら開始点、操作、遷移先、エラー時の分岐を示します。データフローなら送信元、送信先、内容、保存場所、失敗時の扱いを示します。本文と図で同じ情報を別々に更新する場合は、どちらを正本とするかを決めます。

変更履歴と仕様の正本

仕様変更を会議やチャットだけで決めると、実装者が古い文書を参照する可能性があります。変更時には、変更内容、理由、影響する機能、決定者、反映日、対応するチケットを正本へ記録します。

版を更新する前に、進行中の実装へどの時点から適用するかを決めます。すでに作業中の機能を変更する場合は、作り直す範囲、追加のテスト、公開日への影響を確認します。「最新版に合わせる」だけでは、途中の成果物をどう扱うかが残ります。

仕様の正本は一つにし、コピーを配布し続けないようにします。閲覧権限やネットワークの制約で同じ場所を使えない場合は、同期する担当者と時刻を決め、古い版であることを表示します。

開発へ渡す前の仕様書チェック

仕様書を渡す前に、書いた本人ではなく、実装またはテストを担当する人に次の問いで確認してもらいます。

• 利用者と解決したい問題を一文で説明できるか
• 今回作らないものが分かるか
• 変更してはいけない条件と、相談先が分かるか
• 最初に実装する操作を選べるか
• 正常、入力誤り、権限不足、外部サービス停止時の結果が分かるか
• 受け入れ条件を使って合否を判断できるか
• まだ決まっていない点について、決める人と期限が分かるか
• どの文書が最新か分かるか

答えられない項目があれば、説明会を追加する前に仕様書の該当箇所を直します。質問が出た事実を担当者の理解不足とせず、次の読者にも必要な情報かを確認します。

確認する人には、文章の誤字だけでなく、最初の作業を選べるかを見てもらいます。実装を担当する人が追加質問なしで着手できても、テスト担当者が合否を決められないなら、受け入れ条件が足りません。反対に、条件を増やした結果、互いに矛盾する場合は、説明を足す前に優先する条件を決めます。仕様書の長さではなく、実装、確認、変更の三つの判断に使えるかが基準です。

要件整理から始める海外開発の仕様づくり

仕様書を詳しくする前に、必要な人材、担当する機能、英語で判断を返す責任者を整理します。まだ要件が固まっていない場合は、初回ヒアリングで整理する項目もご覧ください。

私たちは、必要なスキル、人数、開始時期の整理から、候補者探索、技術評価、面接、稼働開始の準備までを支援しています。仕様を作る担当と、レビューを担う責任者を含めた体制については、海外IT人材の採用と開発体制についてご相談ください。