AI駆動開発の実践方法｜仕様作成からクラウド実装・運用までを4stepで徹底解説

「AIにコードを書かせてみたが、思ったものと違う実装になった」「動くには動くが、本番に出すのが怖い」とAI駆動開発に取り組み始めたエンジニアの多くが壁にぶつかります。原因の多くは、AIの性能ではなく、AIに渡す「仕様」と「実行条件」が曖昧なことにあります。

この記事では、AI駆動開発の定義と関連概念との違いを整理したうえで、小規模な問い合わせ管理APIを題材に、仕様作成からクラウド設計、実装、デプロイ、運用までを4つのステップで解説します。

AI駆動開発とは、開発ライフサイクルの各工程の、

• 仕様策定

• 設計

• 実装

• テスト

• デプロイ

• 運用

にAIエージェントを組み込み、人間は仕様の確定・設計判断・レビュー・承認といった意思決定に専念する開発スタイルを指します。

単に「AIにコードを書いてもらう」こととの違いは、AIが参照する仕様書や実行条件を人間が事前に整備し、AIの出力を検証・承認する仕組みを開発プロセス全体に組み込んでいる点にあります。

仕様が曖昧なままAIに実装を任せると、AIは足りない情報を推測で埋めてしまい、動作はしても意図とずれたシステムができあがります。

AI駆動開発の周辺には、似た響きの言葉がいくつも存在します。これらは互いに排他的な概念ではなく、AIの関与度合いや、仕様の明文化をどこまで重視するかという軸で整理すると理解しやすくなります。

それぞれの概要は次のとおりです。

• AI支援開発：Copilotのようなコード補完・提案ツールを使う開発スタイルです。実装の主導権は常に人間にあり、AIはあくまで「アシスタント」として提案を返すだけで、設計判断や意思決定を代行することはありません。

• Vibe Coding：生成されたコードや差分を十分に理解・レビューせず、動作結果を見ながら対話形式でAIへ修正指示を出していく進め方です。着手は速い一方、判断根拠や仕様が残りにくく、規模が大きくなるほど再現性・保守性・セキュリティ上の課題が表面化しやすくなります。なお、本記事ではこの意味でVibe Codingという用語を使用します。

• 仕様駆動開発：実装前にspec.mdなどの仕様書を確定し、AIの実装がその仕様・受け入れ条件と一致しているかを検証しながら進める手法です。「仕様と実装を一致させること」自体に焦点を当てています。

• AI駆動開発：仕様策定・設計・実装・テスト・デプロイ・運用というライフサイクル全体にAIを組み込み、仕様駆動開発の考え方を土台としながら、クラウド環境での実行・運用・仕様への反映までを含む、より広い運用モデルです。

これらを表に整理すると、以下のようになります。

仕様駆動開発はAI駆動開発を実践するための有力な方法の一つであり、完全な同義語ではありません。

仕様駆動開発は主に「仕様と実装を一致させる」ことに焦点を当てた手法であるのに対し、AI駆動開発はクラウド設計・デプロイ・運用・仕様へのフィードバックまでを含む、開発ライフサイクル全体の運用モデルを指します。

AIに仕様作成を支援させたり、実装を任せたりする前に、何を題材に進めるか、どのような技術を使うかを決めておきます。

ここで前提をそろえておくことで、以降のステップで扱う仕様書や構成図、コード例を、具体的なイメージを持ちながら読み進められるようになります。

本記事では、以下の機能を持つ小規模なWeb APIを題材として進めます。

• 問い合わせの登録
• 問い合わせ一覧の取得
• ステータスの更新
• ユーザー認証
• データベースへの保存
• 操作ログの記録
• クラウド環境へのデプロイ

一般的な業務システムの最小構成に近い機能セットのため、仕様作成からクラウド実装・運用までの流れを一通り体験するのに適しています。

• AIコーディングエージェント（Claude Codeなど、仕様ファイルを参照しながらコード生成・修正ができるもの）
• Git・GitHub
• 任意のWebフレームワーク
• Docker

