最近、話題のAI駆動開発を実践してみました。
結論から言うと、「設計の密度が、実装の品質や手戻りの少なさに直結する」ということです。
実際にAI駆動開発をどのように行ったか、1つの機能開発を例に解説します。
AI駆動開発とは
AI駆動開発とは、ソフトウェア開発のすべてのフェーズでAIを活用する開発手法です。
AIを活用することで、実装やテストといった工程にかかる時間を短縮できます。
主なAIツールとして、GitHub Copilot、Cursor、Claude Code、Codex、Devinなどが挙げられます。
GitHub Copilotは、コーディングやテストの工程ですでに広く導入されています。
しかし、AI駆動開発ではそれだけでなく、要件定義、設計、リリースといった開発の全フェーズにおいてAIと対話しながらソフトウェア開発を進めることが可能です。
2つのアプローチ：Vibe Codingと仕様駆動開発
AI駆動開発には、大きく分けて2つのアプローチがあります。
Vibe Coding：雰囲気で進めるプロトタイピング
昨年話題となった「Vibe Coding」も、AI駆動開発の一つです。
これは、厳密な仕様書なしに、AIが開発者の指示や"雰囲気"（Vibe）を汲み取ってコーディングを進める「コードファースト」のアプローチです。
簡単なプロトタイプ作成においては、迅速に開発できるため非常に効果的です。
一方で、Vibe Codeを修正するために工数がかかる点が課題としてあげられました。
そのため、要件定義や詳細な仕様が必要になる大規模アプリでは不向きでした。
仕様駆動開発（Spec Driven Development）：設計書でAIを導く
このVibe Codingと対照的なアプローチが、「仕様駆動開発（Spec Driven Development）」です。
これは、要件定義、基本・詳細設計、実装計画といった仕様書をベースに実装を進めるワークフローです。
事前に詳細な仕様書（JSON、YAML、Markdown形式など）を用意することで、AIエージェントの振る舞いを正確に制御する考え方に基づいています。
この仕様駆動開発を支援するツールとして、GitHub Spec KitやAWSがリリースしたKiroなどが存在します。
また、精度の高い仕様書を作成するためには、あらかじめプロジェクトの原則や制約を明文化した「憲章（Constitution.md）」を用意しておくことが重要です。
なぜ仕様駆動開発が有効なのか
生成AIは確率的モデルであるため、常に同じ結果を出すとは限らない「再現性の課題」を抱えています。
しかし、十分に定義された仕様書に基づいて開発することで、同じプロンプトから生成される結果のばらつきを大幅に抑制できます。
これが、冒頭で述べた「設計の密度が品質に直結する」理由です。
設計：AIの思考を導く「指示書」を作成する
当初はGitHub Spec Kitを用いて仕様書を作成することを検討していましたが、今回はより手軽なアプローチとして、Visual Studio CodeのGitHub Copilot Chat拡張機能のみで一連のプロセスを実践しました。
ステップ1：AIの指針となる『AGENT.md』の作成
まず、AIに開発の全体像を理解させるため、プロジェクトの憲章（Constitution.md）のような役割を持つAGENT.mdというマークダウンファイルを作成しました。
AGENT.mdには、以下のような開発者が持つドメイン知識を具体的に記述します。
- 開発の目的・背景: なぜこの機能が必要なのか
- ターゲットユーザー: 誰のための機能か
- 主要な機能要件: 何ができなければならないか
- 非機能要件: パフォーマンス、セキュリティなどの制約
- 期待される成果物: 具体的に何を作るのか
これらの内容は、対話型AI（今回はGitHub Copilot ChatのAgentモードにてClaude Haiku 4.5を利用）と対話しながら壁打ちし、思考を整理して言語化しました。
このAGENT.mdをGitHub Copilotに読み込ませることで、AIはプロジェクトの文脈を常に把握した状態でコード生成や提案を行うようになります。
これは、AI搭載エディタCursorがAIの振る舞いを定義するために使用する.cursor/rulesファイルと同様の役割を果たします。
ステップ2：AIによる仕様書作成とクロスレビュー
次に、ステップ1で作成したAGENT.mdを基に、より具体的な「設計書（SPEC.md）」と「実装計画書（IMPLEMENT_PLAN.md）」を作成します。
1. AIによる草案作成
AGENT.mdをコンテキストとして読み込ませた上で、以下のプロンプトを実行して草案を作成させました。
（同じくAgentモードのClaude Haiku 4.5を選択しました。）
添付のmdファイルに定義されている仕様をもとに○○機能の設計と実装計画を作成したい。
○○機能は現在/scripts/hogehoge.pyのスクリプト、/src/hoge.pyのコンポーネントをもとに実装されている。
○○機能を改修し、○○検出や○○出力を可能にしたい。
これらをもとにSPEC.mdを作成しなさい。
2. 開発者によるレビューと情報追加
AIが生成したSPEC.mdとIMPLEMENT_PLAN.mdに目を通し、人間でなければ判断できない情報（具体的なファイルパスや既存のファイル構成など）を追記・修正します。
3. AIによるクロスレビュー
ここからが今回の試みの特徴的な部分です。
設計の質をさらに高めるため、AIにAIの成果物をレビューさせます。
AgentモードにてAIモデルをGemini 3 Flash(Preview)に切り替え、Claude Haiku 4.5が作成・修正した仕様書を読み込ませて、客観的な視点からレビューを依頼しました。
異なる特性を持つAIの視点を取り入れることで、設計の抜け漏れや改善点を多角的に洗い出すことが目的です。
Hey Gemini！Claudeが作成した添付の設計書が○○機能を実装する上でコードベースと照合して不足点がないかレビューして。
結果として、下記が得られました。
Geminiが回答します。
総評
Claudeの成果物は「設計コンセプト」は100点です。しかし「生産現場にそのまま投下して自動で出来上がる」という意味での100％ではありません。
Geminiからのアドバイス
実装開始前に以下の3点をClaude（または私）に追加で定義させると完成度は100％になります。
- ○○の具体的なアルゴリズム
- ○○のパフォーマンス制約
- ○○の追加
4. 最終的な仕様書の完成
Gemini 3 Flash(Preview)によるレビュー結果を基に、再度Claude Haiku 4.5に最終的な修正を指示します。
そして作成されたSPEC.mdは下記で構成されたものでした。
- ○○機能 仕様書
- サマリー
- 本仕様書の定義内容について
- 対象範囲
- ○○実装仕様
- △△詳細定義
- □□スキーマ定義
- ◇◇パフォーマンス仕様・チェックリスト
-
- システム概要・GOAL・入出力関係
- 0.1 GOAL（達成目標）
- 0.2 データフロー全体図
- 0.3 入出力データの関係性
- 0.4 依存ライブラリ一覧
- 0.5 注意点、既存システムへの影響範囲
-
- ○○機能詳細
- 1.1 概要
- 1.2 目的
- 1.3 入力仕様
-
- 閾値・パラメータの定義
- 2.1 ○○閾値
- 2.2 ○○定数一覧
-
- 技術選択の根拠と期待効果の数値化
- 3.1 根拠、技術的正当性
- 3.2 効果の期待値
- 3.3 パイプライン全体の効果
- 3.4 設計の実現可能性検証
-
- エラーハンドリング・例外処理
- 4.1 エラーケース定義
- 4.2 エラーハンドリング実装例
-
- パフォーマンス仕様
- 5.1 処理時間目標
- 5.2 メモリ使用量予測
- 5.3 GPU最適化
-
- テスト・検証戦略
- 6.1 ユニットテスト仕様
- 6.2 結合テスト仕様
-
- 設定ファイルテンプレート
- 7.1 YAML設定ファイル
-
- 出力メタデータスキーマ
- 8.1 出力ディレクトリ構造
- 8.2 パス変換ルール
- 8.3 output.json スキーマ
-
- 既存output.jsonとの共存戦略
- 9.1 互換性保証
- 9.2 移行計画
-
- 実装チェックリスト
-
- 参考資料
このSPEC.mdを添付して実装計画書を作成します。
この仕様書内で定義されている実装をもとに計画書をIMPLEMENT_PLAN.mdとして保存しなさい。実装・テストにかかる所要日数を見積もり、実装計画内に含めなさい。
詳細なコードとともに作成された実装計画の一部が下記です。
| フェーズ | 所要日数 | 内容 |
|---|---|---|
| 1.○○機能設計 | 3日 | aaa設計1日bbb設計1.5日ccc設計0.5日 |
| 2.○○機能実装 | 5日 | AAAクラス実装2日BBBクラス実装2日デバッグ1日 |
| 3.パイプライン結合・チューニング | 3日 | パイプライン結合1日性能チューニング1日互換性テスト1日 |
| 4.テスト・ドキュメント作成 | 3日 | 自動テストスイート1.5日運用ドキュメント作成1日ドキュメントレビュー0.5日 |
| 合計 | 11日 | 全体スケジュール |
作成された実装計画に所要日数も記載され作業見積、期日の策定までしていただけました。
（事前に作業見積を実施していたためすり合わせた期日を設定しました。）
これにより、複数のAIと人間の知見が組み合わさった、より精度の高い仕様書と実装計画書を完成させることができました。
実装：詳細な設計書がAIの”よしな力”を最大化する
設計が完了したら、いよいよ実装です。
作成したSPEC.mdとIMPLEMENT_PLAN.mdをGitHub Copilotのコンテキストに追加し、機能の実装を指示します。
この実装フェーズにおいて、Vibe Codingと仕様駆動開発の差が最も顕著に現れます。
その違いとは、AIが発揮する「”よしな”の質」です。
方針なき「Vibe Coding」の”よしな”
Vibe Codingのように詳細な設計書がない場合、AIは開発者からの曖昧な指示に対し、自らの判断で”よしなに”ファイルを生成します。
一見すると便利ですが、その生成ルールが開発者の意図と異なっていた場合、「そうじゃない、こうしてほしい」という修正指示のラリーが何度も発生し、かえって工数がかかってしまうケースがありました。
設計書に基づく「仕様駆動開発」の”よしな”
一方、仕様駆動開発では、SPEC.mdに以下のような詳細なルールをあらかじめ記載しておきます。
- ファイル分割の方針: モジュールごとにどうファイルを分割するか
- 命名規則: ファイル名や関数名、変数のルール
- 各ファイルの責務: それぞれのファイルがどんな役割を持つか
これにより、AIは「守るべきルールを完全に理解した上で」、開発者の意図通りに”よしなに”実装を進めてくれます。
結果として、手戻りが劇的に減り、実装のスピードと質が向上します。
実践Tips：大規模実装を成功させる「マイルストーン分割」
とはいえ、AIも万能ではありません。
特に「細部まで作り込まれたSPEC.mdを一度にすべて理解し、完璧に実装しきること」は、現状のAIにとってはまだ難しいタスクです。
一度の指示で実装させようとすると、設計や実装の漏れが発生することがありました。
この課題は、実装タスクをマイルストーンに分割することで解決できると、実践を通して体感しました。
IMPLEMENT_PLAN.mdで定義した計画に基づき、「まずこの部分のAPIを実装して」「次にこのUIコンポーネントを作成して」というように、機能を分割して段階的に実装を指示します。
このアプローチにより、AIは一度に処理する情報量を抑えられ、各ステップで高品質なコードを生成できます。
結果として、実装全体の抜け漏れを防ぎ、安定した開発を実現することができました。
テスト：AIによる自動化の現在地と今後の課題
最後に、AIによるテスト自動化の試みについて解説します。
テスト方針書『TEST.md』の作成
まず、実装フェーズと同様に、AIへの指示書となるTEST.mdを作成します。
このファイルには、以下のようなテスト全体の指針を記述しました。
- テスト対象: どのソースコード、どの機能をテストするのか
- テストの観点: 正常系、異常系、境界値など、どのような観点でテストケースを設計するか
- 使用するテストフレームワーク: Jest, Pytestなど
- 期待するカバレッジ: 目標とするコード網羅率
実際のTEST.mdは下記です。
# テスト戦略と実装ガイド
このドキュメントは○○プロジェクトにおける単体テスト設計、実装、テスト実行の統一基準を定めています。
AI Agentと開発者が自律的にテストを設計・実装するための詳細な規約です。
---
## 目次
- [このドキュメント読み込み時の実行タスク](#このドキュメント読み込み時の実行タスク)
- [テストの目的と概要](#テストの目的と概要)
- [コード規約](#コード規約)
- [成果物の格納先と管理](#成果物の格納先と管理)
- [テストケース粒度の定義](#テストケース粒度の定義)
- [Mock戦略と必須テスト事項](#Mock戦略と必須テスト事項)
---
## このドキュメント読み込み時の実行タスク
このドキュメントを参照して開発を開始する際は、以下の３つのタスクを自動的に実行してください。
### タスク 1: ソースコードから単体テストコードの設計
**実装手順**:
```bash
# 1. テスト対象モジュール一覧を作成
cd /home/project
# 2. src/ 配下の全モジュールをスキャン find src/ -name "*.py" -type f | head -20
# 3. 各モジュール内のpublic関数/クラスを抽出 grep -r "^def |^class " src/ | grep -v "__" | head -30 ```
**出力成果物**:
- テスト設計ドキュメント（テストケース一覧）
- `tests/unit/` 配下の `test_*.py` ファイル（スケルトン）
- `tests/integration/` 配下の結合テストスケルトン
---
### タスク 2: Pytest によるテストコードの作成
**実装手順**:
```bash
# 1. テスト対象モジュール一覧を作成
cd /home/project
# 2. src/ 配下の全モジュールをスキャン find src/ -name "*.py" -type f | head -20
# 3. 各モジュール内のpublic関数/クラスを抽出 grep -r "^def |^class " src/ | grep -v "__" | head -30 ```
**出力成果物**:
- テスト設計ドキュメント（テストケース一覧）
- `tests/unit/` 配下の `test_*.py` ファイル（スケルトン）
- `tests/integration/` 配下の結合テストスケルトン
---
### タスク 3: Pytest によるテストコードの実行
**実装手順**:
```bash
# 1. テスト環境確認
python --version
pytest --version
# 2. 全テスト実行 cd /home/project pytest tests/ -v ```
**実行時チェックリスト**:
- [ ] すべてのテストがPASS（失敗0件）
- [ ] エラーメッセージが具体的かつ再現可能か
**出力成果物**:
- `tests/test_execuition.log` - テスト実行ログ
---
### タスク 4: Pytest によるカバレッジ計測
**実行内容**:
カバレッジを計測し。未テスト箇所を特定・改善
**実装手順**:
``` bash
# 1. カバレッジ計測
pytest tests/ --cov=src --cov-report=html:tests/cov_report -v
# 2. 未テスト行を確認
grep -r "no cover" tests/cov_report/status.json || echo "All lines covered"
```
**カバレッジ目標**:
| レベル | カバレッジ | 達成時期 | 説明 |
|--------|------------|----------|------|
| **Target** | 80% | マージ前 | 基本的な機能パス |
| **Excellence** | 100% | リリース前 | すべてのコード行 |
**出力成果物**:
- `tests/cov_report/index.html` - カバレッジレポート
---
## テストの目的と概要
```
品質保証 + 設計確認 + リグレッション防止
```
単なるバグ検出ではなく以下を目指します。
- **設計の正確性確認**: 仕様書とコード実装の一致検証
- **パフォーマンス保証**: レスポンスタイム、メモリ使用量の基準達成
- **リグレッション防止**: 既存機能への悪影響を検知
- **技術負債削減**: テスト実装によるコード品質向上
- **ドキュメントの代わり**: テストがコードの使用例になる
### テスト成功の定義
```markdown
✅ テストが成功した状態:
-
**全テストPASS**
- 単体テスト: 100% PASS
- 結合テスト: 100% PASS
- エラーメッセージなし -
**カバレッジ基準** - ラインカバレッジ: >= 80%（目標 100％）
- ブランチカバレッジ: >= 75%
- 除外行: 外部API、初期化コードのみ
```
---
## コード規約
### コード品質規約
#### Python スタイル（テストコード）
```python
# ✅ 推奨: 詳細なテスト関数名
def test_text_mining_input_correctly():
"""テスト関数名は「何をテストするか」を明示"""
pass
# ✖ 非推奨: 曖昧なテスト関数名
def test_mining():
"""何をテストしているか不明"""
pass
```
## 成果物の格納先と管理
### ディレクトリ構造（テスト関連）
```
public/
├─ tests/
│ ├─ __init__.py
│ ├─ conftest.py
│ ├─ pytest.ini
│ ├─ test_execution.log
│ └─ .coverage
├─ cov_report/
│ ├─ index.html
│ ├─ coverage.xml
│ └─ status.json
├─ unit/
│ ├─ __init__.py
│ ├─ test_hogehoge.py
│ ├─ test_hghg.py
│ └─ ...
└─ integration/
├─ __init__.py
├─ test_hogehogehoge.py
└─ ...
```
## テストケース粒度の定義
### 正常系テストケース
正常系テストは、 **期待どおりの入力に対して期待どおりの出力を返すこと** を確認します。
#### 粒度レベル 1: 単一入力、単一出力
```python
def test_text_mining_correctly():
"""テキストマイニングを実施し正常な値が返される"""
text = "text"
result = text_mining.mining(text)
assert result is not None
assert len(result) == 4
assert isinstance(result, float)
```
**チェックリスト**:
- [ ] 入力値: １つの具体的な値
- [ ] 出力値; 期待値と一致するか確認
- [ ] データ型: 出力の型が正しいか確認
#### 粒度レベル 2: エッジケース（境界値）
```
詳細を記載
```
---
### 異常系テストケース
異常系テストは、 **不正な入力または異常な状態に対してシステムが適切に対応すること** を確認します。
#### 粒度レベル 1: 入力値エラー
```python
@pytest.mark.parametrize("invalid_input", [
None,
"",
[],
{},
])
def test_text_mining_correctly(invalid_input):
"""無効な入力→適切な例外を発生"""
with pytest.raises((ValueError, TypeError)) as exc_info:
text_mining.mining(invalid_input)
assert "Empty" in str(exc_info) or "invalid" in str(exc_info.value).lower()
```
**チェックリスト**:
- [ ] None、空値、型不正入力
- [ ] 予期された例外が発生するか
- [ ] 例外メッセージが具体的か
#### 粒度レベル 2: リソースエラー
```
詳細を記載
```
---
## Mock戦略と必須テスト事項
### Mock の使用基準
```
本物を使う > 部分Mock > 完全Mock
高コスト バランス 高速/分離
```
#### Mockを使うべき場合
```
詳細を記載
```
#### Mockを避けるべき場合
```
詳細を記載
```
このTEST.mdをAIに読み込ませ、既存のソースコードに対する単体テストの「設計」「テストコード作成」「テスト実行」までを自動で行わせることを目指しました。
理想と現実：AI自動テストで直面した課題
しかし、この試みは理想通りには進みませんでした。
「自動テスト」とはいうものの、現状のAIにはいくつかの壁があると感じています。
課題1：テストケースの抜け漏れ
人間がレビューすれば気づけるような、基本的なテストケースの抽出漏れや、テストコードの実装漏れが依然として発生します。
課題2：一度の指示では完遂できない
そして最も大きな課題は、実装フェーズで直面した問題と同様でした。
「この仕様書を基に、テストを設計・作成・実行せよ」という包括的な指示を一度に出すだけでは、要件を完全に満たす品質のテストを一度で完了させることは困難でした。
今後の展望：コンテキスト理解能力の進化に期待
これらの課題から、現状のAIでテスト自動化の品質を高めるには、実装と同様に「テスト設計」「テストコード生成」「テスト実行と評価」といったように、タスクを細かく分割して段階的に指示するアプローチが有効だと考えられます。
とはいえ、これらのプロセスを人間が管理し続けるのは、本質的な自動化とは言えません。
開発の文脈（コンテキスト）の細部までを一度で深く、正確に理解し、自律的に高品質なテストを完遂してくれるAIモデルの登場を、心から待ち望んでいます。
まとめ
今回、GitHub Copilotを用いて、設計から実装、テストまでの一連のAI駆動開発プロセスを実践しました。
その結果、AIは単なる「自動化ツール」ではなく、開発者の思考を加速させる「優秀な相棒」であり、その能力を最大限に引き出すには「人間による適切なガイド」が不可欠である、という結論に至りました。
知見1：部分的な"手動実行"が、全体のコストを下げる
AIにすべてを丸投げするのではなく、設計のレビューやAIへの指示出しといった要所で人間が的確に介入する方が、結果としてAIが生成したコードを手直しするコストを大きく削減でき、成果物の品質も向上しました。
知見2："Vibe Coding"と"仕様駆動開発"のハイブリッドが現実解
厳格な仕様駆動開発は強力ですが、導入のハードルが高いと感じるかもしれません。
しかし、今回の実践で、完全なVibe Codingで進める場合でも、AGENT.mdのような簡単なプロジェクト憲章（ルールブック）を一つ用意しておくだけで、AIとの対話コストとコードの修正量が劇的に減少することを体感できました。
これは、いわば「ライトな仕様駆動開発」とも呼べるアプローチです。
最後に：AIと共に、開発を次のステージへ
AIとの協業は、単なる作業の効率化に留まりません。
それは、私たち開発者が、より本質的で創造的な「設計」や「アーキテクチャの検討」に集中することを可能にする、新しい開発スタイルへの転換を意味するのだと思います。
皆さんもぜひ、まずはご自身のプロジェクトの「ミニ憲章」づくりから、AIという頼もしい相棒と共に、開発プロセスの効率化と品質向上を目指してみてはいかがでしょうか。
