AI駆動開発で必要な設計書
AI駆動開発では、人が読むためだけの設計書ではなく、AIが理解しやすい設計書を作ることが重要です。
従来の設計書は「人間同士の情報共有」が目的でしたが、Claude CodeやChatGPTなどを活用する場合は「AIへ正確な指示を与えること」が目的になります。
設計書は次のような構成にすると、AIの精度が大幅に向上します。
1. プロジェクト概要
まずAIにシステム全体を理解させます。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | システム名 Relamaide 概要 求人マッチングサイト 開発言語 PHP 8.4 Framework Laravel 12 DB MySQL 8 認証 Laravel Breeze メール SendGrid クラウド ConoHa VPS |
2. ディレクトリ構成
AIはディレクトリ構造を理解すると精度が上がります。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | app ├── Http ├── Models ├── Services ├── Repositories ├── Mail └── Jobs resources ├── views ├── js └── css database ├── migrations └── seeders |
3. コーディングルール
これが最も重要です。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | Controllerは薄くする ビジネスロジックはServiceへ DBアクセスはRepositoryへ Modelにはロジックを書かない 命名規則 UserService UserRepository MailService |
AIはこのルールに従ってコードを書いてくれます。
4. DB設計
AIはテーブル設計が分かるとかなり賢くなります。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | users id name email password status created_at updated_at |
ER図があるとさらに良いです。
5. API仕様
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | POST /login Request email password Response { token user } |
6. 画面設計
画面ごとに
1 2 3 4 5 6 7 8 9 10 11 12 13 | 画面名 目的 入力項目 ボタン 遷移 バリデーション エラー表示 |
を書きます。
7. 処理フロー
例えば
1 2 3 4 5 6 7 8 9 10 11 | ユーザー登録 ↓ 入力チェック ↓ usersへ登録 ↓ メール送信 ↓ 認証URLクリック ↓ 会員登録完了 |
Mermaidを使うとAIも理解しやすくなります。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | flowchart TD A[入力] B[バリデーション] C[DB登録] D[メール送信] E[完了] A --> B B --> C C --> D D --> E |
8. 業務ルール
これが抜けるケースが非常に多いです。
1 2 3 4 5 6 7 | ・メールアドレスは重複不可 ・求人公開は管理者承認後 ・ステータス2のみメール送信 ・退会ユーザーはログイン不可 |
AIはこのルールをかなり忠実に守ります。
9. 開発ルール
例えば
1 2 3 4 5 6 7 8 9 10 11 | 必ずFeature Testを書く N+1を発生させない ValidationはFormRequest Repository経由でDBアクセス SQLは書かない Paginationを使う |
Claude Codeはこのルールをかなり守ります。
Markdownで管理するのがおすすめ
最近はWordやExcelよりもMarkdownが主流です。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | docs/ README.md architecture.md database.md api.md screen.md rules.md coding-rule.md prompt.md |
Claude Codeはdocsフォルダを参照できるため、設計書をMarkdownで管理すると、その内容を踏まえてコード生成や修正を行えます。
Claude Codeでは「CLAUDE.md」が効果的
Claude Codeを利用する場合は、プロジェクトのルートにCLAUDE.mdを配置する方法が非常に有効です。
1 2 3 4 5 6 | / ├── app/ ├── database/ ├── resources/ ├── docs/ └── CLAUDE.md |
CLAUDE.mdには以下のような内容を記載します。
- プロジェクト概要
- コーディング規約
- アーキテクチャ
- 命名規則
- 使用ライブラリ
- テスト方針
- 実装時の禁止事項
- レビュー基準
AIは開発のたびにこの内容を参照し、一貫したルールで実装できるようになります。
おすすめの設計書構成
AI駆動開発では、以下のような構成にすると運用しやすくなります。
1 2 3 4 5 6 7 8 9 10 11 12 | docs/ ├── 01_プロジェクト概要.md ├── 02_システム構成.md ├── 03_アーキテクチャ.md ├── 04_データベース設計.md ├── 05_API設計.md ├── 06_画面設計.md ├── 07_業務フロー.md ├── 08_業務ルール.md ├── 09_コーディング規約.md ├── 10_テスト方針.md └── 11_プロンプトガイド.md |
このような構成にしておけば、Claude Codeや他のAIコーディングツールがプロジェクトの背景やルールを理解しやすくなり、生成されるコードの品質や一貫性が向上します。設計書は「人のための資料」だけでなく、「AIが迷わず実装できるための知識ベース」として整備することが、AI駆動開発を成功させるポイントです。