システム開発における仕様書作成から発行までの道のり

背景

開発プロジェクトにおいて必須な文書である「仕様書」。これからその仕様書の担当になるエンジニアの方に向けて、一つの仕様書ができるまでの流れを説明致します。仕様書とは、システム、製品が満たすべき振る舞いを記述した開発文書の1つです。仕様書の種類や内容に関してはこちらの記事で紹介しておりますので、併せてご覧ください。

システム開発には種類がある

本題に入る前に、開発の種類である「新規開発」と「派生開発」について触れておきます。この概念をまずご理解いただく必要があると考えています。

システム開発の種類①：新規開発とは？

新規で新たにシステムを構築する開発を新規開発といいます。しかし、実際、新規開発はほぼ発生しません。理由は、既に世の中に稼働しているシステムが存在しているため、そのシステムをベースに開発を行い、期間やコストを抑えるのが一般的です。

システム開発の種類②：派生開発とは？

先述の通り、既に稼働しているシステムをベースに開発を行う開発を派生開発とよびます。既にシステムがあるのに新たに開発プロジェクトが立ち上がるのは何故か疑問に感じると思いますが、目的は大きく2つに分かれます。

派生開発の目的①：世の中の変化に追従するため

世の中の技術状況は日進月歩で進化しています。例えば、ついこの間まで携帯電話網は3Gと呼ばれる規格でしたが、今では5G、6Gと進化をしています。携帯網は例の1つですが、システムを構成するインフラは常に変化しますので、流動している製品側で必要な仕様変更を加える必要があるのです。ちなみに、今では家電や自動車も携帯電話網やWi-Fiを利用してネットワークに接続するようになっています。

派生開発の目的②：サービスを改善するため

ユーザーからの製品口コミや、競合他社との差別化など、企業が生き残るためにシステム/製品に追加機能を加えることがあります。機能を追加することもあれば、不要な機能を削除したり、適切な統廃合を行うこともあります。つまり、ユーザーにより良い経験を提供するため、既存仕様に手を加える行為です。

仕様発行までの道のり①：仕様書発行のプロセスを作成し、利害関係者と合意形成する

プロセスを可視化するPFDを作成する

仕様書発行までのプロセスを作成し、利害関係者と合意形成をします。先述の通り、開発プロジェクトは大半が「派生開発」です。そのため、「何をベースに」「どのようなプロセスで」仕様書を発行するのかを可視化する必要があります。プロセスを可視化する方法として、PFD（プロセス・フローダイアグラム）を用いることを推奨します。

PFDとは、プロセスと成果物を一定のルールの下で線で繋ぎ表現する方法です。

PFDを用いることで、何を入力とし、何を生成するのかが一目で分かります。一定のルールの下でと記載しましたが、特に以下を意識しておけば十分です。

• 繋いでよいのは「成果物」と「プロセス」（成果物⇔成果物、プロセス⇔プロセスはNG）
• 分岐を設けない（この場合はこちらの成果物を入力とし、的な表現はしない）
• PFDは順序性を示すものではない（ワークフローと混同しないこと）
• レビュープロセスが発生する場合は「R」マークを成果物に表現しておく

仕様書作成プロセスの場合、以下のようなPFDになります。

PFDの中には「成果物」と「プロセス」が存在しますが、曖昧性を除くため「成果物定義書」と「プロセス定義書」を作成することを推奨します。

成果物定義書で成果物の内容を具体化する

成果物定義書には以下の内容を含むとよいでしょう。

• 成果物名：成果物の文書名やファイル名を記載します
• 入力文書：成果物作成の入力となる文書の文書名やファイル名を記載します
• 成果物の目的：成果物のスコープを簡潔に記載します
• 成果物の内容：成果物内に含む情報を記載します

成果物の内容を詳しく記載しておくと、派生プロジェクトで再利用し効率化できる可能性が高まりますので、出来る限り詳しく記載することをお勧めします。成果物定義書のサンプルを以下に示します。スマホの場合は横にスクロールしてご覧ください。

プロセス定義書でプロセスの内容を具体化する

プロセス定義書には以下内容を含むとよいでしょう。

