仕様駆動開発（SDD）を採用したAI駆動開発の実態と課題

はじめに

こちらの記事は先日開催されたAI駆動開発についてのイベントの登壇内容をベースに記事にしたものです。
https://assign.connpass.com/event/368710/

発表後の反応が良く、特に「他社のAI駆動開発の実態を知ることができてよかった」という声をいただいたため、改めて記事化することにしました。

Claude CodeやCodex等を使用して開発している方は増えていると思いますが、実際に行っている開発フローを共有されることはあまり多くないため、私たちが実施しているAI駆動のフローを共有し、みなさんのAI駆動開発に参考になればと思います。

先に全体像共有

最初に全体像をお見せします。

AI駆動開発のフローは大きく4つのステップで構成されています。

1. 要件定義
2. 設計（バックエンド・フロントエンド）
3. 実装（バックエンド・フロントエンド）
4. PR

基本的に仕様駆動開発（Spec Driven Development）を採用しています。
SDDとは簡単に説明するとコードを書く前にしっかり仕様を定義して、AIと協業して開発を進める手法です。従来のvibe coding^[1]のようなフローではアウトプット精度にブレが大きく、手戻りが発生することが多々あったため、不確実性を減らし精度を上げるためにSDDを採用しています。
全体の開発フローはmiroを使って可視化しています。

あえてmiroで可視化していることには理由があります。
SDDはドキュメントを多く利用する都合上、数が膨大になりがちで、次のような問題に直面します。

• ディレクトリツリーだけでは全体像が見えにくく流れを把握しづらい
• ドキュメントの依存関係や参照関係がわかりづらく変更しづらい

そこで、少し工数をかけてでも全体の開発フローを可視化するようにしました。

各フェーズでのAI駆動開発

ここからは実際に各フェーズで何をやっているのか紹介していきます。
図は少し簡略化しています。

• 実線：同一コンテキスト
• 点線：別コンテキスト

要件定義フェーズ

インプット：特になし
アウトプット：PRD（Product Requirements Document）、DesignDoc、モック

ポイントは動くモックも同時に作っていることです。PRD等をインプットにV0^[2]やLovable^[3]、bolt^[4]などのツールを使って10パターン以上生成します。
主に次のような場面で活用しています。

• 要件が固まりきっておらず価値検証を優先したい時
• LPなど視覚的表現の検証を行いたい時
• 新規機能開発などの0→1の要素が強い時

このフローによって、モックを早期にペルソナに当てられることで検証のサイクルを大幅に短縮できます。例えば「ユーザーの目的が達成されていないのでフローを変えよう」や「パターンCのUXの方をベースに体験を改善しよう」のような意思決定ができます。モックを見てPRDを修正することもよくあり、文字だけの仕様書より動くものがあると議論が具体的になります。

設計フェーズ （バックエンド）

インプット：PRD / DesignDoc（Notion MCP）
アウトプット：API設計書、DB設計書、API詳細設計書、全体設計書

ここで重要なのは設計書を作成する順番です。インプットを元にAPI設計書を作成、次にAPI設計書を元に保持するデータを決めDB設計書を作成するのように、図で表している順番で設計書を作成するフローが最も効率的でした。

またフローを可視化したことで、API設計書は全開発工程で5回も参照される重要なドキュメントだと判明しました。バックエンドだけでなくフロントの実装でも参照されるため、この設計書の品質が悪いと後工程全体に悪影響を及ぼします。そのため特に丁寧なレビューを心がけています。

全体設計書はAIに現在地を把握させるために作成したドキュメントです。実装時にAIにポイントだけ渡すとドキュメント間の前後関係が失われ、コードの品質が悪くなることがありました。そのため、全体のどこを実装しているのかを把握してもらう目的で用意しています。

設計フェーズ （フロントエンド）

インプット：デザイン（Figma MCP）、API設計書、設計書テンプレート
アウトプット：画面仕様書、全体設計書、分割方針書、スコープ別仕様設計書

画面仕様書はコンポーネントの配置やデザインを詳細に記述したものです。AIには視覚的な情報が伝わらないため、「左上にカラーコード#D70C18のアイコン、その右に3つのナビゲーションメニュー」といった具体的な情報を記載しています。

スコープ別仕様設計書は1スコープ1PRの粒度になるよう分割した設計書です。フロントでは画面単位で分割しても実装量が膨大になりがちなため、適切な粒度で実装できるようスコープを明示的に定義しました。

実装フェーズ （バックエンド）

インプット：プロジェクトルール、API設計書、DB設計書、API詳細設計書、全体設計書
アウトプット：コード、テスト

仕様駆動開発により前段で作成した設計書を参照しながらAIが自律的に開発を進めることができます。「このAPIエンドポイントを実装して」と指示するだけで、DB設計書やデータフローを参照しながら適切な実装を行ってくれます。

