要件から始めるソフトウェア設計（小規模TS Webアプリの実践）

小〜中規模の Web フロントエンドを持つシステム（TypeScript 想定）を対象に、要件定義→設計→テストまでを「一貫した判断基準」で進めるための実践教材です。

想定読者

• 対象読者: 小〜中規模の Web アプリで、要求整理〜要件定義〜設計〜テスト方針の策定に関わる実務者（エンジニア/PM/テックリード）
• 前提知識: TypeScript と Web の基本（HTTP/REST、Git の基礎、一般的なチーム開発の流れ）

この本の目的

• 要求を「合意された要件」に変換し、設計入力として扱えるようにする
• 結合を「統合強度×距離×変動性（S/D/V）」で捉え、過剰設計を避ける
• 価値と保守性を前提に、単体/統合/E2E の配分を複雑さに応じて決められるようにする

本書の前提用語（要求/要件/仕様/設計）

本書では、議論の対象を次の 4 つに分けます（混同しないための整理です）。

• 要求（Needs / Goals）: なぜやるか（ビジネス目的・課題・KPI）
• 要件（Requirements / Shall）: 何を満たすべきか（実装方法に依存しない約束）
• 仕様（Specification / Behavior）: どう振る舞うか（外部から観測できる振る舞いを曖昧さなく）
• 設計（Design / Structure）: どう作るか（内部構造・モジュール・アルゴリズム・DB物理など）

この 4 つを、章とテンプレ（Appendix）に対応させて進めます。

非ゴール（本書では扱わない）

• 特定フレームワーク（例: Next.js）固有の最適化・詳細実装
• 大規模前提のテンプレ（フル装備のクリーンアーキテクチャ、マイクロサービス化）
• 参照書籍・PDF本文の転載
• 実サンプルアプリの完成（必要なら別 Issue）

読み方ガイド

• 初めて読む場合は、00 → 01 → 02 → 03 → 04 → 05 → 06 → 07 の順を推奨します
• 実務で困っている箇所が明確なら、該当章だけ先に読んでも問題ありません
• 実装前の最小タイムライン（例: 1〜2週間の初期立ち上げ）は 00. この本の使い方 を参照します
• 共通題材（ランニング例）として「小規模タスク管理（期限/権限/通知）」を全章で用います
• 本書で「何をどの粒度で守るか」を整理した後、AI を使ったテスト観点の具体化やレビュー手順まで広げたい場合は、関連教材 AIテスト戦略入門 を併読すると接続しやすくなります

最初の 1 クリック

• 実装前に全体像と進め方を掴みたい場合は、00. この本の使い方 から読み始めてください。
• すぐに実務へ適用したい場合は、Appendix A: チェックリスト、Appendix B: テンプレ集、Appendix D: 記入例 を先に参照すると使いどころが掴みやすくなります。
• 用語で止まりやすい場合は、Appendix E: 用語集 と Appendix C: 参考文献・リンク を手元に置いて読み進めてください。

学習成果

• 要求を合意済みの要件・仕様に分解し、設計入力として扱える成果物（要件/仕様/意思決定ログ）を作成できるようになる。
• 結合を「統合強度×距離×変動性（S/D/V）」の観点で評価し、モジュール境界と依存関係の設計判断を説明できるようになる。
• 小〜中規模 Web アプリに適したテスト方針（単体/統合/E2E の配分）を、複雑さと変更頻度に応じて設計・見直しできるようになる。

前提知識

• TypeScript と Web の基本（HTTP/REST の概要、フロントエンド開発の流れ）
• Git の基礎（差分確認、ブランチ/PR の概念）
• （推奨）チーム開発の基本プロセス（要求整理〜要件定義〜設計〜テストの流れ）

所要時間

• 通読: 約2〜2.5時間（本文量ベース概算。コードブロック除外、400〜600文字/分換算）
• テンプレートを用いて自プロジェクトに適用する場合は、対象範囲と反復回数により変動します。

ライセンス

本書は CC BY-NC-SA 4.0 で公開されています。商用利用は別途契約が必要です。

詳細なライセンス条件

利用と更新情報

• 更新・フィードバック
  • リポジトリ: itdojp/small-webapp-software-design-book
  • 更新差分を追う場合は、GitHub の コミット履歴 と PR 一覧 を参照してください。
  • 誤記報告や改善提案は GitHub Issues / PR を利用してください。
  • 併せて README と CONTRIBUTING を確認すると、ローカル確認手順と改善提案の出し方を把握できます。
• 安全に使うための注意
  • 本書の設計例は TypeScript を前提にした小〜中規模 Web アプリ向けの判断材料です。採用するフレームワーク、認証方式、外部サービスの仕様差分は実案件側で確認してください。
  • 参照資料の扱い、転載禁止、機密情報や個人情報の混入防止は POLICY.md の方針に従ってください。
  • 要件やテスト観点の整理を別教材と接続したい場合は、Issue駆動仕事術 と AIテスト戦略入門 を併読すると流れを追いやすくなります。

目次

本編

• 00. この本の使い方
• 01. 要件定義を設計入力にする
• 02. 複雑性の捉え方
• 03. 結合の物差し（統合強度×距離×変動性）
• 04. 小規模TS向けの最小アーキテクチャ
• 05. 設計時にテストを織り込む
• 06. テスト戦略（単体/統合/E2E）
• 07. 進化条件（ADRと境界の強化タイミング）

Appendix

• Appendix A: チェックリスト
• Appendix B: テンプレ集
• Appendix D: 記入例（ランニング例の完成形）
• Appendix E: 用語集
• Appendix C: 参考文献・リンク

補足: 一覧ページとして 目次 も用意しています。