「ソフトウェア設計仕様書（SDD）」の作成方法、仕様書に含めるべき内容とは：優れたソフトウェア設計仕様書を作成するためのヒント

　SDDは、関係者と開発者との間の契約としての役割を果たし、想定する結果について全関係者の見解を一致させる。見解が一致していれば、スコープクリープ（意図しないプロジェクトの拡大）のリスクが最小限に抑えられ、プロジェクトが順調に進み、予算内に収まる。さらに、将来の繰り返し、メンテナンス、アップグレードに使用できる参照ポイントとなり、効率的な変更が容易になる。

　設計仕様を文書にしておけば、SDDはシステムのアーキテクチャと機能に関する包括的なガイドとしての役割を果たす。SDDがあれば、開発チームへの新しいメンバーの参加が迅速になる。最終的には、時間をかけて質の高いSDDを作成すれば、適切なコラボレーションが生まれ、コードの品質が高まり、ソフトウェアプロジェクトの全体的な成功につながる。

　SDDをどのように構成するかは、テクノロジー業界の中でも異なる可能性があるが、構成が変わっても次のようなメリットが得られることは変わらない。

• 信頼できる唯一の情報源：SDDは、プロジェクトの目標、スコープ、業務要件、技術要件を細かく定め、開発チーム、製品管理担当者、経営陣といった関係者の間に誤解が生じないようにする関連情報を含む
• スコープクリープの回避：SDDに設計要件と技術要件を詳しく記載することで、プロジェクトマネジャーはSDDを参考にプロジェクトに必要なリソース、時間、予算を正確に見積もることができる。プロジェクトチームは、詳細SDDを使って、スコープクリープを回避し、潜在的なリスクとその緩和方針を早期に特定できる
• コラボレーションの促進：チームコラボレーションツールでSDDを共有すれば、特に部門横断的なチームでのチームワークと調整が容易になる。各開発者が自身の役割と責務を理解することで、作業の重複が減り、全てのコンポーネントが調和して開発される。これは、反復的な開発と継続的インテグレーションによって効率的なチーム調整が求められるアジャイル環境では特に重要になる。
• 品質の向上：SDDによって最終製品が必要な設計と機能を満たすことが保証されるため、SDDは開発プロジェクトの品質のベンチマークになる。また、コーディングプラクティス、テスト手順、ドキュメントの成功基準や標準もSDDによって設定される

ソフトウェア設計仕様書の作成方法

　SDDの作成には、チームに参加するさまざまな職務の担当者の専門知識や意見が必要になるため、ある程度の準備が必要だ。チームの関係者はSDDの作成以外の職務も担う。

　通常、SDDの作成には次のような関係者が参加する。

• 開発者
• エンタープライズアーキテクト、クラウドアーキテクト、ソリューションアーキテクト
• テスト担当者
• 業務アナリスト
• UIとユーザーエクスペリエンス（UX）のデザイナー
• テクニカルライター

　さまざまな職務を担う部門横断型のチームを結成したら、SDDの作成を成功に導くためにチームが実行すべき重要な準備手順が幾つかある。

1.SDDでの役割と責務を定義する

　SDD作成の効率を上げるには、SDDでの役割と責務を明確に定義することが重要だ。SDD作成に上級開発者やアーキテクトが参加できるかどうかを検討する。参加できるなら、上級開発者やアーキテクトにテクニカルライティングのサポートを求め、その専門知識が最も役立つセクションに集中できるよう特別に配慮する

2.要件を集める

　SDDの作成は、利害関係者に接触して意見を求め、その要件と期待事項を集めることから始める。この時点で初めて、既存の要件ドキュメント、ユーザーストーリー、関連ドキュメントを集め、レビューする。

3.システムの統合図を作成する

　システムの環境と、自社内の他のバックエンドシステムなど他のエンティティとの相互作用を説明する図を作成するのも重要な準備手順の一つだ。この図には、パートナーやベンダー（サードパーティーの決済業者など）のシステムと自社システムが相互作用する仕組みも盛り込む必要がある。じっくりと時間をかけて、機能の要件を捉え、システムのさまざまなパーツがどのように相互作用するかを示すユースケースを考える。

4.プロジェクトの目標とスコープを定義する

　自社の業務目標との整合性が確保されるように、プロジェクトの目標とスコープを明確に定義する。この時点で、業務関係者または業務部門から指名された担当者を参加させる。オンラインミーティングを開催するか、可能ならプロジェクトチームを一堂に集め、相互に協力して議論や質疑応答を実施する。

ソフトウェア設計仕様書の内容

　SDDのテンプレートを作成する方法は幾つもある。いずれにせよ、作成者は開発チームや関係者の協力を得て、SDD作成に関する自社標準を確立しなければならない。「IEEE 1016-2009」など、SDDに盛り込む内容を規定する標準もある。ただし、自社のニーズに合わせてカスタマイズしたSDDを使用するチームが多い。

　参考までに、ここではSDDを構成する一般的な要素を紹介する。

1.序文

　SDDの序文には、次のような内容を盛り込む。

