📄
仕様駆動開発の仕様書について考えてみる その１
はじめに
2025年は、生成AIを活用したソフトウェア開発支援が大きな話題となっています。私も普段の開発でChatGPTやGitHub Copilotを活用していますが、これらのツールを最大限に活用するためには、仕様書の質が重要です。
最近は、SpecKitやOpenSpecといった仕様からコードを作成するツールやフレームワークも登場しており、仕様駆動開発（Spec-Driven Development）という考え方が注目されています。
一方で、これらのフレームワークでは、どのような仕様書を用意すれば良いのか、具体的な内容についてはあまり言及されていないように思います。生成AIが扱い易く、人も理解できて、記述も負担にならない、そんな仕様書の内容についてシリーズで考えてみたいと思います。
スコープ
システム開発の仕様書に特化しています。例えば、プロジェクト管理の領域や、投資判断の領域については対象外とします。
設計書の目次
早速ChatGPTに相談しながら作ってみました。SEC BOOKS：経営者が参画する要求品質の確保も参考にしています。最小限のドキュメント構成を目指しましたが、結構なボリュームになってしまいました。
ChatGPT 5 Thinkingに評価してもらいましたが、以下のように妥当な内容のようです。
総評
- 網羅性：業務システム向けとしてはほぼ満点クラス
- 記述のし易さ：構造は良いが、いくつかの境界に「書き分けルール」を足すとさらに良くなる
- 客観性・トレーサビリティ：ID付け＋相互参照ルールを入れればかなり強い
今の段階で「設計ドキュメントの土台」としては十分以上です。あとは、
- 各フォルダに「何を書く／何を書かないか」を1〜2行書いたREADMEを置く
- 要件・機能・テストにIDを振って、最低限のトレースルールを決める
- プロジェクトごとに「使うドキュメント種別」を決めて、軽量運用もできるようにする
この3つをやっておくと、「実務で回しやすい理想形」にかなり近づくと思います。
それでは、以下、目次です。
docs/
000-ビジネス/
プロジェクト概要/
プロジェクトスコープ/
プロジェクト課題と解決アプローチ/
010-業務ドメイン/
010-ビジネスルール/
020-用語集/
030-業務データ辞書/
040-概念データフロー図/
050-概念クラス図/
060-画面仕様/
070-状態遷移図/
080-業務イベント一覧/
090-システム化機能一覧/
100-業務受け入れ条件/
020-アーキテクチャ/
010-C4コンテキスト図/
020-C4コンテナ図/
030-C4コンポーネント図/
040-インフラ構成概要/
030-システム設計/
010-実装データフロー図/
020-実装クラス図/
030-DB設計/
010-論理設計/
020-物理設計/
040-シーケンス図/
050-実装画面仕様/
060-バッチ・ジョブ設計/
070-設定パラメータ一覧/
040-インターフェース/
010-API仕様/
020-外部システムIF/
030-メッセージ仕様/
050-品質/
010-非機能要件/
020-システム受け入れ条件/
030-アクセス制御/
040-エラー処理/
050-監査・モニタリング/
060-テスト/
010-テスト戦略・方針/
020-テスト計画/
030-テスト観点・テスト条件一覧/
040-単体テスト/
050-結合テスト/
060-システムテスト/
070-受け入れテスト/
080-移行/
010-業務移行方針/
020-データ移行設計/
030-カットオーバー計画/
090-決定記録/
ADR-0001-xxx.md
ADR-0002-xxx.md
ドキュメント一覧と内容
各々のドキュメントの目的、内容、サンプルは以下になります。
000-ビジネス
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| プロジェクト概要 | プロジェクトの背景と狙いを共有する | 背景・目的・必要性・期待効果・前提条件 | 「本プロジェクトは、店舗在庫の欠品率を年間○％削減することを目的とする。」 |
| プロジェクトスコープ | 対象範囲／対象外を明確にする | 対象業務、対象システム、対象期間、スコープ外 | 「対象：店舗〜本部の在庫・発注業務／対象外：仕入先側システム改修」 |
| プロジェクト課題と解決アプローチ | 取り組むべき課題と解決策の方針を整理する | 課題一覧、原因、解決策候補、選択したアプローチと理由 | 「課題：欠品が多い／解決策案：安全在庫見直し、自動発注導入… 採用：自動発注＋見直し（理由：効果とコストのバランス）」 |
010-業務ドメイン
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-ビジネスルール | 業務上の判断・処理ルールを明文化する | ルールID、条件、結果、例外、根拠 | 「BR-001: 在庫数＜発注点 の場合、自動発注候補を生成する。」 |
| 020-用語集 | 用語の意味を統一する | 用語、定義、備考、類似語・禁止語 | 「発注点：在庫がこの数量を下回ったときに発注候補とみなす基準数量。」 |
| 030-業務データ辞書 | 業務で扱う“項目”の意味を揃える | 項目名、説明、単位、入力者、利用シーン、関連用語ID | 「項目名：発注点／説明：用語集T-001参照／入力：商品マスタ画面（バイヤー）」 |
| 040-概念データフロー図 | 業務レベルの情報の流れを可視化 | 「誰が・何を・誰に」などの情報フロー図 | 「店員 → POS『販売データ』→ 在庫管理 → 発注管理『発注候補』」 |
| 050-概念クラス図 | 業務上のエンティティ関係を整理 | 商品・在庫・発注・店舗などの概念と関連 | 「商品 1..* 在庫、店舗 1..* 在庫、発注 1..* 発注明細」 |
| 060-画面仕様 | 業務ユーザー視点の画面要件を定義 | 画面一覧、目的、項目一覧、入力制約、ボタン動作、メッセージ | 「画面：在庫一覧／項目：商品コード、商品名、在庫数、発注点、在庫状態…」 |
| 070-状態遷移図 | 業務オブジェクトの状態変化を整理 | 状態、遷移イベント、遷移条件、禁止遷移 | 「注文：『登録』→『承認』→『出荷済』→『完了』」 |
| 080-業務イベント一覧 | 業務上の重要な出来事を整理 | イベントID、名称、トリガー、入力・出力データ、関係ロール | 「EV-001: 販売発生／トリガー：会計完了／出力：販売伝票、在庫減少イベント」 |
| 090-システム化機能一覧 | システムで実現する機能を一覧化する | 機能ID、機能名、対応業務・イベント、実現手段、優先度 | 「F-001 在庫照会／対象：EV-001／手段：画面 INV-001／優先度：高」 |
| 100-業務受け入れ条件 | 業務側から見た“OKライン”を明確化 | 業務シナリオ、期待結果、判定基準、関係KPI | 「UC-01 欠品アラート：欠品候補商品は前日までに一覧化され、バイヤーが対応できる。」 |
020-アーキテクチャ
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-C4コンテキスト図 | システムと外部主体の関係を俯瞰する | ユーザー、外部システム、本システムの関係図 | 「店舗スタッフ／バイヤー／外部仕入先システム ↔ 在庫・発注管理システム」 |
| 020-C4コンテナ図 | システム内部の“箱”構成を定義 | Web/UI、API、バッチ、DB、メッセージ基盤などの構成 | 「Webフロント、APIサーバ、ジョブサーバ、RDB、Kafka」 |
| 030-C4コンポーネント図 | コンテナ内の主要コンポーネントを定義 | サービス、リポジトリ、アダプタなど主要コンポーネントと依存関係 | 「在庫サービス、発注サービス、マスタ管理サービス、認証コンポーネント…」 |
| 040-インフラ構成概要 | インフラのざっくり構成を共有 | 利用クラウド、VPC構成、ネットワーク、環境構成（本番・検証） | 「AWS／東京リージョン、VPC1つ、ALB → EC2(API) → RDS(PostgreSQL)」 |
030-システム設計
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-実装データフロー図 | 実装レベルの処理・データの流れを定義 | サービス間、バッチ、キュー、外部IFのデータフロー | 「POS→API『/sales』→SalesService→在庫更新イベント→発注バッチ」 |
| 020-実装クラス図 | 実装クラス構造を定義 | クラス、インターフェース、継承関係、パッケージ構成 | 「StockService → StockRepository、OrderService → OrderRepository」 |
| 030-DB設計/010-論理設計 | 論理テーブル構造を定義 | エンティティ、テーブル名、項目、論理型、主キー・外部キー | 「TABLE: INVENTORY（product_id, store_id, qty, reorder_point,…）」 |
| 030-DB設計/020-物理設計 | 物理的なDB仕様を定義 | 物理型、インデックス、パーティション、表領域など | 「qty: INTEGER／IDX_INV_PRODUCT_STORE(product_id, store_id) 作成」 |
| 040-シーケンス図 | 処理の時系列の流れを明確化 | ユースケースごとのコンポーネント間メッセージ | 「ユーザー→画面→API→Service→Repository→DB の呼び順」 |
| 050-実装画面仕様 | UI実装の詳細仕様を定義 | 画面ID、ルーティング、コンポーネント構成、バリデーション、API連携 | 「/inventory-list は GET /api/inventories を呼び、レスポンスをテーブル表示。」 |
| 060-バッチ・ジョブ設計 | バッチ処理の実装仕様を定義 | ジョブID、実行タイミング、入力・出力、リトライ、エラー動作 | 「JOB-001 自動発注候補作成：毎日2:00／入力：INVENTORY／出力：ORDER_CANDIDATE」 |
| 070-設定パラメータ一覧 | 変更可能な設定項目を整理 | パラメータ名、説明、既定値、範囲、上書き階層、反映方法 | 「reorder.threshold.default=10／上書き：環境・店舗単位／再起動不要」 |
040-インターフェース
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-API仕様 | 画面や外部から利用されるAPIを定義 | エンドポイント、HTTPメソッド、リクエスト／レスポンス、ステータスコード | 「GET /api/inventories?storeId=… → 200: Inventory[]／404: NotFound」 |
| 020-外部システムIF | 他システムとの連携仕様を定義 | 対象システム、データ項目、フォーマット、伝送方法、スケジュール | 「仕入先システムへ発注データを日次CSV(SJIS)でSFTP送信」 |
| 030-メッセージ仕様 | イベント／キューのメッセージ仕様を定義 | トピック・キュー名、メッセージ構造、バージョン、再送・冪等方針 | 「topic: stock.changed payload:{productId, storeId, beforeQty, afterQty, changedAt}」 |
050-品質
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-非機能要件 | 性能・可用性などの品質要求を定義 | 性能、同時接続、可用性、保守性、運用性、セキュリティ | 「在庫照会API：平常時P95 500ms以内、ピーク時100 RPSを処理可能とする。」 |
| 020-システム受け入れ条件 | システム全体としての合格基準を定義 | 機能・非機能・障害・移行などの受け入れ条件 | 「性能試験で全てのNFRを満たし、重大障害0件であること。」 |
| 030-アクセス制御 | 認証・認可のルールを定義 | ロール、権限一覧、画面/APIごとのアクセス可否、権限変更フロー | 「店舗スタッフ：自店舗在庫のみ閲覧可／店長：全店舗閲覧可。」 |
| 040-エラー処理 | エラー時の挙動を統一する | エラー分類、ユーザ向けメッセージ方針、ログ、リトライ | 「外部APIタイムアウト：3回リトライ、失敗時はユーザに汎用メッセージ＋WARNログ出力。」 |
| 050-監査・モニタリング | ログ・監視・監査証跡の方針を定義 | 監査ログ項目、保持期間、監視メトリクス、アラート条件 | 「監査ログ：誰が・いつ・どの商品を・どの値からどの値に変更したかを記録（7年保管）。」 |
060-テスト
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-テスト戦略・方針 | 全体テストの考え方を示す | テストレベル、対象範囲、優先度、自動化方針 | 「ドメインロジックは単体〜結合まで自動化、UIは主要シナリオのみE2E。」 |
| 020-テスト計画 | テストのスケジュールと体制を定義 | テスト期間、体制、環境、役割、マイルストーン | 「結合テスト：○/○〜○/○、担当：開発チームA、環境：TEST01。」 |
| 030-テスト観点・テスト条件一覧 | 何を確認すべきかを整理 | 業務観点、例外観点、非機能観点、要件・機能IDとのトレース | 「TC-INV-001：在庫自動発注（条件：在庫＜発注点）」 |
| 040-単体テスト | 単体テスト設計・結果を記録 | クラス／メソッド単位のテストケース・期待値・結果 | 「StockService.adjust()：マイナス値禁止、0境界、正常加算…」 |
| 050-結合テスト | コンポーネント間結合の検証 | 結合パターン、ケース、期待値、結果 | 「画面→API→Service→Repository→DB の一連動作確認。」 |
| 060-システムテスト | システム全体の動作確認 | 業務シナリオテスト、非機能テスト結果 | 「日次業務のシナリオ（販売→発注→入荷）の通しテスト。」 |
| 070-受け入れテスト | ユーザー受け入れ結果を記録 | 業務受け入れ条件との対応、判定、指摘・要望 | 「UC-01：OK／UC-02：アラート閾値調整要望あり」 |
080-移行
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| 010-業務移行方針 | 旧業務→新業務への移行方針を定義 | 移行方式（一斉／並行）、影響範囲、教育・マニュアル方針 | 「1ヶ月間は旧システムと並行稼働し、差異確認後に新システムへ一本化。」 |
| 020-データ移行設計 | 旧DB→新DBの移行方法を定義 | 対象データ、マッピング、変換ルール、移行ツール／バッチ、検証方法 | 「旧 INV_OLD.qty → 新 INVENTORY.qty（単位変換なし）、無効商品は除外。」 |
| 030-カットオーバー計画 | 本番切替の具体手順を定義 | 当日タイムライン、作業手順、担当者、リハーサル・ロールバック手順 | 「T-1h: 旧システム停止／T+0h: データ移行開始／T+2h: 新システム起動／T+4h:業務利用開始。」 |
090-決定記録
| ドキュメント | 目的 | 主な内容 | サンプル（抜粋イメージ） |
|---|---|---|---|
| ADR-xxxx | 重要な設計・技術選択の決定理由を残す | 背景、決定した内容、検討した選択肢、採択理由、影響範囲 | 「ADR-0001: DBとしてPostgreSQL採用。代替：MySQL／理由：既存資産・チーム経験・機能要件。」 |
To be continued
この後は、プロジェクトの雛形を作って、各ドキュメントのサンプルファイルを用意してGitHubで公開しようと思います。また、各ドキュメントの書き方や運用方法についても考えていきたいと思います。
どうぞお楽しみに！💫
Discussion