• プロセス名：プロセスの名称です
• 入力文書：プロセス実施時に参照する入力文書の文書名やファイル名を記載します
• 出力文書：プロセスで生成する文書名やファイル名を記載します
• プロセス開始条件：プロセスを開始する前提条件を記載します
• 必要なスキル：プロセスを担当するエンジニアに求めるスキルを記載します
• 活動内容：プロセスで行う活動を詳しく記載します
• プロセス終了条件：プロセス終了の基準を記載します

上記の中で、「必要なスキル」の定義は重要と考えます。複数のプロセスの中で、「このプロセスはこの人しかできない」ということを可視化し、体制面で対策を検討すべきだからです。もう少し掘り下げますと、仕様書を作成する際、「頭」を使う作業と「量をこなす」作業が発生しますが、この「頭」を使う作業に関してはベテランエンジニアやリーダーがボトルネックになりがちです。そのため、PFDを利害関係者間で合意形成する際に、体制的な問題はないかを是非議論していただければと存じます。プロセス定義書の例を以下に示します。スマホの場合は横にスクロールしてご覧ください。

作成したPFDを利害関係者と合意形成する

作成したPFDを利害関係者と合意形成する必要があります。特に、作成した仕様書を入力とする後工程（ソフトウェア開発チーム、評価チーム）との合意形成は必須事項です。ここの合意形成を怠ると、せっかく作成した仕様書を「受け取ってもらえない」という最悪の事態に発展しかねないためです。そのため、後工程がPFDのレビューに参加してもらえるように粘り強く交渉しましょう（忙しいからという理由で断られても引き下がってはだめです）。

仕様発行までの道のり②：仕様書をPFDに沿って作成する

作成したPFD、プロセス定義書、成果物定義書に従い仕様書を作成していきます。

仕様発行までの道のり③：仕様書をレビューする

作成した仕様書をレビューします。レビューとは、成果物の妥当性を検証する一つの手法です。レビュー方法は数多く世の中に定義がございますが、代表的なものを以下に示します。

ピアレビュー

最も手軽なレビュー形式です。メンバー間で成果物を交換し、指摘を出し合います。ピアとは仲間や同僚という意味で、まさに隣同士の人とレビューするイメージです。お互いの成果物を交換しレビューするので、クロスチェックとよぶこともあります。ピアレビューのメリットとしては、メンバー間の技術力を平均化したり、成果物の揺れを防ぐ点にあります。ベテランエンジニアやリーダーは忙しく、中々レビューの時間が取れないため、ピアレビューを積極的に活用しましょう。

ウォークスルーレビュー

会議の場で成果物を上から下まで説明する形式です。最もポピュラーです。ベテランエンジニアやリーダーに対し、成果物作成担当者が説明します。成果物を上から下までチェックしますので、漏れなく指摘を抽出することが可能です。しかし、成果物のボリュームが多い場合、かなりの労力を使うため、ウォークスルーレビューの実施前によく話し合うことが重要です。例えば、代表的なものだけウォークスルーレビューを行い、他の成果物に関してはピアレビューのみとする等、時間効率を検討します。

回覧レビュー

会議を実施せず、成果物を配布して指摘を待つレビュー形式です。会議調整が不要な点、会議時間が発生しない点がメリットです。しかし、成果物のコンセプト等を説明していない分、的確な指摘がもらえない、期日までに見てもらえない等のリスクがあります。また、指摘も文章のみとなるため、指摘の意図が理解できず、せっかく修正しても差し戻しされるリスクがあります。そのため、配布前に成果物のコンセプトを説明することや、配布後、レビュワーからの指摘の意図を口頭で確認するなど、文章のみでコミュニケーションを取ろうとしないことを前提に回覧レビューを行いましょう。

インスペクション

最も公式なレビュー形式です。参加者に明確な役割を持たせ、組織の規定に従い会議進行します。例えば、各参加者に以下のような役割を持たせます。

• 司会進行
• 議事録担当
• レビュワー
• 承認者

大きな組織の場合、開発規定により、次工程移行の判断をインスペクションにより行う場合があります。例えば、仕様発行を完了し、ソフト開発工程へ移行することを承認する公式な会議の場合、仕様部署のリーダーが司会進行を行い、ソフト開発部署や品証がレビュワーとして成果物を指摘し、最終的に事業部長クラスが承認するといった具合です。このインスペクションの場で出された指摘は漏らさず議事録に残し、後日、対応状況を報告する義務があります。議事録の残し方については以下の記事も参考にしていただければと存じます。

モブワーク