• プロジェクト名
• プロジェクト担当者
• SDDの作成者
• 開発チームのメンバー
• バージョン履歴

　SDDの序文には、設計書のバージョンとその変更内容を記録するバージョン履歴の表を含めるのが一般的だ。こうした表は過去の遺物のように思えるかもしれないが、コンプライアンス監査人は監査の一環としてこの情報を探す。

2.概要

　SDDの冒頭で、プロジェクトを説明する簡単な概要を5〜10行で記述する。概要には、SDDで使われる用語集やプロジェクト目標の一覧も含める。記述する際には、プロジェクトの簡単な概要を必要とする経営陣など、開発者以外の関係者を念頭に置く。

3.現状の設計

　アプリケーションの現状の設計を含める。運用環境で既に使用しているアプリケーションの設計書が存在しなかったり、かなり古くなったりしている場合は、そのアプリケーションのリバースエンジニアリングを行い、SDDを作り直すことも考える。現状の設計を文書にしておくと、オンプレミスで運用してきたレガシーアプリケーションをクラウドサービスに移行する場合などに役立つことがある。

4.設計案

　設計案セクションでは、新しいシステムのアーキテクチャ、機能、コンポーネントを詳しく説明する。

　通常、設計案はSDDの中でも最も大きくなるセクションの一つで、ソフトウェアを実装するための設計パターンと設計原則を説明する。システムの構造やデータの流れを視覚的に表現する図やモデルも含める。設計案がプロジェクトの要件を満たし、特定された問題に対処する方法を説明する。最後に、選択するテクノロジーとツールや、それをプロジェクトで使用する妥当性も記述する。

5.変更の予定

　プロジェクトの変更予定を詳しく示す一覧を含める。変更予定を通知する最善の方法は、次の詳細を表形式で示すことだ。

• 変更の概要（変更の目的や予想される影響など）
• 詳細説明（現在の状態、提案する状態、変更の理由など）

　変更の範囲によって、他のシステムコンポーネントや外部システムと、変更の予定との依存関係によって影響を受けるアプリケーションコンポーネントの概要を示す。

6.テスト計画

　SDDのテスト計画セクションには、プロジェクトのテスト計画へのリンクを含める。以前は完全なテスト計画を含めるのが標準だったが、現在はオンラインドキュメントが主流になり、テスト計画へのリンクだけを含める方が容易だ。

7.監視計画

　このセクションには、監視の詳細計画を含める。例えば、パイロットフェーズでアプリケーションが受け取ったユーザートラフィックを調べ、そのトラフィックに関連する可観測性の指標などを含める。

8.デプロイ計画

　SDDのデプロイ（展開）計画セクションには、アプリケーションを運用環境にデプロイするための詳しい計画と枠組みを含める。デプロイ計画もSDDで最も大きくなるセクションの一つで、ソフトウェアデプロイに必要な次のようなさまざまな側面を説明する。

• 概要（デプロイ計画の簡単な概要、デプロイの目標、主な関係者など）
• デプロイの方針（デプロイの方法、方針の正当性など）
• デプロイの前提条件（システムと環境の前提条件、構成設定、データ移行の要件、セキュリティとコンプライアンスの確認など）
• デプロイの各フェーズ（デプロイの各フェーズの詳細手順、スケジュール、マイルストーン、チームメンバーの責務など）
• デプロイ環境（特にターゲットにする環境）
• 環境の設定と構成の手順
• 検証と妥当性確認の手順
• ツールとリソース（デプロイとリソース割り当てに必要なツールの一覧など）
• デプロイテスト（デプロイ前のテスト手順、デプロイの成功基準、デプロイ後の検証手順など）
• リスク管理（可能性のあるリスクの特定、リスク緩和の方針、緊急時対応計画など）

9.コミュニケーション計画

　SDDのコミュニケーション計画セクションでは、プロジェクト関係者への通知方針の概要を示し、プロジェクトの進捗（しんちょく）状況と重要な決定事項を関係者に、いつ、どのように通知するかを詳しく説明する。関係者全員がスケジュールとシステムダウンタイムを確実に把握できるように、デプロイのスケジュールや通知の仕様を決める。

　このセクションでは、進捗レポートの頻度と形式など、全員の足並みをそろえるための報告プロセスについても説明する。さらに、文書化のプロセスを詳しく示し、プロジェクトのライフサイクル全体で作成、保守、共有する文書を強調する。この計画により、コミュニケーションチャネルが明確に定義され、関係者全員がアクセス可能になる。最後に、関係者の懸念を効果的に収集して対処するためのフィードバックメカニズムを用意する。

10.文書化計画

　技術文書を製品の一部として扱うことは極めて重要だ。そのため、SDDには製品に同梱する技術文書に関するセクションを用意する。オンラインヘルプやユーザー支援文書を作成する方針と手順を詳しく説明する。

11.ロールバック計画

　主にアプリケーションから社外の有料顧客にサービスを提供する場合、アプリケーションを以前のバージョンにロールバックするための計画とオーケストレーションが必要になる。SDDには、プロジェクトのロールバック計画をステップバイステップで示す細かい計画を含める。