本記事は、Git、Web API、Docker、クラウドの基礎知識がある読者を想定しています。特定のクラウド事業者に依存しない考え方を中心に説明します。

個人でAI開発を進めるステップと具体的なスキルに関しては、こちらの記事で消化しています。

AIに実装を任せる前に、まず「何を作るか」を仕様として言語化します。

ここで仕様の粒度が粗いままだと、後続のステップでクラウド設計やCI/CDをどれだけ丁寧に整えても、土台となる実装自体が意図とずれてしまいます。

ステップ1では、機能のスコープを定め、AIが迷わず実装できる粒度まで仕様を書き込む方法を扱います。

AIに実装させる前に、まず「今回作る機能」と「今回は作らない機能」を分けて言語化します。

問い合わせ管理APIであれば、以下のように整理します。

• 作る：問い合わせ登録、一覧取得、ステータス更新、認証、操作ログ
• 作らない：問い合わせへの返信機能、担当者への自動アサイン、外部チャットツールとの連携

「作らない機能」を明記しない場合、AIが気を利かせて関連機能まで実装してしまい、レビューすべき差分が想定以上に膨らむことがあります。

スコープの境界線を先に引いておくことが、後述する「1回の指示で1つのタスクだけを実装させる」（ステップ3）にもつながります。

AIが参照する仕様書として、spec.mdを作成します。見出し構成の例は以下のとおりです。

markdown

# プロジェクトの目的
# 想定ユーザー
# ユースケース
# 機能要件
# 非機能要件
# データ要件
# 制約条件
# 受け入れ条件
# 対象外

重要なのは、機能要件を「問い合わせを登録できる」のような一文で終わらせないことです。AIは書かれていない部分を推測で補うため、入力内容・処理・保存情報・正常時の結果・エラー時の挙動まで書き切ります。

問い合わせ登録機能であれば、次のように記述します。

markdown

## 機能要件: 問い合わせ登録

- 入力内容
  - 氏名（必須、100文字以内）
  - メールアドレス（必須、RFC準拠のメール形式）
  - 件名（必須、200文字以内）
  - 本文（必須、5000文字以内）
- 処理
  1. 入力値をバリデーションする
  2. 問い合わせIDとしてUUID v4を生成する
  3. ステータスを「未対応」で保存する
  4. 登録日時（UTC）を記録する
  5. 操作ログに「問い合わせ登録」イベントを記録する
- 保存情報
  - 問い合わせID、氏名、メールアドレス、件名、本文、ステータス、登録日時、更新日時
- 正常時の結果
  - HTTP 201とともに問い合わせIDを返す
- エラー時の挙動
  - 必須項目未入力: HTTP 400、フィールド名を含むエラーメッセージ
  - メール形式不正: HTTP 400
  - 一時的なDB接続エラー: HTTP 503と汎用エラーコードを返す。再試行可否は処理の冪等性を考慮して定義し、内部エラーの詳細はレスポンスに含めない

操作ログには、イベント名、問い合わせID、操作者ID、実行日時、処理結果を記録します。問い合わせ本文、氏名、メールアドレス、認証情報などの機密情報や個人情報は、操作ログへ記録しないことを仕様に明記します。

AIは記載されていない要件を推測して実装する可能性があるため、以下の非機能要件も事前に決めておきます。

• 認証・認可（誰がどの操作を行えるか）
• レスポンスタイム
• 同時利用数
• データの暗号化
• ログの保存期間
• バックアップ
• 障害時の復旧方法
• クラウドコストの上限

非機能要件を決めずにAIへ実装を任せると、認証チェックが甘い、通信が暗号化されていない、ログが際限なく増え続ける、といった問題が実装後に発覚しがちです。

クラウドコストは、クラウド事業者、リージョン、リクエスト数、データベース方式、ログ量、外向き通信量によって大きく変わります。