上記のように、成果物を作成してからレビューをするのが主流ではありますが、このやり方にはいくつもの問題があります。

• 成果物作成者とレビュワーとの間に技術力の差があるため、差し戻しが多い
• レビュワーの指摘の意図を成果物作成者が理解できない
• レビュー時間が足りず、配布先から品質の面でクレームがくる
• レビューの場が苦痛になり、離職の原因になる

レビューは成果物の品質向上のためには不可欠な工程です。そして、ベテランエンジニアやリーダーのノウハウを若手に継承する場、つまり教育の場でもあります。レビュワーとしては「わかってほしい、成長してほしい」という想いで指摘を出すのですが、これが若手にとってみると「どうして認めてもらえないんだろう、レビューがつらい」という悪循環になりがちです。もし、そのような事態に陥っている場合、モブワークという仕事の仕方は有意義です。モブプログラミングの派生版で、一つの成果物を複数人で作成する手法です。具体的な進め方は以下です。

1. 複数人で同じ画面を見る
2. 画面操作する人、指摘を出す人を決める
3. 画面操作開始（成果物作成開始）
4. 気になる点があればリアルタイムに指摘をし、その場で修正されるまで見届ける
5. 一定時間が経過したら画面操作担当者を交代し3~4を繰り返す

この進め方であれば、レビューが必要無いので、結果的に早く高品質な成果物が作成できるメリットがあります。また、ベテランの技をじっくりと観察することができるため、若手の成長にとっても有意義です。わかりやすい例で言えばショートカットキーです。ベテランの方が明らかに使いこなすショートカットキーの数が多いため、若手は魔法を見ているような感覚になります。また、ベテランの方からすると、「なるほど、このやり方を知らないのか、だから遅いのか」という気付きが得られ、指導の仕方を見直すことができます。

仕様発行までの道のり④：仕様書をリリース

仕様書作成が完了し、レビューを終え、指摘事項を修正完了した後、仕様書を関係部署へリリースします。Gitやサブバージョン等のリポジトリに仕様書のベースラインを格納し、関係部署へアナウンスをします。

仕様発行までの道のり⑤：Q&A活動

仕様書をリリース後、仕様受領部署（ソフト開発部署など）が仕様書を確認します。その際、疑問点や不具合が見つかることがあります。その疑問点や不具合を解消するために、Q&A活動という活動を行います。Qは質問、Aは回答という意味ですが、つまり、質問を受け付けますよということです。このQ&A活動が仕様担当にとって鬼門です。様々な部署から問い合わせが来ますので、効率的に課題管理する必要がありますので、RedmineやJIRA等のチケット管理システムを利用するとよいでしょう。Excelやメールでやり取りをすると管理が難しいですが、チケット管理システムであれば状況をデジタルに表示できます。なお、チケットを起案する側、チケットを受け取る側それぞれの負荷を最小限に抑えるための運用ルールをよく話し合っておきましょう。例えば、「チケット内に最低限含めてほしい情報を決めておく」、「質問なのか仕様修正してほしいのか」を記載してもらう等を決めておくことで、その後のやり取りがスムーズになります。ソフト開発部署からすると、仕様書と設計文書との間をトレースする必要があるため、仕様と設計に乖離があると不都合なわけです。そのため、仕様修正を依頼されることがしばしばあります。

仕様発行までの道のり⑥：仕様書を修正

Q&A活動を通し、仕様書が修正されますので、仕様書を関係部署へ再度リリースします。その際、仕様書のバージョンが更新されます。そして、変更点に関しては変更履歴に記載されます。仕様書のバージョン管理や変更履歴に関しては以下の記事でも紹介しておりますので、併せてご覧いただければと存じます。

参考サイト

派生開発やPFDに関し、以下のサイトが参考になりますので、併せてご覧いただくと、より理解が深まると存じます。

https://affordd.jp/previous/conference2014/affordd_conference2014_tutorial.pdf

まとめ

仕様書が作成される流れをまとめてみました。ソフト開発を担当していた方が、仕様担当を初めて担当した際、こんなことを言っていました。「今まで、仕様書を早く発行してくれと言う立場だったが、仕様担当がこんなに大変だとは知らなかった」。仕様担当は意外と大変です。

関連記事

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

2024年4月15日 開発文書に変更履歴は何故必要なのか？重要性と記載する際のポイント