仕様駆動開発の仕様書について考えてみる その２

はじめに

前回は、仕様駆動開発（Spec-Driven Development）に適した仕様書について、目次とその内容について考えてみました。

早速その目次と内容に従って、設計ドキュメントの雛形を作成してみました。まだ初版（2025年11月時点）ですがGitHubで公開していますので、興味のある方はご覧ください。

https://github.com/naoji3x/grandma-candy-shop

単にリポジトリを公開するのも面白くないので、以下の物語に沿って、仕様書やコードを追加していきたいと思います。

物語があると、仕様書を書くモチベーションも上がりますし、コードを書くモチベーションも上がります。さらに、物語に沿って仕様書やコードを書いていくことで、実際の開発現場で起こりうる様々なシナリオを想定しながら進めることができます。

なお、物語は別の記事で投稿していきます💫

あらすじ

主人公はCoderDojoに通う小学６年生の天才少年、算野創太。

最近、おばあちゃんの物忘れが多くなってきて、営んでいる「駄菓子屋きぬや」でいろいろな問題が発生するようになってきました。創太はおばあちゃんのために、駄菓子屋の運営を支援するシステムを作ることを決意します。

登場人物

ChatGPTにキャラクター設定・イメージ作成を手伝ってもらいました。以下が登場人物の一覧です。

算野 創太(さんの そうた)

主人公。小学６年生の天才少年。プログラミングが得意でCoderDojoに通う。

算野 きぬ(さんの きぬ)

おばあちゃん。駄菓子屋「きぬや」の店主。物忘れが激しいが優しい性格。

堂ノ前 進(どうのまえ すすむ)

CoderDojoのメンター。主人公の師匠でありアドバイザー。CoderDojoでは師匠と呼ばれる。

踊川 舞(おどりかわ まい)

幼馴染の友達。ダンスが得意。主人公を支え、駄菓子屋の常連。一緒にCoderDojo通い。

金田 玲奈(かねだ れいな)

小学校の友達。お金持ちの令嬢。主人公に好意を抱いている。実は隠れた駄菓子屋の常連。一緒にCoderDojo通い。

剛力 大地(ごうりき だいち)

創太のクラスメイト。いじめっ子でイタズラ好きだが寂しがり屋。

風間 隼人(かざま はやと)

創太のクラスメイト。主人公にライバル心を抱くが内心尊敬している。

春野 さくら(はるの さくら)

創太くんのいとこ。保育士のお姉さん。明るく優しい性格で子どもたちに人気。

肉山 力(にくやま ちから)

肉屋「肉山精肉店」店主。豪快で力持ち。算野家の常連。

青葉 菜男(あおば なおと)

八百屋「青葉青果」店主。明るく世話好き。算野家をよく手伝う。

金森 徹子(かなもり てつこ)

金物屋「金森金物店」店主。しっかり者で面倒見が良い。算野家を支援。

---

ドキュメント一覧と内容

ドキュメントの内容、順番も少し見直しました。今後、プロジェクトを進める中で、必要に応じてドキュメントを追加・修正していく予定です。

000-プロジェクト

ドキュメント	目的	主な内容	サンプル（抜粋イメージ）
010-プロジェクト概要	プロジェクトの背景と狙いを共有する	背景・目的・必要性・期待効果・前提条件	「本プロジェクトは、店舗在庫の欠品率を年間○％削減することを目的とする。」
020-プロジェクトスコープ	対象範囲／対象外を明確にする	対象業務、対象システム、対象期間、スコープ外	「対象：店舗〜本部の在庫・発注業務／対象外：仕入先側システム改修」
030-プロジェクト課題と解決アプローチ	取り組むべき課題と解決策の方針を整理する	課題一覧、原因、解決策候補、選択したアプローチと理由	「課題：欠品が多い／解決策案：安全在庫見直し、自動発注導入… 採用：自動発注＋見直し（理由：効果とコストのバランス）」

010-業務仕様

ドキュメント	目的	主な内容	サンプル（抜粋イメージ）
010-概念データフロー図	業務レベルの情報の流れを可視化	「誰が・何を・誰に」などの情報フロー図	「店員 → POS『販売データ』→ 在庫管理 → 発注管理『発注候補』」
020-概念クラス図	業務上のエンティティ関係を整理	商品・在庫・発注・店舗などの概念と関連	「商品 1..在庫、店舗 1.. 在庫、発注 1..* 発注明細」
030-ビジネスルール	業務上の判断・処理ルールを明文化する	ルールID、条件、結果、例外、根拠	「BR-001: 在庫数＜発注点 の場合、自動発注候補を生成する。」
040-状態遷移図	業務オブジェクトの状態変化を整理	状態、遷移イベント、遷移条件、禁止遷移	「注文：『登録』→『承認』→『出荷済』→『完了』」
050-画面仕様	業務ユーザー視点の画面要件を定義	画面一覧、目的、項目一覧、入力制約、ボタン動作、メッセージ	「画面：在庫一覧／項目：商品コード、商品名、在庫数、発注点、在庫状態…」
060-業務イベント一覧	業務上の重要な出来事を整理	イベントID、名称、トリガー、入力・出力データ、関係ロール	「EV-001: 販売発生／トリガー：会計完了／出力：販売伝票、在庫減少イベント」
070-システム化機能一覧	システムで実現する機能を一覧化する	機能ID、機能名、対応業務・イベント、実現手段、優先度	「F-001 在庫照会／対象：EV-001／手段：画面 INV-001／優先度：高」
080-用語集	用語の意味を統一する	用語、定義、備考、類似語・禁止語	「発注点：在庫がこの数量を下回ったときに発注候補とみなす基準数量。」
090-業務データ辞書	業務で扱う“項目”の意味を揃える	項目名、説明、単位、入力者、利用シーン、関連用語ID	「項目名：発注点／説明：用語集T-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-テスト観点・テスト条件一覧	何を確認すべきかを整理	業務観点、例外観点、非機能観点、要件・機能IDとのトレース	「TC-INV-001：在庫自動発注（条件：在庫＜発注点）」
030-単体テスト	単体テスト設計・結果を記録	クラス／メソッド単位のテストケース・期待値・結果	「StockService.adjust()：マイナス値禁止、0境界、正常加算…」
040-結合テスト	コンポーネント間結合の検証	結合パターン、ケース、期待値、結果	「画面→API→Service→Repository→DB の一連動作確認。」
050-システムテスト	システム全体の動作確認	業務シナリオテスト、非機能テスト結果	「日次業務のシナリオ（販売→発注→入荷）の通しテスト。」
060-受け入れテスト	ユーザー受け入れ結果を記録	業務受け入れ条件との対応、判定、指摘・要望	「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

この後は、物語に沿って仕様書やコードの追加・修正を行っていきます。

• 「仕様駆動開発の仕様書について考えてみる」シリーズでは、物語とは別に、各ドキュメントの具体的な中身や作成手順について詳しく解説していく予定です。
• 物語の方は「おばあちゃんの駄菓子屋」シリーズとして進めていきます。

どうぞお楽しみに！💫