仕様作成を担当するエンジニアが理解すべき仕様書の基本知識

背景

システム開発、ソフトウェア開発の上流工程では、仕様書と呼ばれる技術的な文書が作成されます。この仕様書作成を初めて担当することになり不安になっているエンジニア向けに、仕様担当として理解しておくべきポイントを解説致します。

仕様書とは？

仕様書とは、システムやソフトウェアが満たすべき振る舞いを記述した文書のことを言います。仕様書内には自然言語で書かれた文章のみではなく、UMLと呼ばれるシーケンス図や状態遷移図などのモデルも表現されます。

仕様書はなぜ必要か？

大規模な開発プロジェクトになると、複数の組織を跨いで開発が行われることになります。つまり、発注者と受注者の関係性が生まれます。発注者はシステムやソフトウェアが満たすべき振る舞いを定義し、それを文書化します。その文書を用いて受注者が設計/開発行為を行うという流れです。発注者が仕様書を作成する行為を上流工程、受注者が仕様書を基に開発行為を行うことを下流工程と業界では呼ばれています。この上流工程と下流工程を繋ぐ文書が「仕様書」です。

仕様書には種類がある

仕様書には目的やスコープに応じて様々な種類があります。組織や開発プロジェクトにより種類は異なってくると思いますが、ここでは一つの事例として受け止めていただければと思います。

上位仕様書（例：システム要求仕様書、システム仕様書など）

システムが満たすべき「要求」を記述した、仕様書の中では上位に位置する文書のことを上位仕様書と呼びます。システムとは、サービスを実現するために構成された要素の集合を指します。例えば、スマートフォンからエアコンをつけるサービスを開発するとします。その場合、システムを構成する要素は以下のような粒度感になります。

・スマートフォンアプリ

・センタ（サーバー）

・エアコン

上記のような、システムを構成する要素それぞれに対し満たすべき振る舞いを記述する仕様書のことを「システム要求仕様書」や「システム仕様書」等といいます（本記事ではシステム要求仕様書と定義します）。システム要求仕様書では、システムを構成する要素に対し担うべき責務を記述します。上記のシステムでは、例えば以下のような責務分担となります。

・スマートフォンアプリ：ユーザー操作を検知し、センタ（サーバー）へ通知し、結果をユーザーへ表示する

・センタ（サーバー）：スマートフォンアプリからの通知を受信し、エアコンへ操作要求を通知する

・エアコン：センタ（サーバー）からの通知を受信し、エアコンを起動する

上記はいわゆる機能的な責務分担になりますが、非機能的な要求を記述することもあります。例えばセキュリティに関する要求があります。なりすましや盗聴といった脅威からシステムを守るために適切な責務分担を検討し記述されます。例えば以下のような責務分担となります。

・スマートフォンアプリ：正規のユーザーであるかを認証する、通信を暗号化&復号する

・センタ（サーバー）：スマートフォンアプリ&エアコンを認証する、通信を暗号化&復号する

・エアコン：センタ（サーバー）を認証する、通信を暗号化&復号する

上記は一例ですが、よく見る要求です。セキュリティはリスクベースという考え方です。先述のなりすましというリスクに対し「認証」という対策を講じることでリスクを軽減します。また、盗聴というリスクに対しては通信を「暗号化」するという対策でリスクを軽減します。セキュリティのリスクを洗い出す際、STRIDEと呼ばれるフレームワークを用いることが一般的です。STRIDEとは、マイクロソフト社が提唱しているリスク抽出手法で、以下の頭文字の略称です。

