仕様からコードへのAI活用

ストーリー

「実際の開発って、"仕様"から始まるよな」

中島先輩がJiraのチケットを見せた。

「このチケットの要件をAIに伝えて、コードに落とし込む。 仕様→設計→実装の流れをAIと一緒にやる方法を教えよう」

「仕様をそのままAIに投げればいいんですか？」

「そのままだと曖昧すぎる場合が多い。 仕様を構造化してからAIに伝えるのがコツだ」

仕様→コードの変換プロセス

全体フロー

[1. 仕様を整理]
  → 曖昧な部分を明確にする
    ↓
[2. 設計をAIと議論]
  → データモデル、API設計、処理フローを決める
    ↓
[3. 段階的に実装]
  → 型定義→ロジック→API→テストの順で
    ↓
[4. レビュー・修正]
  → AIにレビューさせ、改善する

Step 1: 仕様の構造化

仕様の曖昧さを排除する

元の仕様（よくある曖昧な仕様）:

「ユーザーがブックマークを保存・管理できる機能を追加する」

構造化した仕様:

機能: ブックマーク管理

ユーザーストーリー:
  - ユーザーとして、記事をブックマークに追加したい
  - ユーザーとして、ブックマーク一覧を確認したい
  - ユーザーとして、ブックマークを削除したい
  - ユーザーとして、ブックマークにタグを付けて整理したい

データモデル:
  - Bookmark: id, userId, articleId, tags[], createdAt
  - ユーザーとの関係: 1対多

API要件:
  - POST /api/bookmarks (追加)
  - GET /api/bookmarks (一覧、タグでフィルタ可)
  - DELETE /api/bookmarks/:id (削除)
  - PUT /api/bookmarks/:id/tags (タグ更新)

制約:
  - 同じ記事の重複ブックマークは不可
  - 1ユーザーあたり最大500件
  - タグは1ブックマークあたり最大5個

Step 2: AIと設計を議論

プロンプト例:
以下の仕様に基づいて、データモデルとAPIの設計を提案してください。

[構造化した仕様を貼り付け]

技術スタック: TypeScript, Express, Prisma, PostgreSQL

出力してほしいもの:
1. Prismaスキーマ
2. APIエンドポイント一覧（メソッド、パス、リクエスト、レスポンス）
3. バリデーションルール
4. 考慮すべきエッジケース

AIの出力を確認するポイント:

□ データモデルは仕様を満たしているか
□ APIのRESTful設計は適切か
□ バリデーションが十分か
□ 制約条件（重複不可、上限等）が考慮されているか

Step 3: 段階的な実装

実装の順序

1. 型定義（types.ts）
   → Copilotのコメント駆動で生成

2. データアクセス層（repository.ts）
   → Prismaクエリの生成

3. ビジネスロジック（service.ts）
   → バリデーション、制約チェック

4. APIルーター（routes.ts）
   → エンドポイントの実装

5. テスト（__tests__/）
   → Copilot /tests + 手動エッジケース追加

各ステップでのAI活用

型定義:
  → Copilotのコメント駆動
  → "// ブックマークのエンティティ型" と書いてTab

データアクセス層:
  → Copilotの補完 + Copilot Chat
  → "@workspace Prismaスキーマに基づいたCRUD操作を実装して"

ビジネスロジック:
  → ChatGPT/Claude で設計を相談
  → "重複チェックと上限チェックのロジックを実装して"

APIルーター:
  → Copilotの補完が最も効果的
  → 型定義とサービス層があれば自動で推測

テスト:
  → Copilot Chat の /tests
  → エッジケースは自分で追加

実践のコツ

AIへの指示は小さく、頻繁に

悪い例:
  「ブックマーク機能を全部実装して」
  → 品質の低い大量のコードが生成される

良い例:
  1. 「Bookmarkの型定義を作って」→ 確認
  2. 「ブックマーク追加のリポジトリ関数を作って」→ 確認
  3. 「重複チェックのバリデーションを追加して」→ 確認
  4. 「POST /api/bookmarks エンドポイントを実装して」→ 確認

仕様変更への対応

仕様変更が発生した場合:

1. 変更内容をAIに伝える
   「ブックマークにメモ機能を追加したい。
    memo: string (optional, 最大500文字) フィールドを追加」

2. 影響範囲をAIに分析させる
   「この変更で影響を受けるファイルと修正内容を列挙して」

3. 段階的に修正
   型定義 → スキーマ → サービス → ルーター → テスト

まとめ

チェックリスト

• 曖昧な仕様を構造化する方法を理解した
• AIと設計を議論するプロンプトを作成できる
• 段階的な実装の進め方を理解した
• 仕様変更時のAI活用方法を理解した

次のステップへ

仕様からコードへの変換がわかったら、次はAIが生成したコードのレビュー方法を学びます。

推定読了時間: 30分