「人間向けの設計書」と「AI向けの設計書」は違う。
Claude Codeを使い込む中で、AIに効く設計書の書き方が見えてきた。
人間向け vs AI向け
人間向け設計書
- 背景・目的を重視
- 図やダイアグラムが多い
- 「なぜ」の説明が厚い
AI向け設計書
- 制約・禁止事項を明確に
- コード例が多い
- 「何をしてはいけないか」が厚い
最初の一言が重要
Claude Codeに渡す最初のプロンプトで、プロジェクトの性格が決まる。
悪い例:
ブログシステムを作って
良い例:
以下の制約でブログシステムを実装してください：
技術スタック:
- フロントエンド: React + TanStack Router + TanStack Query
- バックエンド: Go + Chi router
- DB: PostgreSQL
制約:
- Server Componentsは使わない
- CSSフレームワークはTailwind CSSのみ
- 状態管理ライブラリは追加しない（TanStack Queryで完結）
ディレクトリ構成:
src/
components/ # 再利用可能なUIコンポーネント
routes/ # ページコンポーネント
lib/ # ユーティリティ、API クライアント
実装指示書のテンプレート
# 機能名: 記事一覧API
## 目的
記事の一覧を取得するAPIエンドポイントを実装する
## エンドポイント仕様
- Method: GET
- Path: /api/articles
- Query Parameters:
- page: number (default: 1)
- limit: number (default: 20, max: 100)
## レスポンス形式
{
"articles": [...],
"total": 100,
"page": 1,
"limit": 20
}
## 禁止事項
- ORMは使わない（sqlcで生成したコードを使う）
- 認証チェックはこのフェーズでは不要
- キャッシュ実装は次フェーズ
## 参考実装
既存の /api/users エンドポイント（src/handlers/users.go）を参考にすること
フェーズ分けのコツ
AIは「全部一気に」が苦手。フェーズを明確に分ける。
## Phase 1: データモデル
- articlesテーブルのマイグレーション
- sqlcでのクエリ定義
## Phase 2: APIエンドポイント
- ハンドラー実装
- バリデーション
## Phase 3: フロントエンド
- 一覧ページUI
- TanStack Query連携
各フェーズ完了時に確認を求めること。
次フェーズの先取り実装は禁止。
Reasonの明文化
「なぜそうするのか」を書いておくと、AIが一貫性のある判断をしやすい。
## 設計判断とその理由
### なぜORMを使わないか
- パフォーマンスの予測可能性を重視
- sqlcで型安全性は担保できる
- 複雑なクエリを書く予定がある
### なぜServer Componentsを避けるか
- チームにNext.js経験者が少ない
- デバッグの複雑さを避けたい
- 将来的にViteへの移行を検討している
禁止事項リストの効果
「やること」より「やらないこと」を書いた方が効く。
## やらないこと（重要）
- [ ] console.logでのデバッグ出力
- [ ] any型の使用
- [ ] 新規ライブラリの追加（事前相談なしに）
- [ ] 既存のAPIレスポンス形式の変更
- [ ] テストなしのマージ
おわり
AI駆動開発の設計書は「AIへの契約書」。曖昧さを排除し、境界を明確にすることで、期待通りの出力が得られる。
人間向けの設計書より「つまらない」文書になるが、それが効く。