Claude Codeにプログラム設計書105件を自動生成させた結果

2025年10月31日 2025年10月31日 Mark4

Mark4

7フェーズ方式と品質検証プロセス — 140件の設計書を生み出すまでの試行錯誤

140件の設計書を、どうやって作ったのか

前回の記事で、wagahiアプリの設計フェーズ3ヶ月の全記録をお伝えしました。今回は、その設計フェーズの中でも特に印象的だった「プログラム設計書の自動生成」について、具体的な手法と結果をお話しします。

結論から言えば、Claude Code（VSCode拡張）を使って、データベース8テーブル、バックエンド105クラス、フロントエンド27モジュール、合計140件のプログラム設計書を自動生成しました。

「自動生成」と書きましたが、ボタン一発で全部出来上がる魔法のような話ではありません。依存関係を考慮した順序設計、品質検証プロセス、そして数々の失敗と修正の繰り返しがありました。

7フェーズ方式 — 依存関係に基づく生成順序

プログラム設計書の生成で最も重要だったのは、「どの順番で生成するか」です。

バックエンド105クラスには複雑な依存関係があります。たとえば、Service層のクラスはRepository層とEntity層に依存し、Controller層はService層に依存します。依存先が未定義のまま依存元の設計書を生成すると、参照先のクラス名やメソッド名が不正確になります。

この問題を解決するために、7フェーズ方式を採用しました。

Phase 1.5-2: Entity クラス（User, Character, Message等）— 最も依存される基盤層
Phase 3: Repository インターフェース — Entity に依存
Phase 4: DTO クラス — Entity の公開用ラッパー
Phase 5: Configuration クラス — アプリケーション設定
Phase 6: Exception / Error クラス — 例外定義
Phase 7: Utility クラス — 横断的ヘルパー
Phase 8-12: Service → Controller → 統合 — 上位層を順次生成

各フェーズでは、前フェーズで生成済みの設計書をClaude Codeに読み込ませた上で次のフェーズの設計書を生成します。これにより、クラス名・メソッド名・引数の型が一貫した設計書群が出来上がります。

フルオート実行プロンプト — AIへの「作業指示書」

設計書生成を効率的に進めるために、フルオート実行プロンプトを作成しました。これは、Claude Codeに対する詳細な作業指示書です。

プロンプトには以下の内容を記載しています。

生成対象の設計書ファイル名とクラス名
参照すべき上位設計書（詳細設計書の該当セクション）
コーディング規約ファイルのパス
依存する実装済みクラスの確認手順
生成後のビルド・テスト実行手順
git操作（add, commit, push）の自動実行ルール

このプロンプトにより、1つのフェーズの設計書生成が「指示 → 生成 → ビルド確認 → コミット」まで一気通貫で進みます。人間が介入するのは、ビルドエラーが発生した場合と、設計書に不明点がある場合だけです。

準拠性100%検証 — 設計書の品質をどう担保したか

140件の設計書を生成しただけでは不十分です。生成された設計書が上位設計書（詳細設計書）に準拠しているかの検証が必要です。

当社が実施した検証プロセスは以下の通りです。

クラス名・メソッド名の照合: 詳細設計書に記載されたクラス名・メソッド名が、プログラム設計書に正確に反映されているか
パッケージ構成の確認: Maven標準ディレクトリ構造に準拠しているか
依存関係の検証: import文が正しいクラスを参照しているか
エラーコードの整合性: ErrorCodesクラスに定義されたコードが設計書と一致しているか
テスト設計の網羅性: 各クラスのテストケースが設計書に記載されているか

この検証プロセスを経て、最終的に準拠性100%を達成しました。ただし、最初から100%だったわけではありません。

失敗の記録 — 推測は最大の敵だった

正直に書きます。設計書生成の過程で、いくつかの重大な失敗がありました。

失敗1: テーブル名からクラス名を推測した

テーブル名 conversation_messages から Entity クラス名を ConversationMessage.java と推測して生成しました。正解は Message.java。設計書を読めば一発でわかることを、推測で進めてしまった典型例です。

失敗2: 定数クラスを確認せずに実装した

ErrorCodes.java の実装内容を確認せずに、設計書の記載だけで GlobalExceptionHandler を生成しました。結果、コンパイルエラー2件、エラーコード不一致7件。「確認する必要がありますが、設計書から実装できます」という自分への言い訳が、すべての元凶でした。

失敗3: テストコード55件を実装コード未確認で作成した

Flywayマイグレーション（実装済みSQL）を確認せずに、プログラム設計書だけを見てテストスクリプト55件を作成。トリガー名が2件誤っていました。実装コードが唯一の真実であり、設計書だけでは不十分だという教訓です。

これらの失敗から、強制停止ルールを設けました。

「確認する必要がありますが」と発言した時点で、即座に作業停止・確認実行
「たぶん〜だろう」「おそらく〜」という思考が浮かんだら、必ず実装コードを読む
「トークンを節約するため〜」という理由での省略は全面禁止

このルールは、今もCLAUDE.md（プロジェクトの設定ファイル）に明記されており、Claude Codeが作業を開始するたびに読み込まれます。失敗を仕組みで防ぐ。これもAI駆動開発で学んだ重要な知見です。

不明事象 — 設計と実装のフィードバックループ

設計書に基づいて実装を進めると、設計書には記載されていない事象に遭遇します。当社はこれを「不明事象」と呼び、番号を振って管理しました。

MVP_01期間中に発見・解決した不明事象は74件。たとえば、会話APIの冪等性保証（不明事象-059）や、Gemini APIのレスポンスフォーマット差異など、実際に動かしてみないとわからない問題が次々と見つかりました。

重要なのは、これらの不明事象を設計書にフィードバックしたことです。不明事象を解決したら、その解決策を該当する設計書に反映する。この「実装 → 試験 → 不明事象発見 → 設計書改定 → 再実装」のサイクルが、設計書の品質を継続的に向上させました。

数値で振り返る

プログラム設計書自動生成の実績を数値でまとめます。

生成した設計書: 140件（DB 8 + BE 105 + FE 27）
生成方式: 7フェーズ方式（依存関係順）
準拠性検証: 100%達成
実装後のテスト: 887件 → 最終的に1,922件（全合格）
不明事象: 74件発見・解決
MVP_01期間: 42日間（2025/10/02〜11/16）

140件の設計書を人手で書く工数を仮に1件2時間とすると、280時間（約35人日）。Claude Codeとの協働では、生成・検証・修正を含めて実質10日程度で完了しました。もちろん単純比較はできませんが、生産性の差は確実に存在します。

次回予告

次回は、この設計書群を使って結合試験を自動化した話をお伝えします。Playwright MCPを使ったブラウザ自動操作と、Chrome DevTools MCPによるRedux State確認。34の試験項目をAIに自動実行させた結果は、想像以上に実用的なものでした。

本記事は2025年10月時点の情報に基づいています。

著者: 株式会社シーテン — インフラ系から宇宙関連システムまで20年以上の開発経験を持つ技術者集団。2025年より生成AI・AIエージェントを活用したAI駆動開発に本格参入し、自社プロダクト「wagahi」の開発を通じて実践知見を蓄積中。

関連記事:

投稿者プロフィール

Mark4