00. この本の使い方
目的
- 本書の適用範囲（小〜中規模）と前提（TypeScript）を明確化する
- 「やらないこと」を先に固定し、設計判断の迷走を減らす
- 以降の章で使う用語（要求/要件/仕様/設計、結合、S/D/V、テストレベル）を揃える
得られる判断能力
- 「今の規模で必要な設計」と「過剰設計」を区別できる
- 要件・設計・テストの判断を、同一の基準（S/D/V、非機能の最小合意）で接続できる
- 章を読み進めるための前提（用語、進め方、題材）を揃えられる
対象読者 / 対象規模
- 対象読者: 小〜中規模の Web アプリ開発に関わるエンジニア（TypeScript を前提）
- 対象規模（例）:
- 1〜2 チーム程度（〜10 名規模）
- 仕様変更が週〜月単位で発生する
- 単一リポジトリでの開発が中心（必要に応じて分割）
非ゴール（この本では扱わない）
- 特定フレームワーク固有の最適化・詳細実装（例: Next.js 固有の最適化）
- 大規模前提のテンプレ（フル装備のクリーンアーキテクチャ、マイクロサービス化）
- 外部書籍/ガイドの本文転載（リンク参照で代替する）
- 実サンプルアプリの完成（必要なら別 Issue で扱う）
この本でやること（全体像）
本書は「良い設計パターン集」ではなく、要求から設計・テストまでを 同じ語彙と成果物 でつなぐための実務手順です。扱う対象を次の 4 つに分け、混同を避けます。
- 要求（Needs / Goals）: なぜやるか（ビジネス目的・課題・KPI）
- 要件（Requirements / Shall）: 何を満たすべきか（実装方法に依存しない約束）
- 仕様（Specification / Behavior）: どう振る舞うか（外部から観測できる振る舞いを曖昧さなく）
- 設計（Design / Structure）: どう作るか（内部構造・モジュール・アルゴリズム・DB物理など）
混同しやすいポイント:
- 要件は「約束（Shall）」であり、実装方法を含めない
- 仕様は「外から見える振る舞い」であり、内部構造を含めない
- 設計は「内部の作り方」であり、仕様の言い換えにならない（仕様を満たす複数の設計があり得る）
本書の章とテンプレ（Appendix）は、次の対応で進めます。
| 対象 | この段階で行うこと | 参照テンプレ | 主な章 |
|---|---|---|---|
| 要求 | 目的/課題/KPI/非ゴールを固定する | Appendix B-1 | 01 |
| 要件 | Shall を列挙し、スコープと非機能の最小合意を取る | Appendix B-2 | 01 |
| 仕様 | 受け入れ条件・例外系・外部I/Fの振る舞いを曖昧さなくする | Appendix B-3（任意: B-10, B-12） | 01 |
| 設計 | 境界・依存方向・データモデル等の構造を決め、S/D/V と ADR で根拠を残す | Appendix B-4〜B-7（任意: B-9/B-10） | 02〜04, 07 |
| テスト | 単体/統合/E2E の配分と最小セットを決める | Appendix B-8 | 05〜06 |
| 横断 | 要件→仕様→設計→テストの対応を追跡し、漏れを検知する | Appendix B-11（任意） | 01, 06 |
最小タイムライン（例: 1〜2週間の初期立ち上げ）
小〜中規模の開発で「実装を始められる最小合意」を作るための、タイムボックス例です（単一チーム/単一リポジトリ想定）。
前提:
- すべてを網羅しない（トップ要件/主要導線から始める）
- 迷いが出る論点だけを固定し、詳細は実装と学習に合わせて更新する
| フェーズ | 目安 | この段階で行うこと | 成果物（最小） | 次に接続する |
|---|---|---|---|---|
| 要求 | 0.5日 | 目的/課題/KPI/非ゴールを固定する | B-1 | 要件の優先順位 |
| 要件 | 0.5〜1日 | Shall を列挙し、スコープと非機能の最小合意を取る | B-2 | 仕様（受け入れ条件） |
| 仕様 | 1日 | 受け入れ条件・例外系・観測点を曖昧さなくする | B-3（任意: B-10, B-12） | 設計（境界/契約） |
| 相互作用/結合 | 0.5日 | 相互作用と依存の痛みを焦点化し、介入点を決める | B-9, B-4 | 設計アウトライン |
| 設計 | 1日 | 最小の境界・責務・依存方向・データモデルを決める | B-5（任意: B-7） | テスト配分 |
| テスト | 0.5日 | 単体/統合/E2E の配分と最小セットを合意する | B-8 | 実装/自動化 |
テンプレの本体は Appendix B、記入例は Appendix D を参照してください。
レビュー観点（最小）:
- 要求: KPI/非ゴールで迷いが減るか（「やらないこと」が明確か）
- 要件: Shall が実装方法に依存していないか（検証可能な約束になっているか）
- 仕様: 例外系と観測点があるか（合否判定ができるか）
- 設計: S/D/V の根拠があるか（変更容易性と運用が接続しているか）
- テスト: 仕様（B-3）と契約を守る投資になっているか（E2E が増殖していないか）
共通題材（ランニング例）
本書では、章を通して同一の題材で説明を一貫させます。
ランニング例: 小規模「タスク管理」+ 期限/権限/通知
- 主要機能:
- タスクの CRUD
- 状態遷移（例:
todo → in_progress → done） - 期限ルール（期限超過の扱い、期限変更の制約）
- 通知（メール送信を外部I/F例として扱う）
- 権限（管理者/一般ユーザー）
以降の章で「この題材なら、どこに相互作用が生まれ、どの結合を弱めるべきか」を具体化します。
学習の進め方
- 章を読む → 演習を解く → Appendix のテンプレに記入する、の順で進めます
- 演習結果は「判断ログ」として残すと、後から設計変更の根拠になります（ADR と親和性が高い）
- テンプレは「成果物の型」です。粒度や項目を必要最小限にしても、用語（要求/要件/仕様/設計）を混同しないことを優先します
本書の判断原則（背骨）
- 要求: 「なぜやるか」を KPI/課題として固定し、非ゴールで迷走を抑える
- 要件: 要求を「Shall（約束）」に落とし、検証可能な合意にする
- 仕様: 外部から観測できる振る舞いを曖昧さなく定義し、例外系も含める
- 設計: 結合（知識の共有）を 統合強度×距離×変動性（S/D/V） で扱い、最小の境界と構造を選ぶ
- テスト: 単体/統合/E2E を「価値導線」と「複雑さ」に応じて配分し、仕様と契約を守る
前提/用語
- 要求（Needs / Goals）: 利害関係者が「したいこと」。目的、課題、KPI として説明できる状態にする
- 要件（Requirements / Shall）: 実装方法に依存しない約束。「何を満たすべきか」を列挙できる
- 仕様（Specification / Behavior）: 外部から観測できる振る舞い（入力/出力、状態遷移、エラー）を曖昧さなく定義する
- 設計（Design / Structure）: 仕様を満たすための内部構造（境界、モジュール、アルゴリズム、DB物理など）
- S/D/V: 結合を扱うための物差し（統合強度 / 距離 / 変動性）
要点
- 小規模では「抽象化のコスト」が支配的になりやすい（過剰設計が損失）
- 設計は「最適化」ではなく「制約の設定」として扱うと破綻しにくい
- テストは網羅率ではなく、価値導線と変更容易性を守る投資として配分する
演習（最小1個）
- 自分の対象システムを 1 行で要約する（例: 「社内向けの申請・承認Web」）。
- 「やらないこと（非ゴール）」を 5 つ書く（例: マルチテナント化しない）。
- 期待するアウトカム（KPI/業務効果）を 2 つ書く。
よくある失敗
- 「将来の拡張」を根拠に、現時点で不要な抽象化を導入する
- 要件が曖昧なまま UI 実装に着手し、手戻りを正当化してしまう
- テストを「あとで追加」する前提で設計し、結局追加できない
チェックリスト
- 対象の規模（ユーザー数/チーム規模/変更頻度）を言語化できる
- 非ゴールを合意できる（少なくともチーム内）
- 受け入れ条件の粒度イメージを共有できる
- S/D/V の定義をチームで共有できる