「不明事象」との戦い — AI駆動開発のデバッグ戦略
Mark4設計書に書かれていない74件の壁 — 番号管理と根本原因追跡の記録
設計書に書かれていない現実
前回の記事で、Playwright MCPを使った結合試験の自動化についてお伝えしました。51項目、272期待結果、100%合格。数字だけ見れば順調そのものです。
しかし、この「100%合格」に至るまでの道のりは、決して平坦ではありませんでした。設計書通りに実装し、試験を実行すると、設計書には記載されていない事象が次々と見つかるのです。
当社はこれを「不明事象」と呼び、通し番号を振って管理しました。MVP_01期間（42日間）で発見・解決した不明事象は、74件に上ります。
不明事象の管理方法
不明事象の管理は、シンプルなルールで運用しました。
- 発見したら即座に番号を振る: 「不明事象-001」「不明事象-002」…と連番管理
- 調査結果を記録する: 発見日時、再現手順、原因分析、解決策をMarkdownで記録
- 解決したら設計書に反映する: 設計書の不備が原因であれば、設計書を改定する
- Cipher MCP（メモリ永続化ツール）に記録する: 次のセッションで再利用するため
特に重要なのは3番目のルールです。不明事象の解決は「バグを直して終わり」ではなく、「設計書を正しい状態に更新する」ことまでが1セット。この「設計書フィードバックループ」が、プロジェクト全体の品質を底上げしました。
会話API冪等性保証 — 不明事象-059
74件の中で最も印象的だった不明事象を紹介します。
不明事象-059: 会話APIの冪等性保証
結合試験IT-API-CONV-001を実行中、同じメッセージを短時間に2回送信すると、会話履歴に重複メッセージが記録される現象を発見しました。
原因は、会話APIにリクエストの冪等性（同じリクエストを複数回送っても結果が変わらない性質）を保証する仕組みがなかったことです。設計書には「メッセージを送信する」とだけ記載されており、重複送信への対応は想定されていませんでした。
解決策として、フロントエンド側での送信ボタンの二重クリック防止と、バックエンド側でのリクエストIDによる重複チェックを実装しました。そして、この対策を詳細設計書と内部設計書の両方に反映しました。
AIが設計書を生成する際、このような「ユーザーの予期しない操作」への対策は見落とされがちです。実際に試験を通してこそ発見できる問題であり、だからこそ結合試験の自動化が重要なのです。
設計書フィードバックループの確立
不明事象を74件解決する中で、自然と確立されたのが設計書フィードバックループです。
- 実装: 設計書に基づいてコードを書く
- 試験: 結合試験を自動実行する
- 不明事象発見: 設計書にない問題を発見する
- 設計書改定: 設計書を現実に合わせて更新する
- 再実装: 改定された設計書に基づいて修正する
このサイクルを回し続けることで、設計書は「理想の姿」から「現実に即した正確な仕様書」へと進化していきます。
AI駆動開発では、AIが生成した設計書を「完成品」と見なしがちです。しかし実際には、設計書は「進化する文書」であり、実装と試験を通じて継続的に改善されるべきものです。不明事象の管理は、この改善プロセスを仕組み化する手段でした。
MVP_02 — 7日間の短期集中スプリント
MVP_01の42日間で基盤が固まった後、MVP_02はわずか7日間の短期集中スプリントで実施しました（2025年11月12日〜18日）。
MVP_02のスコープは以下の通りです。
- トークン使用量表示: Gemini APIのトークン消費状況をユーザーに可視化
- アイコン実装: キャラクターアイコンの表示・管理機能
- DB設計書整合性確保: Flywayマイグレーション（V001〜V020）と設計書の完全整合性確認
7日間で完了できた理由は2つあります。
1つ目は、MVP_01で確立したフィードバックループが機能したこと。設計書が現実に即した正確な状態になっていたため、「設計書通りに実装すれば動く」状態が実現していました。
2つ目は、設計書と実装の双方向整合性検証をMVP_02の重要タスクとして位置づけたこと。Flywayの全マイグレーションファイル（V001〜V020）と設計書を突き合わせ、カラム追加（encrypted_initial_greeting等）を設計書に正確に反映しました。
結果として、システムテスト（ST-003〜ST-005）は100%合格を達成。設計と実装の乖離をゼロに保つことが、開発速度の向上に直結することを実証しました。
不明事象から学んだ教訓
74件の不明事象と向き合って得た、AI駆動開発における教訓をまとめます。
教訓1: AIは「正常系」が得意で「異常系」が苦手
AIが生成する設計書やコードは、正常系のフローは高い品質で生成できます。しかし、エッジケース（重複送信、タイムアウト、不正入力など）への対応は、人間のレビューと試験による発見が不可欠です。
教訓2: 設計書は「完成品」ではなく「進化する文書」
設計書フィードバックループを回すことで、設計書の品質は実装・試験のたびに向上します。初期の設計書に固執するのではなく、現実に合わせて柔軟に改定する姿勢が重要です。
教訓3: 不明事象の管理は品質投資
不明事象に番号を振って管理し、解決策を設計書に反映する。この地道な作業は、一見すると非効率に見えます。しかし、MVP_02以降の開発速度を見れば、この投資が確実にリターンを生んでいることがわかります。
次回予告
次回は、Gemini APIを組み込んだAIチャット機能の実装記をお伝えします。キャラクターとの自然な会話を実現するためのプロンプト設計、トークン消費の最適化、そしてMagic Link認証への全面移行。MVP_02からMVP_03にかけての技術的挑戦の記録です。
本記事は2025年11月時点の情報に基づいています。
著者: 株式会社シーテン — インフラ系から宇宙関連システムまで20年以上の開発経験を持つ技術者集団。2025年より生成AI・AIエージェントを活用したAI駆動開発に本格参入し、自社プロダクト「wagahi」の開発を通じて実践知見を蓄積中。
関連記事:
投稿者プロフィール
