AIが迷わず実装できる設計書の書き方 — 20セクション・3,500行の構成を公開
設計書の目次を公開する
「設計書を書け、と言われても、何をどこまで書けばいいかが一番むずかしいんですよね」
これは、私が後輩から実際に言われた一言です。たしかに、その通りだなと思いました。設計書の重要性は語られていても、テンプレートとして使える「目次の例」を見る機会はあまりありません。
前回の記事 では、設計書の完成度が開発速度を決めるという話を書きました。今回はその続編として、私自身が AI 駆動開発で 16 人日を 2 時間に短縮したときに使った設計書の構成 を、目次そのまま公開してみます。
「全部書け」とは言いません。最初の 7 セクション から手をつけてもらえれば、効果は十分に体感できると思います。
20 セクションの全体像
まずは目次の全景から。
| # | セクション | 重要度 | 役割 |
|---|---|---|---|
| 1 | 文書概要 | ★☆☆ | 目的・対象読者・関連文書 |
| 2 | 技術スタック | ★★★ | 何を使うか（選定理由付き） |
| 3 | アーキテクチャ概要 | ★★★ | システム構成図・レイヤー構成 |
| 4 | データモデル | ★★★ | ER 図・テーブル間の関係 |
| 5 | テーブル定義書 | ★★★ | カラム名・型・制約・初期値 |
| 6 | 状態遷移設計 | ★★☆ | ステータスの遷移ルール |
| 7 | API 設計 | ★★★ | エンドポイント・リクエスト/レスポンス型 |
| 8 | 権限制御設計 | ★★★ | ロール × リソース × 操作のマトリクス |
| 9 | セキュリティ設計 | ★★☆ | 認証・CSRF・入力検証 |
| 10 | インフラ構成 | ★★☆ | Docker・環境変数 |
| 11 | 画面遷移設計 | ★★★ | どの画面からどの画面へ |
| 12 | テスト戦略 | ★★☆ | テストの種類と範囲 |
| 13 | 初期データ設計 | ★☆☆ | シードデータ |
| 14 | マイグレーション戦略 | ★☆☆ | DB 変更の管理方法 |
| 15 | インデックス戦略 | ★☆☆ | クエリ最適化 |
| 16 | 全文検索設計 | ★☆☆ | 検索機能がある場合のみ |
| 17 | パフォーマンス要件 | ★☆☆ | レスポンスタイムの目標 |
| 18 | 通知設計 | ★☆☆ | メール送信がある場合のみ |
| 19 | 今後の詳細化対象 | ★☆☆ | MVP 以降の検討事項 |
| 20 | 備考 | ★☆☆ | その他 |
おすすめは、まず ★★★ の 7 セクション だけを埋めることです。ここが、AI に「考えさせない」ための核になります。
各セクションの「これだけは書け」
ここからは、特に効果が大きかった ★★★ セクションについて、最低限書いてほしい中身を紹介します。
技術スタック（★★★）
ポイントは、バージョンと選定理由をセットで書く ことです。「React を使う」では弱くて、「Next.js 15.x (App Router) を使う。SSR/SSG が必要なため」まで踏み込みたいところ。
| レイヤー | 技術 | バージョン | 選定理由 |
|---|---|---|---|
| フロントエンド | Next.js (App Router) | 15.x | SSR/SSG 統合 |
| ORM | Prisma | 7.x | 型安全なクエリ |データモデル + テーブル定義書（★★★）
ここが曖昧だと、AI は本当に毎回質問してきます。カラム名・型・制約・デフォルト値 までを書き切るのがコツです。
| カラム | 型 | NULL | デフォルト | 説明 |
|---|---|---|---|---|
| id | UUID | NO | gen_random_uuid() | 主キー |
| name | VARCHAR(100) | NO | - | プロジェクト名 |
| status | ENUM | NO | 'planning' | 現在のステータス |API 設計（★★★）
エンドポイントは、パス・メソッド・認証要否・レスポンス型 を一覧化するのがおすすめです。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| GET | /api/projects | 要 | プロジェクト一覧 |
| POST | /api/projects | 要 | プロジェクト作成 |
| GET | /api/projects/:id | 要 | プロジェクト詳細 |権限制御設計（★★★）
ここを省くと、AI は「この操作は誰ができますか？」と毎回聞いてきます。私自身、これで何度時間を溶かしたか分かりません。
ロール × リソース × 操作のマトリクスを、最初に一枚作っておくのがおすすめです。
| リソース | 操作 | admin | manager | member | viewer |
|---|---|---|---|---|---|
| プロジェクト | 作成 | ✅ | ✅ | ❌ | ❌ |
| プロジェクト | 閲覧 | ✅ | ✅ | ✅ | ✅ |
| タスク | 編集 | ✅ | ✅ | ✅(自分のみ) | ❌ |画面遷移設計（★★★)
これは少し裏ワザ的ですが、ディレクトリ構造で表現する と、AI がルーティングと 1:1 で読み取ってくれて迷いません。
app/
├── (auth)/login/ # ログイン画面
├── (dashboard)/
│ ├── projects/ # プロジェクト一覧
│ └── projects/[id]/ # プロジェクト詳細
│ ├── tasks/ # タスク管理
│ └── gantt/ # ガントチャート設計書を書く順序
「20 セクション全部を頭から書こう」とすると、私の経験では、ほぼ確実に途中で挫折します。
順序を工夫すると、ぐっと書きやすくなります。
| 順序 | セクション | 理由 |
|---|---|---|
| 1 | 技術スタック | 最初に決めないと後が全部変わる |
| 2 | データモデル + テーブル定義 | データが決まれば API が決まる |
| 3 | API 設計 | データモデルから自動的に導出できる |
| 4 | 権限制御 | API の各操作に対して「誰ができるか」 |
| 5 | アーキテクチャ + 画面遷移 | 全体像を図示 |
| 6 | 残りのセクション | 必要に応じて追加 |
データから API、API から権限、と 上から下流に流していく イメージです。
さいごに
設計書を「書くのが面倒なもの」と感じる気持ちは、私も今でも変わりません。書くだけでは何も動かないし、すぐに成果が見える作業でもないからです。
それでも、設計書は 過去の判断を蓄積する装置 だと私は捉え直しています。書いた瞬間、開発者（人間でも AI でも）が同じ判断を繰り返さなくて済むようになる。これは、地味だけど確実な投資です。
もしまだ設計書を書く習慣がないようでしたら、いきなり全部ではなく ★★★ の 7 セクションだけ で構いません。それだけでも、AI 駆動開発の速度は、自分でも驚くくらい変わってきます。
あなたのプロジェクトでは、どのセクションから書き始めてみますか？
関連記事
- 16人日の開発が2時間で終わった — 設計書の完成度が開発速度を決める — なぜ設計書の完成度が重要なのか
- 「テスト工程が消滅した」— AI駆動開発 vs 従来開発を全工程で比較してみた — AI 駆動開発の実績データ