12.プロジェクトの影響

　SDDのプロジェクトの影響セクションでは、コスト分析、セキュリティ分析、他の業務部門への影響、リスク分析に重点を置いて説明する。

13.評価基準

　SDDの評価基準セクションには、システムのパフォーマンスと有効性を測定する特定の指標とベンチマークを含め、機能要件と機能以外の要件（使いやすさ、信頼性、スケーラビリティなど）のテスト手順と成功基準を概説する。さらに、設計が関係者のニーズと期待を満たすことを確認するために、ユーザーからフィードバックを集めて分析する方法も指定する。

14.作業スケジュール

　SDDでは、プロジェクトの作業スケジュールも周知する。SDDをチームコラボレーションツールに公開する場合は、プロジェクト管理アプリケーションのプロジェクトスケジュールにリンクするか、スケジュールをSDDに盛り込む機会を探る。

15.使用する参考資料

　このセクションでは、SDDの各段階で参考にした第三者のリソースを取り込み、文書にする。ここには、次のような標準的な参考資料を含める。

• 社内文書（要件書や関連文書など）
• SDDの作成中に参考にしたアナリスト報告書
• 社内方針を示す文書やプレゼンテーションの資料

優れたソフトウェア設計仕様書を作成するためのヒント

　SDDの作成は、多くの場合、チームの専門知識と才能を結集したチーム作業になる。誰もが執筆業を本業とするわけではない。

コンテンツの管理

　SDDの作成では、チームメンバーの専門知識に応じて執筆チームを編成し管理することが重要だ。

• チームメンバー全員がSDD全体の作成に取り組む必要はないことを前提として、担当者を割り当てる
• ビジネスアナリスト、テクニカルライター、テクニカルリーダーなどの中から、SDDの執筆と編集の担当者を調整する
• アイデアの創出から完成までの間、SDDプロジェクトのコンテンツはさまざまな担当者が執筆するため、そうしたコンテンツのトーンとスタイルを1つにまとめる技術知識をしっかりと備える担当者をチームの中核に据える
• 自社のスタイルガイドに従うようエンジニアや技術スタッフに文章のスタイルを強いるのではなく、むしろ、文章をシンプルかつ簡潔に保つように促し、成功への道筋を示す
• 文章を書くのが苦手なチームメンバーは、抵抗なく文章を書けるメンバーと連携し、文章の執筆段階で実用的なフィードバックを提供できるテクニカルライターや編集者の協力を仰ぐ

SDDの編集

　SDDの編集は、スケジュールが短く、部門横断型チームが対応するという性質上、きめ細かく行うことが重要だ。SDDを編集するに当たっては、チームメンバーの専門知識に注目する。例えば、元の文書よりも文法上の間違いが増える可能性があるため、アーキテクトやバイスプレジデントに文法の編集を依頼してはいけない。チームメンバーの得意分野に基づき、次のように編集の役割を定める。

• 発展的編集：業務関係者がSDDの草稿に疑問を呈するのに理想的だ。業務関係者はコンテンツに集中でき、SDDの方向性について建設的なフィードバックができるようになる
• テクニカルレビュー：エンジニアやアーキテクトがSDDの技術的正確性と実現可能性をレビューする
• コンテンツ編集：テクニカルライターがSDDコンテンツの文法、流れ、一貫性、影響をレビューする。一般的には、テクニカルライターの編集により、チームのアナリスト、エンジニア、アーキテクトに疑問が投じられる可能性がある

　SDDは複数の担当者が執筆を担当するため、編集とコメントを追跡することが重要になる。

SDDの執筆

　複雑で読みにくいSDDは、プロジェクト管理上の事故を招く恐れがある。SDDプロジェクトでテクニカルライターを確保できる場合でも、次の重要なヒントに従うようにする。

• 読みやすくなるよう、文章と段落を短くする
• 必要に応じて、特に部品表や図表などの例を多用する
• SDDの執筆者を支援するため、AI（人工知能）を活用するライティングツールを実装する
• SDDが読みやすくなるよう、見出しのスタイルを多用する

　特に一般的なAI使用ポリシーが自社にない場合は、生成AIを利用して草稿を作成するのはリスクを伴う可能性がある。

図表を含める

　SDDに図表を取り入れると、さらに読みやすくなる。SDDでは、次のような図表の利用を検討する。

• クラウドアーキテクチャ図
• ネットワーク図
• スケジュール表

フィードバックの収集

　SDDに関するフィードバックの収集は、1回限りのレビュー作業ではなく、継続的な活動にする必要がある。チームと社内関係者は、SDDの重要なバージョン全てにフィードバックを提供する必要がある。

SDDの定期更新

　クラウドネイティブアプリケーションの複雑なSDDを作成するには、時間と専門知識が必要になる。プロジェクトライフサイクルの一環として開発チームがSDDを更新するためのプロセスとゲートを設けることで、チームは時間と専門知識を確保できる。