金額を一律に置くのではなく、想定トラフィックを料金計算ツールへ入力して上限を試算し、予算アラートと合わせて設定してください。

spec.mdで確定した仕様を、実際にどのクラウドサービス・構成で実現するかに落とし込みます。

コンピュート方式やデータベースの選定は後から変更しづらく、やり直しのコストも大きいため、AIに実装を始めさせる前に、構成とその判断根拠を人間が固めておくことがステップ2の目的です。

spec.md を作成したら、機能要件・非機能要件をクラウドコンポーネントへ変換します。

問い合わせ管理APIの例では、次のように対応づけられます。

この段階では実装の詳細ではなく、「どの要件をどのマネージドサービスが満たすか」という対応関係を整理することが目的です。

コンピュート方式は、アクセス量、実行時間、起動速度、運用負荷、ネットワーク要件、コストを基準に判断します。

小規模なAPIであれば、運用負荷を抑えやすいサーバーレスやマネージドコンテナから検討するのが現実的です。

問い合わせ管理APIのようにアクセス頻度が読みにくい小規模システムでは、まずサーバーレスかマネージドコンテナで構築し、アクセス傾向が見えてきた段階で必要に応じて見直す進め方が、運用負荷とコストのバランスが取りやすいでしょう。

構成図には、以下の要素を含めます。

• ユーザー
• 認証
• API
• アプリケーション
• データベース
• シークレット
• ログ
• CI/CD
• 外部サービス

サービスの配置だけでなく、データの流れ、ネットワーク境界、権限境界も記載します。

以下は構成図の例です。

コンピュート方式やデータベースの選定など、後から「なぜこの構成にしたのか」を追いにくい判断は、ADRとして残します。

markdown

# ADR-0001: コンピュート方式にマネージドコンテナを採用

## ステータス
承認済み

## コンテキスト
問い合わせ管理APIはアクセス量が不安定で、将来的にバッチ処理の追加も見込まれる。
サーバーレスはコールドスタートの影響が懸念され、VMは運用負荷が高い。

## 決定
マネージドコンテナを採用する。

## 影響
- コンテナイメージのビルド・脆弱性スキャン工程がCI/CDに必要になる
- 将来的な処理の複雑化に対してサーバーレスより柔軟に対応できる

ADRを残しておくと、AIエージェントに設計変更を依頼する際も「過去になぜこの構成にしたか」を参照させられるため、既存の設計判断を無視した提案を減らせます。

仕様とクラウド設計が固まったら、いよいよAIに実装を任せます。

ここで重要なのは、AIに丸投げするのではなく、実装前に計画を確認し、レビューできる粒度までタスクを分割してから進めることです。Step3では、AIの振る舞いを人間がコントロールしながら品質を検証するための具体的な運用ルールを扱います。

AGENTS.md や CLAUDE.md などに、AIが守るべきルールを記載します。例として以下のような項目を含めます。

markdown

# AIエージェント向けプロジェクトルール

- spec.md に記載のない仕様は実装せず、不明点は質問すること
- 本番環境（prod）のリソースは操作しない。対象は開発・検証環境のみ
- 1つの指示に対して1つのタスクのみを実装し、複数機能を同時に変更しない
- 実装前に変更計画（変更対象ファイル、方針、想定される影響範囲）を提示すること
- データベースのマイグレーションファイルは直接編集せず、新規ファイルを追加すること
- 実装後は spec.md の受け入れ条件に対応するテストを追加すること

このルールは一度作って終わりではなく、AIの誤った振る舞いに気づくたびに追記していく運用ドキュメントとして扱います。

いきなりコードを生成させるのではなく、まず変更計画を出力させ、人間がレビューしてから実装に進みます。指示の例は以下の通りです。

text

spec.md の「問い合わせ登録」機能を実装する前に、
変更予定のファイル一覧、実装方針、想定されるリスクを箇条書きで提示してください。
コードの生成はこの計画が承認されてから行ってください。

