AI駆動開発(設計・実装・テスト)を​実践して​見えた、​設計の​密度が​品質を​左右する​話

最近、話題の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を選択しました。）

2. 開発者に​よる​レビューと​情報追加

AIが生成したSPEC.mdとIMPLEMENT_PLAN.mdに目を通し、人間でなければ判断できない情報（具体的なファイルパスや既存のファイル構成など）を追記・修正します。

3. AIに​よる​クロスレビュー

ここからが今回の試みの特徴的な部分です。
設計の質をさらに高めるため、AIにAIの成果物をレビューさせます。

AgentモードにてAIモデルをGemini 3 Flash(Preview)に切り替え、Claude Haiku 4.5が作成・修正した仕様書を読み込ませて、客観的な視点からレビューを依頼しました。
異なる特性を持つAIの視点を取り入れることで、設計の抜け漏れや改善点を多角的に洗い出すことが目的です。

結果として、下記が得られました。

4. ​最終的な​仕様書の​完成

Gemini 3 Flash(Preview)によるレビュー結果を基に、再度Claude Haiku 4.5に最終的な修正を指示します。
そして作成されたSPEC.mdは下記で構成されたものでした。

- ○○機能 仕様書
- サマリー
 - 本仕様書の定義内容について
 - 対象範囲
   - ○○実装仕様
   - △△詳細定義
   - □□スキーマ定義
   - ◇◇パフォーマンス仕様・チェックリスト

- 0. システム概要・GOAL・入出力関係
 - 0.1 GOAL（達成目標）
 - 0.2 データフロー全体図
 - 0.3 入出力データの関係性
 - 0.4 依存ライブラリ一覧
 - 0.5 注意点、既存システムへの影響範囲
- 1. ○○機能詳細
 - 1.1 概要
 - 1.2 目的
 - 1.3 入力仕様
- 2. 閾値・パラメータの定義
 - 2.1 ○○閾値
 - 2.2 ○○定数一覧
- 3. 技術選択の根拠と期待効果の数値化
 - 3.1 根拠、技術的正当性
 - 3.2 効果の期待値
 - 3.3 パイプライン全体の効果
 - 3.4 設計の実現可能性検証
- 4. エラーハンドリング・例外処理
 - 4.1 エラーケース定義
 - 4.2 エラーハンドリング実装例
- 5. パフォーマンス仕様
 - 5.1 処理時間目標
 - 5.2 メモリ使用量予測
 - 5.3 GPU最適化
- 6. テスト・検証戦略
 - 6.1 ユニットテスト仕様
 - 6.2 結合テスト仕様
- 7. 設定ファイルテンプレート
 - 7.1 YAML設定ファイル
- 8. 出力メタデータスキーマ
 - 8.1 出力ディレクトリ構造
 - 8.2 パス変換ルール
 - 8.3 output.json スキーマ
- 9. 既存output.jsonとの共存戦略
 - 9.1 互換性保証
 - 9.2 移行計画
- 10. 実装チェックリスト
- 11. 参考資料

このSPEC.mdを添付して実装計画書を作成します。

詳細なコードとともに作成された実装計画の一部が下記です。

作成された実装計画に所要日数も記載され作業見積、期日の策定までしていただけました。
（事前に作業見積を実施していたためすり合わせた期日を設定しました。）

これにより、複数の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と開発者が自律的にテストを設計・実装するための詳細な規約です。

---

## 目次

1.  [このドキュメント読み込み時の実行タスク](#このドキュメント読み込み時の実行タスク)
2.  [テストの目的と概要](#テストの目的と概要)
3.  [コード規約](#コード規約)
4.  [成果物の格納先と管理](#成果物の格納先と管理)
5.  [テストケース粒度の定義](#テストケース粒度の定義)
6.  [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` - カバレッジレポート

---

## テストの目的と概要

``  
品質保証 + 設計確認 + リグレッション防止
``

単なるバグ検出ではなく以下を目指します。

1.  **設計の正確性確認**: 仕様書とコード実装の一致検証
2.  **パフォーマンス保証**: レスポンスタイム、メモリ使用量の基準達成
3.  **リグレッション防止**: 既存機能への悪影響を検知
4.  **技術負債削減**: テスト実装によるコード品質向上
5.  **ドキュメントの代わり**: テストがコードの使用例になる

### テスト成功の定義

``markdown  
✅ テストが成功した状態:

1. **全テストPASS**  
   - 単体テスト: 100% PASS  
   - 結合テスト: 100% PASS  
   - エラーメッセージなし  

2. **カバレッジ基準**
   - ラインカバレッジ: >= 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という頼もしい相棒と共に、開発プロセスの効率化と品質向上を目指してみてはいかがでしょうか。