不確実性を減らし品質を保つため、テスト駆動開発を採用しています。
実装スピードの向上により、コードがこれまでにない速さで変更されるようになりました。そのため品質を担保する目的でテスト駆動開発を取り入れています。

品質保証やテスト駆動開発については、弊社うちほり（@showichiro0123）が書いた記事で詳しく紹介しています。
https://zenn.dev/assign/articles/ai-driven-development-qa

実装フェーズ （フロントエンド）

インプット：プロジェクトルール、分割方針書、スコープ別仕様設計書、設計方針書
アウトプット：コード、テスト

フロントエンドではビジネスロジックとUIの両方のコンテキストが必要となり、参照ファイルが多くなるため、コンテキストウィンドウが急速に圧迫されます。
分割方針書を作成していない時期は大雑把に分割して指示を出しており、たびたびプロンプトを自動的に圧縮するauto-compactが発生して精度が落ちていました。

現在は精度を保つために、1スコープ1PRを基準にした分割方針書をベースにして、コンテキストを節約しながら開発を行っています。
実際には、1つの機能を次のように分割して開発を進めます。

1. 基本となる画面の枠組み
2. データ層の実装
3. 各コンポーネントの実装
   ...
   この分割方法により、1フェーズあたりの品質が大きく向上しました。

PRフェーズ

インプット：コード、Jira
アウトプット：PR

ここではJira MCPを使ってPRの背景を取得しています。実装内容だけでは変更の必要性が分からないことが多いため、ブランチに紐づくJiraチケットからコンテキストをMCPで取得し、PRのdescriptionに自動追記することでレビュアーの理解を助けています。

またClaude Code GitHub Actionsで一次レビューも行っています。人間のレビュー前に、基本的なコーディング規則違反やセキュリティ上の問題を検出してくれるので、一つのレビュー材料として利用しています。

課題

ここからは実際に直面した課題を2つ共有します。

課題1：作業スコープの肥大化

1つ目の課題は、実装時に実装量やスコープが肥大化してしまうことです。

1スコープ1PRの単位になるように分割していますが、想定していたボリュームを超えてしまう問題がたびたび発生しています。特にフロントエンドで顕著です。これによりコンテキストが圧迫され精度が低下する問題が発生し、さらに変更量が多いことでレビュアーの負担が大きくなる問題も生じました。
原因は分割方針書のルールが甘いことで、例えば実際のプロンプトに「10ファイル前後で分割して」という指示をしていますが、ファイル数だけではコード量を予測できないため肥大化しやすいです。

対策として取り組んでいるのは暗黙知の言語化です。「UIコンポーネントとロジックは別PR」「スタイリングの大規模変更は独立したPR」など、これまで人間が当たり前にやっていた分割基準を明文化していく必要があります。

課題2：実装者のセルフレビュー負荷

2つ目の課題が実装者のセルフレビュー負荷です。

生成コードをレビューするのは人間の責務ですが、確認量と修正箇所が膨大になり、修正漏れが発生してしまうことがあります。例えば生成されたコードで修正が必要な20箇所に対し、セルフレビューで17箇所は見つけて修正したものの、2、3箇所は見逃してしまいPRで指摘されるといったケースが発生しています。

対策は2つあります。1つ目はコーディング規則をより具体的にすることです。方針だけでなく「何をすべきでないか」も明記するようにしています。
2つ目は、気づきがあればコーディング規則以外でもドキュメントに都度フィードバックを反映し、継続的に改善していくことです。

今後の改善策

課題を踏まえて、次の改善に取り組んでいます。

• 暗黙知の言語化・コンテキスト追加
• ドキュメントテンプレートの改善
• コンテキストウィンドウ管理

フローの可視化により重要度の高いドキュメントが明確になりました。API設計書のような参照回数の多いドキュメントから優先的に改善を進めています。
またサブエージェントでのコンテキスト退避も今後特に力を入れていきたい領域です。Claude Codeのサブエージェントを使えば、別のコンテキストウィンドウで処理できるため仕様駆動開発と相性が良さそうです。
やることは多いですが結局はやるべきことを愚直にやっていくしかないため、コツコツ改善していきます。

まとめ

この記事で紹介した開発フローもまだまだ道半ばで、毎週のように改善を重ねている取り組みです。まとまった進展があればまた記事で紹介します。
現在はcc-sdd^[5]を参考にフローを見直している最中です。

ここまで読んでいただきありがとうございました。

脚注

1. vibe コーディングとは？：https://cloud.google.com/discover/what-is-vibe-coding?hl=ja

2. V0：https://v0.app/

3. Lovable：https://lovable.dev/

4. bolt：https://bolt.new/

5. cc-sdd：https://github.com/gotalab/cc-sdd