・Spoofing（なりすまし）
・Tampering（盗聴）
・Repudiation(否認拒否）
・Information Disclosure（情報漏えい）
・Dos(Denial of Service)（サービス妨害）
・Elevation of Privilege(権限昇格）

参考：https://www.ipa.go.jp/archive/security/vuln/programming/ps6vr70000012yp1-att/000059838.pdf

セキュリティの他にも、時間的な要求（起動時間、実行時間）、リソース的な要求（消費電流、メモリ）といった要求も存在します。

機能仕様書、技術仕様書、インターフェース仕様書

システム要求仕様書に記述されている要求を技術的に具体化したものを機能仕様書や技術仕様書と呼びます（本記事では機能仕様書と定義します）。要求レベルでは抽象的なため、設計に着手することができません。そのため、要求を適切に具体化する必要があります。なお、具体化する際、どのような通信経路で、どのような通信プロトコルで、どのようなデータをやり取りするかといった情報が必要になってきます。そのような情報を記述しているのがインターフェース仕様書です。機能仕様書とセットで作成されます。機能仕様書では、要求を実現するための実現手段を表現します。機能仕様書はシステム構成要素毎に発行されるケースと、システムでまとめて発行されるケースがありますが、ここでは前者のケースで紹介致します。上記システム要求をエアコンの視点で具体化した機能仕様とインターフェース仕様の例です。

エアコン機能仕様

・エアコンは、センタ（サーバー）からのエアコンON要求を受信後、要求内容を解析する

・エアコンは、要求内容を正常と判断した場合、操作可否を判断する

・エアコンは、操作可と判断した場合、空調操作を実行する

・エアコンは、空調操作を完了後、操作結果をセンタ（サーバー）へ送信する

インターフェース仕様

上記はエアコンON要求をバイナリ形式でやり取りする例です。他にも、空調操作結果の例を示します。

操作結果が成功の場合は00を、失敗した場合は01を設定しセンタ（サーバー）へ通知するというインターフェース仕様の例です。

参考：https://www.mhlw.go.jp/bunya/shougaihoken/jiritsushien/dl/if2310_02.pdf

インターフェース仕様としては、上記のようにやりとりするデータ以外にも、以下の要素を含みます。

・通信経路：Wi-Fi or Bluetooth or 携帯網

・通信プロトコル：HTTP or HTTPS or MQTT

・認証、暗号方式：TLS

・データ形式：バイナリ or テキスト

上記は例ですので、製品により記載される内容は異なってきます。

仕様書内の章構成

仕様書内に含まれる内容として以下があります。それぞれの概要を説明致します。

表紙

仕様書名やVersion、発行承認者、作成者などの情報を含みます。

仕様書は公式な文書として発行されるため、いつだれが承認したのかという情報を残す必要があります。その際、表紙を活用することが可能です。例では枠を3つ設けましたが、必要に応じて4つ5つと増やすことも可能です。それぞれの枠にサインをするのはどういった人物かを説明しますと、以下のようになります。

・作成：仕様書を担当した実務レベルのエンジニア

・検討：リーダークラスのエンジニア（技術的なレビューを担当した人物）

・承認：プロジェクトマネージャー（プロジェクトにおける責任を果たせる人物）

目次

ドキュメント内の章構成を一覧化したものです。ドキュメント内の地図の役割を果たします。

仕様書内には図や表を入れるのが一般的です。その際、図や表に付与された番号も目次に含むことが可能ですので、図表目次を作成することをお勧めします。

変更履歴

仕様書の変更点をリスト化したものです。仕様書を発行する部署としては変更点の管理に利用しますし、仕様書を受け取る側としても変更点を把握するために必要です。詳細はこちらの記事で紹介しておりますので、あわせてご確認いただけると幸いです。

用語定義

用語の定義をリスト化したものです。

用語定義の際にしばしば議論されますが、一般的な用語だったり、一般的な定義に従い使用している言葉は用語定義には含まない方が無難と考えます。プロジェクト独自のワードだったり、プロジェクトで意図的に定義を変えて使用しているワードに絞って定義をすることで、用語定義を必要最小限にすることが可能です。

仕様書の位置付けとスコープ

仕様書の位置づけを参照関係を用いて表現し、何をどこまで表現する仕様書なのかを記述します。これにより、この仕様書では何をどこまで表現されているのか、表現されていない部分はどこにあるのかを明確にすることが可能です。

参照仕様

仕様書内で外部の文書を参照している場合、参照先の仕様書名とバージョンがここにリスト化されます。例えば、以下のように表現されます。

本文：センタ-エアコン間通信時の送受信データに関し、「センタ-エアコン間通信仕様書」を参照すること

参照仕様：センタ-エアコン間通信仕様書 Ver.1.00

この「参照」という行為、実は書き手と読み手の間でギャップが生まれやすい部分です。

書き手：データ定義は参照先でしているから、ここでは参照に留める。データが不正な場合の処理も参照先のスコープにする

読み手：ただの参照だからスルー

上記の場合、書き手としてはデータ不正なパターン、異常系の振る舞いを参照先で記述しているため、参照先を設計/評価の入力にしてほしいという意図を含んでいます。しかし、それが読み手に伝わらず、後々トラブルになるという悲劇が発生します。ベテランの設計者であれば書き手の意図を理解できますが、設計経験が浅いエンジニアの場合、参照の意図を理解できないケースがあります。そのような事態を避けるためには、以下のように具体的に本文内でガイドするのが無難です。

本文：なお、データが不正な場合の振る舞いに関し、「センタ-エアコン間通信仕様書」を参照すること

仕様（機能仕様 or 非機能仕様 or インターフェース仕様）

仕様書の本体である仕様本文が記述されます。仕様の記述方法に関しては様々なガイドが既に世の中にたくさんありますが、最小限抑えておいていただきたい点のみ説明します。

主語を記述する

要件内に可能な限り主語を記述しましょう。書き手は要求内容を熟知しているので、記述を省く傾向にありますが、読み手が誤解をするリスクを常に想定しておく必要があります。

1文章で複数の動詞を記述しない

~し、~し、そして~してから~すること

上記のような仕様を記述すると、とても読みにくいです。そして、設計や評価の際に管理がしずらくなってしまうこともあり、避けるべきです。そのため、以下のような仕様がおすすめです。

エアコンは、~後、~すること

「~後」は動詞じゃないのか？複数書いているではないか、と疑問に感じるかもしれませんが、「~すること」のみがこの仕様の動詞になります。「~後」は「トリガ」の意図です。プログラム的には「トリガ」の後で動詞を表現するため、仕様としても「トリガ」を含むとより良い仕様となります。そのため、テンプレートとしては以下のようになります。

「主語」は、「トリガ」後、「動詞」すること

表現を統一する

表現が揺れていると、書き手と読み手の理解にギャップが生まれるリスクが高くなります。よくある揺れ方を示します。

・保存系：保存する、保持する、書き込む、所持する

・保存場所系：不揮発、NV、メモリ、不揮発メモリ

・判断系：判断する、判定する

・異常系：異常な場合、不正な場合、エラーの場合

・状態遷移系：状態、モード、動作モード

・通信系：送信する、要求する、要求を送信する

特に意図が無い場合は表現を統一するのが無難です。

Appendix

仕様ではないが、仕様の理解を促進するために必要な情報をAppendixとして表現することがあります。例えば、実際の運用で利用されるデータ設定などを記述することがあります。組織によっては、Appendixを仕様と定義するケースがありますが、混乱を招くためあまりおすすめできません。

まとめ

これから仕様を担当する方に向けて、必要と思われる基本知識を記述しました。仕様担当はとてもハードな業務ですが、少しでも本記事の内容がお役に立てば幸いです。