プロダクト開発において、仕様書は道標であり時にエビデンスとして参照されることもあります。
そのため、仕様書の記述が曖昧だと実装時の手戻りの原因になったり、仕様書から実装に必要な情報が読み取れず手が付けられないといった問題が起こります。
こうしたトラブルを防ぐためにも、仕様書に対する認識を合わせ、チームのコミュニケーションの助けとなる仕様書を作りましょう。
目次
プロダクト開発に欠かせない「仕様書」
プロダクト開発を行う上で、その共通認識となるのが「仕様書」です。仕様書があることで、プロダクトがどのように振る舞い、どのような仕組みとなっているのかについて認識を合わせる助けになります。
Webサイトの開発で例を挙げると、一般的には以下のような項目が仕様書に記載されます。
- プロダクトの概要
- サイトマップ（サイト構成図）
- ワイヤーフレーム（画面デザイン）
- スマートフォン対応の有無
- 対応OSや対応ブラウザの指定
- 納品形式（サーバーやドメインの対応など）
- 画像や文章などの内容について
このように仕様書を見ただけで「どのような目的で何を作るのか」が明白にわかるようになっています。つまり仕様書とは、チーム全体の認識を合わせるために使われるコミュニケーション手段のひとつであるといえます。
仕様書を作成する目的
プロダクト開発はチームで行うからこそ、チームメンバーそれぞれの認識を常に合わせておくことが重要です。その共通認識の材料として使用されるのが仕様書です。プロダクト開発では、さまざまな機能を取り扱いますが、適切なコミュニケーションがないと認識がずれたまま実装される可能性があります。
仕様書に対するよくある課題
IT業界では、仕様書にまつわる問題がよく起こります。ここではよく散見される問題点をあげていきます。
仕様書を書いたけど認識があっていなかった
仕様書を書いたからといっても、認識のずれが起こることはあります。これには読み手側、書き手側の双方に原因があるかもしれません。
読み手側の原因としては、「見落とし」「勘違い」「経験則による思い込み」などが挙げられます。特に文章量が多く、情報が豊富な場合にこうしたことが発生しやすくなります。
逆に書き手側の原因としては、「ざっくりとした説明に終始している」という点があります。肝心な機能説明の部分が1行だけという場合もあり、「具体的な仕様がわからない」「改修時に機能差分の概要がわからない」などという問題が起こるのです。
仕様書を書くのに時間がかかる
仕様書の作成には時間がかかりますが、その構築に多くの時間を割いてしまうと、一番の核となる開発のスケジュールに支障が出てしまいます。
逆に作成に時間をかけず内容が曖昧だと、手戻りなどによって余計な時間が発生します。手戻りが多く発生すると、仕様書の改修も行わなくてはいけませんが、作業の多さから仕様書のメンテナンス作業が滞って関係者が疲弊することもあるのです。
そのため、仕様書はどこまで詰めるかという点が大切です。
メンテナンスコストがかかる
仕様の変更があると仕様書も書き換えなくてはいけません。ただでさえ、修正やスケジュール調整などリソースが足りない状態なのに、仕様書の変更も加わると大きなコストとなります。また、仕様変更は仕様書の不備によっても発生するため、曖昧な仕様書は大きなリスクとなるのです。
仕様書を書くときのポイント
ここからは実際に仕様書を記載する際のポイントをご紹介します。
共通言語を使う
チーム内のコミュニケーションを円滑にするためには、「ユビキタス言語」の定義が推奨されます。ユビキタス言語は、ドメインユーザー、ドメインエキスパート、開発者など、開発に携わるチーム全体で言語を統一するために策定されるものです。
共通言語のないチームでは、「エンジニアによって言い回しが異なる」「ドキュメント・コミュニケーションツール・コード内などで表記揺れが発生する」といった問題が起こりがちです。こうした状態を防ぐことで、トラブル発生のリスクの軽減や効率的な運用を行えるようにします。
実際の運用方法は、Notionなどのドキュメント管理ツールで、用語集や図を使用して開発に必要な言語を定義します。また、ユビキタス言語は、「境界づけられたコンテキスト」のみでの使用が適切です。同じ言葉でも、プロダクトやチームが変われば異なる概念となることもあるため、幅広い範囲で同時に活用するものではありません。
画面と機能は切り離して仕様を記載する
仕様書は画面単位で記述されることが多いですが、これには課題があると考えます。なぜなら、機能とは本来、ある特定のユーザーストーリーを実現するためにあるものですが、一方で画面は複数の機能を内包するケースが多いからです。そのために画面単位の説明では、実現目的であるユーザーストーリーとの結びつきが希薄化してしまいます。そこで、機能単位で仕様を記述することで、実現目的との関連性を明確に表すことができます。
また、画面デザインは変更が発生することが多いため、別のツールで管理します。これにより画面デザインの変更と仕様の変更とを切り分けて管理することができます。
履歴ではなく経緯を記載する
履歴を記載すると、それを追うのに無駄なリソースが発生します。履歴は、記載するのではなくツールで管理することがおすすめです。
仕様書には、履歴でなく「経緯」を記載するようにします。「Why：なぜ」にあたる部分を書くことで、「なぜこの機能が必要なのか」「なぜこの仕様になったのか」が「いつ誰が見ても」わかるようにするのです。
100%の仕様書を作ろうとしない
仕様書の作成だけに大きな時間をかけるわけにはいきません。完璧な仕様書を作成するよりも、アップデートを前提に「ミスに気づける」「カバーできる」仕組みづくりが重要です。
そのためには、属人化しない「誰が見てもわかる仕様書」を作成します。仕様書がわかりやすければミスに気づきやすくなりますし、後々に改修が発生しても、そこまでに至る経緯が仕様書に示されていることで、ブラックボックス化のような状態を避けられるのです。
仕様書を確定させる前に各職種がチェックする
仕様書を確定する前に、職種横断でのレビューを実施します。エンジニア以外が見ることで、「記入漏れ」「認識ずれの気づき」「わかりにくい箇所がないか」といった確認が取れます。これはユビキタス言語の確認や、属人化が発生しない仕様書作りにも役立ちます。
シーケンス図を使用する
システムの概要をわかりやすくするために、シーケンス図を挿入します。シーケンス図は、システムの仕様と処理を図式化したもので、クラスとオブジェクトの関係性が一目でわかるようになります。
仕様書には機能の詳細も必須ですが、ユーザー側のアクションに対してシステム処理がどのようになっているのかを理解できるようにすることも重要です。
デザインは別で管理する
仕様書にデザインファイルを挿入することは、読み手に視覚的なイメージを与え、チーム内の認識をより合わせやすくなります。一方で、機能や振る舞いに本来影響しないレベルのデザインや文言の修正においても、仕様書をメンテナンスする必要が生じ、管理コストが激増する問題もはらんでいます。
そこで、仕様書とデザインファイルとを別個に管理することを推奨します。仕様書からはデザインファイルへの参照のみを記述するにとどめ、文言を含めたデザインは常にデザインファイルを正とする管理を行うのです。
これにより、仕様書の扱うスコープは、機能の実現目的や振る舞いに焦点を合わせられるため、継続的なメンテナンスを行いやすい体系とすることができます。
まとめ
仕様書による問題を防ぐためには、「機能の詳細に関して誰がいつ見てもわかる」ように作成しなければいけません。そのためには、ユビキタス言語の作成、シーケンス図、デザインファイルを使用した「見やすい・検索しやすい」仕様書づくりが必要です。
100%の仕様書を目指さず、常にアップデートする体制作りを行えば、仕様書の構築に無駄なリソースをかけることもありません。
また、作成した仕様書は、職種横断でレビューすることで認識ずれや記入漏れを軽減することが可能です。
