設計書6種一斉改定 — AI駆動開発における「設計と実装の乖離」との戦い
Mark4設計と実装のズレという永遠の課題にAI駆動開発で立ち向かった記録
「設計と実装の乖離」という永遠の課題
ソフトウェア開発において、設計書と実装コードが乖離していくのはよく知られた問題です。初期段階では一致していた設計と実装が、開発が進むにつれて少しずつズレていく。機能追加やバグ修正のたびに「まずコードを直して、設計書は後で更新しよう」となり、気がつけば設計書は実態を反映していない古い文書になっている。
wagahiアプリのAI駆動開発でも、この問題は避けられませんでした。RC_02のトークン経済改定を経て、設計書と実装コードの間に無視できない乖離が蓄積していたのです。
RC_02完了時の乖離状況
RC_02の完了時点で、以下の乖離が確認されました。
CHARACTER_GENERATIONプロンプトの改修12項目
キャラクター擬人化の品質向上のため、AIへのプロンプトを12項目にわたって改修していました。しかし、設計書にはRC_01時点のプロンプト仕様が記載されたままでした。
- プロンプトテンプレートの構造変更
- 地域特性を反映したキャラクター生成ロジックの追加
- 画像生成時の品質パラメータ調整
- エラーハンドリングの強化
- その他8項目の微調整
会話品質v1.1の反映漏れ
会話品質を改善するためにプロンプトエンジニアリングを見直した結果（会話品質v1.1）が、内部設計書に反映されていませんでした。
トークン経済改定の波及
前回・前々回の記事でお伝えしたトークン経済の全面改定とキラキラ玉廃止の影響が、一部の設計書に未反映でした。
6種設計書一斉改定の方針
乖離を放置するとさらに拡大する一方です。RC_02完了のこのタイミングで、全6種の設計書を一斉に改定することを決めました。
- DB詳細設計書: テーブル定義、制約、トリガーの現状反映
- バックエンド詳細設計書: API仕様、ビジネスロジック、例外処理の更新
- フロントエンド詳細設計書: コンポーネント構成、状態管理、UI仕様の更新
- OpenAPI仕様書: エンドポイント定義、リクエスト/レスポンス型の更新
- 内部設計書: アーキテクチャ図、処理フロー図の更新
- 外部設計書: 画面遷移図、ユーザー操作仕様の更新
機能ドメイン別分割 — 33ファイル＋5目次
一斉改定を進める中で、もう一つ大きな決断をしました。全設計書を機能ドメイン別に分割することです。
それまでのwagahiアプリの設計書は、各種類ごとに1つの巨大なMarkdownファイルでした。バックエンド詳細設計書は1万行を超え、フロントエンド詳細設計書も数千行。Claude Codeで作業する際、1つのファイルが大きすぎてコンテキストウィンドウに収まらないという実務上の問題がありました。
そこで、全設計書を機能ドメイン別に分割しました。
- バックエンド詳細設計書 → 10ファイル＋目次
- フロントエンド詳細設計書 → 10ファイル＋目次
- DB詳細設計書 → 2ファイル＋目次
- 外部設計書 → 5ファイル＋目次
- 内部設計書 → 6ファイル＋目次
合計33ファイル＋5目次。各目次ファイルには逆引き表を設け、「このAPIはどのファイルに記載されているか」「この画面の仕様はどこにあるか」を即座に特定できるようにしました。
新VM環境の構築（AlmaLinux 10.1）
RC_02の期間中に、開発環境のVMもAlmaLinux 10.1に移行しました。RHEL 10系への移行により、XorgからWaylandへの移行対応やパッケージ構成の変更など、環境面の調整も必要でした。
AI駆動開発ではMCPサーバー（Playwright、Cipher、Chrome DevTools等）の動作環境が重要です。新VMでのMCP動作確認に一定の時間を要しましたが、最終的にすべてのMCPサーバーが正常に稼働する環境を構築できました。
教訓: 設計書は「生きている文書」
今回の経験から得た最大の教訓は、設計書は実装と同時に更新しなければ、必ず乖離するということです。
AI駆動開発では、設計書がAIへの指示書としても機能します。設計書が古いと、AIが古い仕様に基づいてコードを生成してしまう。これは従来の開発以上に深刻な問題です。
RC_02以降、当社は以下のルールを導入しました。
- 実装変更時の同時更新: コード変更と設計書更新を同じコミットに含める
- フェーズ完了時の整合性レビュー: 各フェーズ完了時に設計書と実装の整合性を確認
- 目次ファイルの逆引き表: 「何を変えたらどの設計書を更新すべきか」を即座に特定
設計書を「書いて終わり」にしない。常に実装と同期させる。AI駆動開発の品質は、この基本原則にかかっています。
本記事は2026年1月時点の開発状況に基づいています。
著者: 株式会社シーテン — インフラ系から宇宙関連システムまで20年以上の開発経験を持つ技術者集団。2025年より生成AI・AIエージェントを活用したAI駆動開発に本格参入し、自社プロダクト「wagahi」の開発を通じて実践知見を蓄積中。
関連記事:
投稿者プロフィール
