【Vibe Coding実践②】設計書を書いてからAIに実装させたら品質が段違いだった
この記事のまとめ
- ドキュメント駆動型Vibe Codingで25時間・8900行のSpring Bootアプリをテスト付きで開発した
- 設計書をAIの「プロンプト」として活用することで、コード品質と一貫性が大幅に向上した
- 非プログラマの事例と比較し、Vibe Codingの向き・不向きを明らかにした
対象読者
- Vibe Codingの品質面に不安がある方
- AI駆動開発を業務で本格活用したいエンジニア・SE
- 前回記事（非プログラマ編）を読んだ方
前回のおさらい: 非プログラマのVibe Coding
前回の記事では、プログラミング未経験のSEがChatGPT + Codex CLIを使い、
業務の合間10日間で2600行超のJavaバッチツールを完成させた事例を紹介しました。
成果は確かに驚異的でした。しかし同時に、いくつかの課題も浮き彫りになりました。
- 2600行が1ファイルに集中（保守困難な構造）
- コードの意味を理解できない（「動くけど、なぜ動くか分からない」）
- テストコードなし、品質を判断する基準がない
一言でまとめると、「動くけど保守できない」 という問題です。
ではアプローチを変えれば、この問題は解消できるのか？ — 今回、私自身が別のプロジェクトで検証しました。
今回の事例: ドキュメント駆動型Vibe Coding
プロジェクト概要
今回開発したのは、外部API連携を含む業務自動化ツールです。
| 項目 | 内容 |
|---|---|
| アプリケーション種別 | バックエンドサービス（バッチ処理型） |
| 主な機能 | 外部APIの状態変化を検知し、メッセージングサービスへ通知 |
| 外部連携 | REST API（2種）、メッセージング |
| データ永続化 | RDB |
技術スタック
| カテゴリ | 技術 |
|---|---|
| 言語 | Java 21 |
| フレームワーク | Spring Boot 3.5 |
| ビルドツール | Maven |
| ORM | Spring Data JPA |
| HTTPクライアント | Spring WebClient |
| テスト | JUnit 5, Mockito, WireMock |
前回の事例（2600行のバッチツール）に比べると、外部システムとの連携があるぶん技術的な複雑さが高いプロジェクトです。
開発プロセス
今回の開発で最も重要なポイントは、実装の前に設計ドキュメントを作り込んだことです。
ChatGPTで設計し、Claude Codeで実装する — AIツールをフェーズごとに使い分けました。
- ChatGPT: 対話的なブレインストーミング、要件の構造化、設計書の作成に使用
- Claude Code: コード生成、テスト実行、ファイル操作を直接行える実装フェーズに使用
事前に整備したドキュメント
実装に入る前に、以下の4本の設計書を作成しました。
| ドキュメント | 内容 | 目的 |
|---|---|---|
| 要件定義書 | 機能要件・非機能要件の一覧 | 「何を作るか」の明文化 |
| 基本設計書 | アーキテクチャ、技術選定、レイヤー構成 | 「どう作るか」の方針決定 |
| 詳細設計書 | パッケージ構成、クラス設計、責務定義 | コードレベルの設計 |
| 処理フロー図 | Mermaid記法による処理の可視化 | 複雑な処理の整理 |
4本すべてをMarkdown形式で記述し、実装時にClaude Codeに参照させました。
「ドキュメント ≈ プロンプト」という発見
今回の開発で最大の気づきは、設計書をAIに参照させることは、詳細で一貫性のあるプロンプトを与えることと等価だったということです。
具体的に3つの効果がありました。
1. リトライの大幅削減
設計書にクラス構成・各クラスの責務を明記していたため、「意図と異なるコード」が生成されるケースがほぼ発生しませんでした。
前回の事例では「指示が反映されない」「デグレが頻発」という問題がありましたが、今回はそれが起きなかった。設計書という「一貫した指示書」が常にAIの参照先にあったからです。
2. 命名規則の統一
設計書でクラス名・メソッド名を定義していたため、命名が全体を通じて統一されました。
たとえば、各サービスクラスは XxxService 、各リポジトリは XxxRepositoryという命名規則が最初から最後まで一貫しています。
継ぎ足しスタイルだと対話のたびに命名規則がブレがちですが、設計書があればAIはそれに従います。
3. アーキテクチャの一貫性
パッケージ構成が設計書通りに生成され、対話のたびに構成が揺らぐことがありませんでした。
設計書で「このパッケージにはこの責務だけを置く」と定義しておけば、AIは新しいクラスを追加するときも適切なパッケージに配置します。前回の事例で問題になった「2600行が1ファイルに集中」という構造的な問題は、今回は最初から発生しませんでした。
定量的な成果
開発成果サマリー
| 指標 | 結果 |
|---|---|
| 総開発時間 | 約25時間（設計10h + 実装・テスト15h） |
| コード行数 | 約8900行 |
| ソースファイル数 | 31ファイル |
| テストファイル数 | 19ファイル |
| テスト件数 | 125件（単体71 + 結合44 + E2E 10） |
| テスト成功率 | 100%（125/125） |
| 行カバレッジ | 88% |
| 分岐カバレッジ | 70% |
| 検出バグ数 | 5件（全件修正完了） |
| ドキュメント数 | 27ファイル |
検出バグの分類
開発中に5件のバグを検出し、すべて修正完了しました。
| 検出フェーズ | 件数 | 主な原因 |
|---|---|---|
| 結合テスト | 3件 | フレームワーク設定の誤り、環境依存の問題 |
| E2Eテスト | 2件 | 外部APIの実挙動と設計時の想定の乖離 |
注目すべきは、単体テストではバグが検出されなかった点です。
設計書の情報が十分だった領域では、AIが正しいコードを生成できていました。
一方、設計書でカバーしきれなかった外部APIの実挙動やフレームワーク固有の挙動に起因する問題は、結合テスト以降で顕在化しました。
設計投資の回収分析
開発時間25時間のうち、約10時間（40%）を設計ドキュメント作成に費やしました。これは「遅い」ように見えるかもしれません。
しかし、この投資が実装フェーズで大きく回収されました。
| 設計の投資 | 投資時間 | 回収できた効果 |
|---|---|---|
| パッケージ構成の定義 | 約2h | コード構造が一発で決定。リファクタリング不要 |
| クラス設計・責務定義 | 約3h | 責務分離が適切。テストコード生成も効率化 |
| 処理フロー図の作成 | 約2h | 複雑なポーリング処理が一発で実装 |
| 外部API環境情報の整理 | 約1h | API呼び出しの検索条件が正確 |
特に実装フェーズが瞬時に完了した点は特筆に値します。
設計書を参照させてClaude Codeに実装を依頼したところ、約4800行の初期コードがほぼ一発で生成されました。
継ぎ足しスタイルで同じ規模のコードを書こうとしたら、試行錯誤に何倍もの時間がかかったはずです。
2つの事例を比較する
ここで、前回（Vibe Coding実践①）と今回（Vibe Coding実践②）の事例を並べてみます。
定量比較
| 指標 | 第1事例（非プログラマ） | 第2事例（本記事） |
|---|---|---|
| 実施者 | プログラミング未経験SE | プログラミング経験者 |
| 開発期間 | 10日間（業務の合間） | 約25時間 |
| コード行数 | 2633行 | 約8900行 |
| ファイル構成 | 1ファイル | 31ソース + 19テスト |
| テスト | なし | 125件（成功率100%） |
| カバレッジ | — | 行88% / 分岐70% |
| 設計書 | なし | 4本（27ドキュメント） |
| 使用ツール | ChatGPT + Codex CLI | ChatGPT + Claude Code |
本質的な違い: 「継ぎ足し」 vs 「ドキュメント駆動」
2つの事例の最大の違いは、開発のアプローチです。
実践①例: 継ぎ足しスタイル
- AIとの対話で逐次的に機能を追加
- 全体設計なしに「動くコード」を積み重ねる
- 速い、手軽、すぐ動く
実践②例: ドキュメント駆動スタイル
- 実装前にドキュメントを完成させる
- 設計書が「一貫したプロンプト」として機能
- 初期コストは高いが、品質が段違い
それぞれの強み・弱み
| 観点 | 継ぎ足しスタイル | ドキュメント駆動 |
|---|---|---|
| 初期速度 | 速い（すぐ動くものができる） | 遅い（設計に時間が必要） |
| コード品質 | 低下しやすい | 高く保てる |
| 保守性 | 低い（構造が劣化する） | 高い（設計書通りの構造） |
| 学習曲線 | 低い（誰でも始められる） | 高い（設計スキルが必要） |
| リトライ頻度 | 多い | 少ない |
| 最終的な速度 | 手戻りで遅くなりがち | 設計投資が回収される |
どちらが「正解」ということではありません。目的に合わせて使い分けることが重要です。
Vibe Codingが向いているケース・向いていないケース
2つの事例から、Vibe Codingの適用可否の判断基準が見えてきました。
向いているケース
| ケース | 推奨アプローチ | 理由 |
|---|---|---|
| プロトタイプ・PoC | 継ぎ足しスタイル | とにかく速くフィードバックを得たい |
| 個人の業務効率化ツール | 継ぎ足しスタイル | 自分だけが使うなら保守性は二の次 |
| 新規のバックエンドサービス | ドキュメント駆動 | 長期運用するなら設計投資が回収される |
| 外部連携を含むシステム | ドキュメント駆動 | 複雑な仕様を事前に整理することでバグを減らせる |
| チームで開発するプロジェクト | ドキュメント駆動 | ドキュメントがチーム内の認識合わせにもなる |
向いていないケース
| ケース | 理由 |
|---|---|
| ドメイン知識が非常に複雑 | ドキュメント化に膨大な時間がかかり、投資対効果が低い可能性 |
| AIの学習データが少ない技術 | マイナーなフレームワークではAI出力の品質が低下する |
| リアルタイム性が求められるシステム | パフォーマンスチューニングはAIの得意領域ではない |
| 大規模プロジェクト（数万行以上） | AIのコンテキスト制限に抵触する可能性 |
アプローチ選択の目安
最初は継ぎ足しスタイルでプロトタイプを作り、方向性が定まったらドキュメント駆動で作り直す
— これが現時点での最も実践的なアプローチだと考えています。
ドキュメント駆動の限界
ドキュメント駆動であれば万全かというと、そうではありません。
今回の開発でも、事前にドキュメント化しきれない領域からバグが発生しました。
ドキュメント化が難しい3つの領域
| 領域 | 起こりうる問題 | 今回の事例 |
|---|---|---|
| 外部APIの実挙動 | ドキュメントと実際のレスポンスが異なる | APIのレスポンス形式が設計時の想定と異なっていた |
| 実行環境の制約 | 開発環境では再現しない問題 | OS固有のエンコーディング問題 |
| フレームワーク固有の挙動 | 暗黙的な動作が想定外の結果を生む | 設定ファイルのマージ挙動が想定と異なった |
これら3つに共通するのは、「実際に動かしてみないと分からない」 という性質です。
対策: 完璧なドキュメントより「問題を伝える力」
重要な気づきは、これらの問題が発生したとき、AIに状況を報告すれば適切な修正が得られたことです。
ドキュメント駆動の真の価値は「完璧な事前設計」ではなく、問題が起きたときに的確にAIに伝えるための基盤を持つことです。
設計書があれば、「設計ではこうなるはずだが、実際にはこうなっている」と差分を明確に伝えられます。
まとめ
ドキュメント整備は「AIへの投資」
今回の検証で明らかになったのは、設計ドキュメントの整備がAI出力の品質を直接的に左右するということです。
10時間の設計投資は、実装フェーズでの試行錯誤をほぼゼロにし、テスト125件全成功・カバレッジ88%という品質につながりました。前回の事例で問題になった「動くけど保守できない」は、ドキュメント駆動によって解消できました。
自分の目的に合ったアプローチを選ぶ
Vibe Codingには「継ぎ足しスタイル」と「ドキュメント駆動」の2つのアプローチがあり、どちらにも適した場面があります。
| 目的 | アプローチ |
|---|---|
| とにかく速く試したい | 継ぎ足しスタイル |
| 品質を担保して本番運用したい | ドキュメント駆動 |
| 最初は試して、後で本番化 | 継ぎ足し → ドキュメント駆動 |
また、最適なアプローチは目的だけでなく、実施者のスキルレベルによっても変わります。
プログラミング経験者・SE未経験者・非SEそれぞれに適した進め方を、以下のペルソナ別活用ガイドで整理しています。
Discussion