この一手間により、AIが仕様を誤読していないか、影響範囲が想定より大きくなっていないかを、コードを書かせる前に確認できます。

tasks.md などにタスクを機能単位で分割しておき、1回の指示につき1タスクのみ実装させます。

markdown

# tasks.md（抜粋）

- [ ] TASK-01: 問い合わせ登録APIの実装
- [ ] TASK-02: 問い合わせ一覧取得APIの実装
- [ ] TASK-03: ステータス更新APIの実装
- [ ] TASK-04: 操作ログ記録処理の実装

タスクを小さく保つことで、1つのプルリクエストのレビュー負荷が下がり、セキュリティ上の懸念点も見つけやすくなります。

次のStep4で扱う「小さな変更を検証環境へ流し、確認してから本番へ反映する」というCI/CDの前提にもなります。

実装が終わったコードを、どのようにクラウド環境へ安全に反映し、仕様へ戻していくかを扱います。

AIが本番環境に直接触れない体制と、コードの変更に合わせて仕様を更新し続ける仕組みこそが、継続的に回していくための土台になります。

AIが本番環境を直接操作しないように、環境を分けます。AIには開発・検証環境だけを操作させ、本番反映には人間の承認を必須とします。

具体的には、環境ごとにクラウドアカウント（またはプロジェクト）とIAMロールを分離し、AIエージェントやCI/CDに割り当てる権限は開発・検証環境のリソースに限定します。

本番環境への反映は、後述するCI/CDパイプラインの承認ステップを経由してのみ行われるようにします。

環境ごとの差異をコードで管理し、手作業によるインフラ構築を避けます。

Terraformを使う場合、認証情報やアクセス制御を環境ごとに分離する必要があるシステムでは、環境別のルートモジュール、バックエンド、stateを用意します。同じ認証境界内で同一構成を複製する用途では、ワークスペースも選択肢になります。

hcl

# environments/staging/main.tfmodule "inquiry_api" {
  source = "../../modules/inquiry_api"

  environment       = "staging"
  compute_min_count = 1
  compute_max_count = 2
  db_instance_class = "db.t3.micro"}

hcl

# environments/production/main.tfmodule "inquiry_api" {
  source = "../../modules/inquiry_api"

  environment       = "production"
  compute_min_count = 2
  compute_max_count = 10
  db_instance_class = "db.t3.small"}

以下の流れを構築します。

GitHub Actionsで表現すると、たとえば以下のような骨格になります。

yaml

name: deploy-pipeline

on:pull_request:
    branches: [main]

jobs:test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: make test

  build-and-scan:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Build container image
        run: docker build -t inquiry-api:${{ github.sha }} .
      - name: Scan image for vulnerabilities
        run: trivy image inquiry-api:${{ github.sha }}

  deploy-staging:
    needs: build-and-scan
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - name: Deploy to staging
        run: ./scripts/deploy.sh staging
      - name: Run smoke tests
        run: ./scripts/smoke_test.sh staging

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment:
      name: production  # GitHub Environments の保護ルールで承認者を必須に設定
    steps:
      - name: Deploy to production
        run: ./scripts/deploy.sh production

本番デプロイを完全自動化するのではなく、environment: production に承認ルールを設定するなどして、品質や影響範囲に応じて人間の承認工程を挟む点がポイントです。

機能追加や修正を行う際は、コードだけでなく以下も合わせて更新します。

• spec.md
• ADR
• tasks.md
• テスト
• 運用手順
• AIエージェント用ルール

たとえばプルリクエストのテンプレートに「spec.mdの更新有無」というチェック項目を入れておくと、仕様の更新漏れに気づきやすくなります。仕様と実装の乖離を防ぐことで、次の開発でもAIが正しい情報を参照できる状態を維持できます。

運用中に判明した障害対応の手順や、想定と異なったアクセスパターンも、spec.mdの非機能要件に反映していくと、仕様書自体が運用の実態を反映したドキュメントとして育っていきます。

