アジャイル開発に設計書は本当に必要か？実務で求められる4つの設計書と効果的な運用方法
アジャイル開発では「動くソフトウェアを重視する」という原則から、設計書は不要という誤解が広がっています。しかし、実際の開発現場では適切な設計書がなければプロジェクトの混乱を招くケースも少なくありません。
本記事では、アジャイル開発における設計書の真の役割と、実務で本当に必要な設計書の種類、そして開発スピードを損なわずに設計書を運用する実践的な方法を解説します。
プロダクトバックログだけでは補えない設計書の価値を理解することで、より質の高い開発体制を構築できるでしょう。
アジャイル開発における設計書の位置づけ
アジャイル宣言と設計書の関係
2001年に発表されたアジャイルソフトウェア開発宣言では、「包括的なドキュメントよりも動くソフトウェアを」と謳われています。ただし、この原則を「ドキュメント作成を一切しない」と解釈するのは誤りです。
宣言の補足説明では、「右側のものに価値があることを認めながらも、左側のものにより価値をおく」と明記されています。つまり、ドキュメントそのものを否定しているわけではなく、優先順位の問題なのです。
実際の開発現場では、ドキュメントがまったくない状態では以下のような問題が発生します。
新しいメンバーがジョインした際のオンボーディングに膨大な時間がかかる
システムの全体像が見えず、影響範囲の把握が困難になる
技術的負債が蓄積し、リファクタリングの判断基準が曖昧になる
ステークホルダーへの説明責任を果たせない
なぜ「設計書不要論」が生まれたのか
設計書不要という誤解が広がった背景には、ウォーターフォール開発への反省があります。
従来のウォーターフォール開発では、開発着手前に数百ページにも及ぶ詳細設計書を作成することが一般的でした。しかし、こうした大量のドキュメントには問題がありました。
まず、作成に膨大な時間がかかる割に、実装段階で仕様変更が発生すると即座に陳腐化してしまいます。さらに、ドキュメントのメンテナンスコストが高く、実際のコードとドキュメントの乖離が常態化していました。
アジャイル開発はこうした問題への解決策として登場しましたが、「包括的な設計書は不要」という原則が「設計書そのものが不要」と誤解されるケースが増えてしまったのです。
実際には、アジャイル開発でも設計書は必要ですが、その形式や粒度、メンテナンス方法が従来と異なるというのが正しい理解です。
アジャイル開発で設計書が果たす3つの役割
設計書には、プロダクトバックログでは代替できない独自の価値があります。ここでは、アジャイル開発における設計書の具体的な役割を見ていきましょう。
1. システム全体像の可視化と共通認識の形成
プロダクトバックログは「何を作るか」を管理するツールであり、機能ごとのタスクが列挙されています。一方で、システム全体の構造や各機能の関連性は見えにくいという課題があります。
設計書は、システムアーキテクチャやデータフロー、各コンポーネント間の依存関係を俯瞰的に示すことで、チーム全体の共通認識を形成します。特に複数のマイクロサービスを組み合わせた大規模システムでは、全体像を把握できる設計書の存在が不可欠です。
例えば、新しい機能を追加する際、その機能が既存のどのコンポーネントに影響を与えるのかを判断するには、システム構成図やデータベース設計が必要になります。
2. 技術的意思決定の記録と継承
開発の過程では、さまざまな技術的な意思決定が行われます。なぜこのアーキテクチャを選んだのか、なぜこのライブラリを採用したのか、といった判断基準は、将来のリファクタリングや機能拡張の際に重要な情報となります。
こうした意思決定の背景を記録していないと、後から参加したメンバーが「なぜこのような実装になっているのか」を理解できず、結果として不適切な変更を加えてしまうリスクが生じます。
設計書には、単なる「現状の設計」だけでなく、「なぜその設計を選択したのか」という文脈も含めて記録することで、知識の継承がスムーズになります。
3. 外部連携とステークホルダーへの説明責任
アジャイル開発であっても、外部システムとの連携や、顧客・経営陣への説明が必要な場面は多々あります。
特に受託開発や大企業での内製開発では、システムの仕様や設計を文書化することが契約上求められるケースも少なくありません。また、セキュリティ監査やコンプライアンスチェックの際にも、適切なドキュメントが必要です。
プロダクトバックログだけでは、こうした外部への説明には不十分です。設計書があることで、技術的な詳細をわかりやすく伝え、関係者の信頼を得ることができます。
実務で本当に必要な4つの設計書
アジャイル開発において、すべての設計書が等しく重要というわけではありません。ここでは、実務で優先的に作成すべき4つの設計書を紹介します。
システム構成図：全体像を一目で把握する
システム構成図は、サーバー、データベース、外部API、フロントエンドなど、システムを構成する要素とその関係性を図示したものです。
この図があることで、新規メンバーがシステムの全体像を素早く理解できるだけでなく、インフラの変更や新機能追加時の影響範囲を判断しやすくなります。
システム構成図に含めるべき要素は以下の通りです。
Webサーバー、アプリケーションサーバー、データベースサーバーの構成
使用しているクラウドサービス（AWS、GCP、Azureなど）
外部APIとの連携ポイント
認証・認可の仕組み
データの流れ（リクエスト/レスポンスの経路）
システム構成図は、AWSのアーキテクチャ図のように視覚的にわかりやすく作成することが重要です。テキストベースでの説明だけでは理解に時間がかかるため、図による可視化が不可欠です。
ER図：データ構造の設計と整合性の担保
ER図（Entity-Relationship Diagram）は、データベースのテーブル構造とテーブル間の関連性を示す図です。
アジャイル開発では機能ごとに段階的にテーブルを追加していくことが多いため、データベース設計の全体像を把握しづらくなりがちです。ER図を作成・更新し続けることで、以下のメリットが得られます。
データの重複や不整合を防ぐ
新しいテーブルを追加する際、既存のテーブルとの関連を考慮できる
パフォーマンス改善のためのインデックス設計が容易になる
個人情報保護法対応など、データガバナンスの観点で管理すべき情報を可視化できる
ER図の作成には、MySQL Workbenchやdraw.io、Lucidchartなどのツールが利用できます。最近では、データベースのスキーマから自動的にER図を生成するツールも充実しているため、メンテナンスの負担も軽減されています。
画面仕様書：UIの挙動と状態遷移の明確化
画面仕様書は、各画面の要素、ユーザーアクション、状態遷移を記載したドキュメントです。
Webアプリケーションやモバイルアプリの開発では、画面ごとの挙動を明確にしておかないと、実装者によって解釈が異なり、ユーザー体験に一貫性がなくなるリスクがあります。
画面仕様書に含めるべき情報は以下の通りです。
画面のワイヤーフレームまたはモックアップ
各UI要素の名称と役割
ユーザーが実行できるアクション（ボタンクリック、入力、スワイプなど）
バリデーションルール（入力チェック、エラーメッセージ）
画面遷移のフロー
権限による表示の出し分け
FigmaやAdobe XDといったデザインツールを活用することで、デザインと仕様を一体化させた画面仕様書を作成できます。デザイナーとエンジニアが同じツールを使うことで、コミュニケーションコストも削減されます。
API仕様書：フロントエンドとバックエンドの連携を円滑にする
API仕様書は、バックエンドが提供するAPIのエンドポイント、リクエスト/レスポンスの形式、エラーハンドリングを記載したドキュメントです。
フロントエンド開発とバックエンド開発を並行して進めるアジャイル開発では、API仕様が明確でないと以下のような問題が発生します。
フロントエンドとバックエンドで想定しているデータ形式が異なる
エラーハンドリングの実装が不十分になる
APIの変更があった際、影響範囲の把握が困難になる
API仕様書には以下の情報を含めます。
エンドポイントURL（例：POST /api/v1/users）
HTTPメソッド（GET、POST、PUT、DELETEなど）
リクエストパラメータ（必須/任意の区別、データ型、制約）
レスポンスの形式（JSON構造、ステータスコード）
認証・認可の方法（JWT、OAuth2など）
エラーレスポンスの種類と対処方法
OpenAPI（旧Swagger）やPostmanなどのツールを使えば、コードからAPI仕様書を自動生成でき、常に最新の状態を保てます。こうした自動化の仕組みを導入することで、ドキュメントのメンテナンスコストを大幅に削減できます。
プロダクトバックログと設計書の使い分け
アジャイル開発の中心的なツールであるプロダクトバックログと設計書は、それぞれ異なる役割を持っています。両者を適切に使い分けることが、効率的な開発の鍵となります。
プロダクトバックログの役割と限界
プロダクトバックログは、プロダクトに実装すべき機能や改善項目を優先順位付けして管理するリストです。各項目（ユーザーストーリー）には、「誰が」「何を」「なぜ必要とするのか」が記載されます。
プロダクトバックログの強みは、ビジネス価値の高い機能から優先的に開発できる点です。また、ステークホルダーとの合意形成にも活用できます。
しかし、プロダクトバックログには以下のような限界があります。
システムの技術的な構造や依存関係は見えない
実装の詳細や設計判断の根拠は記録されない
データベース設計やAPIの仕様といった技術的な詳細は管理対象外
過去の意思決定の履歴や、なぜその選択をしたのかという文脈が残らない
つまり、プロダクトバックログは「何を作るか」を管理するツールであり、「どのように作るか」を記録するものではありません。
設計書が補完すべき領域
設計書は、プロダクトバックログではカバーできない技術的な詳細を補完します。
具体的には、以下のような情報を設計書で管理すべきです。
システム全体のアーキテクチャと各コンポーネントの責務
データモデルと正規化の方針
APIの仕様とバージョン管理の戦略
セキュリティ対策（認証、認可、データ暗号化）
パフォーマンス要件と最適化の方針
技術的負債の記録と今後の改善計画
こうした情報を設計書として整理しておくことで、開発チームは技術的な一貫性を保ちながら、スピード感を持って開発を進められます。
使い分けの実践例
実際の開発現場では、以下のように使い分けるとよいでしょう。
プロダクトバックログで管理すべき内容：
ユーザーストーリー（新機能の要件）
バグ修正
ユーザー体験の改善提案
ビジネス要件の変更
設計書で管理すべき内容：
システム構成図（インフラ、サーバー構成）
ER図（データベース設計）
API仕様書（エンドポイント、リクエスト/レスポンス）
画面仕様書（UI/UX設計）
技術選定の理由と制約条件
両者を適切に使い分けることで、ビジネス側と技術側の両方の視点をバランスよく管理できるようになります。
設計書作成でスピードを損なわないための5つの実践テクニック
アジャイル開発のメリットである「スピード感」を維持しながら設計書を作成・運用するには、いくつかの工夫が必要です。ここでは、実務で効果的な5つのテクニックを紹介します。
1. 必要最小限の粒度で作成する
設計書は詳細であればあるほど良いわけではありません。過度に詳細な設計書は、作成に時間がかかり、メンテナンスコストも高くなります。
必要最小限の粒度とは、「その情報がないと開発が進められない、または後で混乱が生じる」レベルの情報のみを記載することです。
例えば、API仕様書であれば、すべてのレスポンスフィールドの詳細説明を書くのではなく、主要なフィールドと特殊なケースのみを記載します。細かい仕様はコード内のコメントやSwaggerの自動生成で補うことで、ドキュメントの負担を減らせます。
2. テキストベースで更新しやすい形式を選ぶ
WordやPowerPointで作成した設計書は、見た目は整っていますが、更新が手間です。特に複数人で同時に編集する場合、バージョン管理が困難になります。
代わりに、Markdownやテキストベースの形式で設計書を作成し、Gitで管理することをおすすめします。これにより、以下のメリットが得られます。
コードと同じリポジトリで管理でき、変更履歴が追跡しやすい
Pull Requestでレビューできる
差分が明確で、何が変わったのかがすぐにわかる
テキストエディタで編集でき、作業効率が高い
Notion、Confluence、GitHubのWiki機能なども、テキストベースで編集しやすく、チーム全体で共有しやすいツールです。
3. 自動生成ツールを積極的に活用する
設計書の一部は、コードやデータベースから自動生成できます。手作業で作成・更新する負担を減らすために、以下のようなツールを活用しましょう。
OpenAPI/Swagger: コードからAPI仕様書を自動生成
TypeDoc/JSDoc: JavaScriptやTypeScriptのコードからAPIドキュメントを生成
SchemaSpy: データベースからER図とテーブル定義書を自動生成
PlantUML: テキストからUML図を生成
こうしたツールを導入することで、設計書とコードの乖離を防ぎ、常に最新の状態を保つことができます。
4. タスクを細分化して段階的に作成する
すべての設計書を一度に作成しようとすると、大きな負担になります。代わりに、スプリントごとに必要な部分だけを作成・更新するアプローチを取りましょう。
例えば、新しいAPI機能を実装するスプリントでは、該当するAPIの仕様書のみを作成します。既存のAPI仕様書には影響しないため、作業負荷を最小限に抑えられます。
また、タスクを「システム構成図の作成」「ER図の更新」といった単位で細分化し、プロダクトバックログに組み込むことで、設計書の作成もスプリント計画に組み込めます。
5. ドキュメント作成を「完了の定義（Definition of Done）」に含める
設計書の作成を後回しにすると、結局更新されないまま放置されることがよくあります。これを防ぐには、各ユーザーストーリーの「完了の定義」にドキュメントの更新を含めることが有効です。
例えば、以下のような完了の定義を設定します。
コードがレビューされ、マージされている
ユニットテストが書かれ、すべてパスしている
API仕様書が更新されている（新しいエンドポイントの場合）
ER図が更新されている（新しいテーブルの場合）
こうすることで、ドキュメント作成が開発プロセスの一部として組み込まれ、継続的に更新される仕組みができあがります。
設計書なしで開発するリスクと実際に起きた問題
設計書を軽視すると、どのような問題が発生するのでしょうか。ここでは、実際の開発現場で起こりがちな課題を見ていきます。
オンボーディングの長期化
新しいメンバーがプロジェクトに参加した際、設計書がないとシステムの全体像を理解するのに膨大な時間がかかります。
経験豊富なメンバーに質問しながら学ぶことになりますが、その結果、既存メンバーの生産性も低下します。また、口頭での説明だけでは情報が断片的になり、正確な理解が難しくなります。
あるプロジェクトでは、新規エンジニアが独力でシステムを理解するのに3ヶ月かかり、その間は簡単なバグ修正しかできなかったという事例があります。もしシステム構成図とER図があれば、この期間を1ヶ月程度に短縮できたでしょう。
影響範囲の見落としとバグの発生
設計書がないと、機能変更やリファクタリングの際に影響範囲を見落とすリスクが高まります。
例えば、あるテーブルのカラム名を変更したとき、そのテーブルがどこで使われているかが可視化されていないと、一部の機能で不具合が発生します。ER図があれば、どのテーブルと関連しているかが一目でわかり、影響範囲を正確に把握できます。
技術的負債の蓄積
設計書がないと、過去の技術的な判断の背景がわからず、不適切な変更が加えられることがあります。
ある開発チームでは、パフォーマンス上の理由で非正規化したテーブル設計を採用していました。しかし、その経緯が記録されておらず、後任のエンジニアが「正規化すべきだ」と判断して変更した結果、クエリのパフォーマンスが大幅に悪化したという事例があります。
設計書に「なぜこの設計を選択したのか」という理由を記載しておけば、こうした問題は防げたでしょう。
ステークホルダーとの認識齟齬
外部との連携やステークホルダーへの説明が必要な場面では、設計書がないと認識の齟齬が生じやすくなります。
受託開発では、顧客に対してシステムの仕様や設計を説明する機会が多くあります。その際、口頭やチャットだけでの説明では誤解を招きやすく、後からトラブルになることがあります。
きちんとした設計書があれば、客観的な証拠として提示でき、無用な争いを避けられます。
効果的なツールの選び方と運用のポイント
設計書を効率的に作成・管理するには、適切なツールの選定と運用方法が重要です。
チケット管理ツールとの統合
JiraやBacklog、Asanaといったチケット管理ツールは、プロダクトバックログの管理に適していますが、設計書の記載には向いていません。
ただし、チケット内に設計書へのリンクを記載しておくことで、関連する設計情報にすぐアクセスできるようになります。例えば、「新しいユーザー登録API」というチケットに、API仕様書のURLを貼っておくイメージです。
ドキュメント管理ツールの活用
設計書の作成には、以下のようなツールが適しています。
Notion: 階層的にページを整理でき、テーブルやデータベース機能も充実
Confluence: エンタープライズ向けで、アクセス権限の管理が柔軟
GitHubのWiki: コードと同じリポジトリで管理でき、エンジニアにとって使いやすい
Docusaurus: 静的サイトジェネレーターで、技術ドキュメントに特化
どのツールを選ぶかは、チームの規模や開発スタイルによって異なりますが、全員が編集しやすく、検索性が高いツールを選ぶことが重要です。
バージョン管理の徹底
設計書も、コードと同様にバージョン管理すべきです。Gitで管理することで、誰がいつ何を変更したのかが記録され、必要に応じて過去のバージョンに戻すこともできます。
特にAPI仕様書は、バージョンごとに互換性を保つ必要があるため、v1、v2といった形でドキュメントを分けて管理するとよいでしょう。
まとめ：設計書とアジャイルは対立しない
アジャイル開発における設計書は、ウォーターフォール開発のような包括的なドキュメントではなく、必要最小限の情報を適切なタイミングで作成・更新するものです。
設計書とアジャイルは対立する概念ではありません。むしろ、適切な設計書があることで、アジャイル開発のスピード感と柔軟性をさらに高めることができます。
本記事で紹介した4つの設計書（システム構成図、ER図、画面仕様書、API仕様書）は、実務で最も価値の高いドキュメントです。まずはこれらから始めて、チームの状況に応じて調整していきましょう。
プロダクトバックログだけでは補えない技術的な詳細を設計書で補完し、ビジネス価値と技術的な健全性の両立を目指してください。
参考情報