AI駆動開発は、仕様と受け入れ条件を明文化でき、変更を小さな単位に分けて検証できるプロジェクトに向いています。

具体的には、次のようなプロジェクトで導入しやすいでしょう。

• APIや業務システムなど、入出力と受け入れ条件を定義しやすい
• 自動テストやコードレビューの体制がある
• 機能単位でタスクやプルリクエストを分割できる
• 開発・検証・本番環境を分離できる
• AIの出力を確認する担当者と承認フローがある

一方で、次のようなプロジェクトでは慎重な導入が必要です。

• 要件探索の初期段階で、作るもの自体が定まっていない
• 既存仕様やテストがなく、変更の影響範囲を確認できない
• 医療、金融、重要インフラなど高い安全性が必要で、専門家によるレビュー体制がない
• AIに広い本番権限を与えなければ開発を進められない
• 生成されたコードを人間が確認する時間を確保できない

向いていない条件に該当する場合は、いきなり開発ライフサイクル全体へAIを組み込まず、仕様整理やテストケース作成など、影響範囲の小さい工程から導入してください。

AIエージェントの開発に関しては、こちらの記事で紹介しています。

AI駆動開発がうまくいかないとき、本記事で扱う代表的な原因は、AIの実装能力そのものよりも、仕様・タスク粒度・権限・検証プロセスといった「AIの周りの設計」の不備にあります。

着手前に以下の項目をチェックしておきましょう。

• 仕様を作らずコード生成から始める

• 1回の指示でシステム全体を作らせる

• AIに過剰なクラウド権限を与える

• AIが生成したテストだけで品質を判断する

要件や制約をAIが推測するため、動作はしても目的に合わないシステムになりやすくなります。

spec.mdと受け入れ条件を確定してから実装を開始することが、遠回りに見えて最も確実な進め方です。

変更範囲が広くなり、実装内容やセキュリティ上の問題を人間が確認できなくなります。

タスクを小さく分割し、機能単位で実装・テスト・レビューを行うことで、問題の早期発見と手戻りの縮小につながります。

AIエージェントやCI/CDに管理者権限（IAMのフルアクセスなど）を与えてしまうと、意図しないリソースの削除や、本番環境への誤ったデプロイといった事故が起きたときの被害が大きくなります。

AIに割り当てる権限は、開発・検証環境の特定リソースに対する最小権限に留め、IAMポリシーやネットワーク設定の変更、本番環境へのアクセスは人間の操作に限定するべきです。

権限設計は一度決めたら終わりではなく、AIが実際にどの操作を行っているかを定期的に棚卸しし、不要な権限を削除していく運用が必要になります。

AIが書いたテストは、AI自身の実装解釈に沿って書かれるため、実装のバグとテストの誤りが噛み合ってテストが通ってしまうことがあります。テストが通ることと、spec.mdの受け入れ条件を満たしていることは別の観点です。

AIが生成したテストケースが受け入れ条件を網羅しているかを人間がレビューし、必要に応じて負荷テストやセキュリティ観点のテストを別途追加するなど、AI生成のテスト結果だけに頼らない検証体制を組んでおくことが重要です。

AI駆動開発は、AIにコードを書かせる技術ではなく、AIが誤った推測をせずに済むだけの仕様と実行条件を、開発ライフサイクル全体にわたって整備し続ける取り組みです。

本記事で解説した4つのステップを振り返ると、次のようになります。

1. spec.mdに機能要件・非機能要件を具体的に記述し、AIの推測の余地を減らす
2. 仕様をクラウドコンポーネントへ変換し、構成図とADRで設計判断を可視化する
3. プロジェクトルール・変更計画・タスク分割によって、AIの実装を人間が検証できる粒度に保つ
4. 環境分離とCI/CDの承認フローで本番反映のリスクを抑え、運用結果を仕様へ反映し続ける

まずは小さな機能単位でこのサイクルを一周させ、自社のプロジェクトルールやCI/CDパイプラインに落とし込んでいくところから始めてみてください。