2025年12月時点における私のAI駆動開発の活用方法 - 「仕様書駆動開発」編
はじめに
気がつけば2025年も終わりに近づいています。
今年はAIエージェントが急速に発展し、ソフトウェア開発におけるAI駆動開発の手法も大きく進化しました。前回同様の記事を書いたのは2025年5月でしたが、その後の数ヶ月で状況は大きく変わりました。
大きな転換点は、Claude Codeの登場でした。AIエージェントによって開発作業の多くが完結するようになり、ソフトウェア開発で実際にコードを書く作業がほぼ不要になりつつあるのが現状です。
ただ、それに伴い、AI駆動開発における新たな課題も浮上しています。解決方法についてはさまざまな分野で試行錯誤が続いている段階ですが、私なりの備忘録として、2025年12月時点におけるAI駆動開発の活用方法と課題をまとめておこうと思います。
私の現状
昨年からコードの実装をAIに依存する機会が増えていますが、ここで私の使用ツールの変遷と現状を整理しておきます。
まず、2025年1月時点。まだ開発者向けのツールは限定的で、MCPもリリースされたばかりでした。この時点ではCursorをメインに使い、制限を超えた場合にはClaude Desktop + Filesystem MCP を活用していました。GitHub Copilotも併用していましたが、性能やUXの面で物足りなさを感じ、補助的な利用に留まっていました。Devin AIなどのツールも試しましたが、最終的にはCursorを使い続けていました。
その後、5月にClaude Codeがリリースされ、状況は一変しました。IDEを使わずとも、AIエージェントが開発作業を完結できるようになったためです。2025年7月にはCursorのサブスクリプションを解約。現在はClaude Codeを利用するため、Anthropicへ月額100ドルを支払っています。（Cursorは頻繁にトークン制限に達していたことも、解約理由の1つです）
8月にGPT-5がリリースされ、Codex CLIと組み合わせて使い始めました。その進化には目を見張るものがあり、一時はGPT-5 + Codex CLIの組み合わせをメインにしていました。また、Gemini 3 Proのリリースに伴い、Gemini CLIの使用頻度も増えました。いずれのAIモデルも非常に優秀であり、コモディティ化の進展を実感させられました。
しかし、最終的にはClaude Codeに落ち着いています。動作の安定性に加え、サブエージェントやフック機能などのエコシステムも充実しており、現時点では他のツールへ乗り換える強い動機が見当たりません。
AI駆動開発の課題
コンテキストの喪失
基本的にAIエージェントは短期的なコンテキストに基づいて動作します。そのため、プロジェクトの全体像や設計意図を十分に理解しないままコードを生成してしまうリスクがあります。
実際に私が経験した例として、認証を必要としない想定のWebアプリに対し、AIエージェントが勝手に認証機能を実装してしまったケースがあります。 エージェント側はセキュリティを考慮した結果だったのでしょうが、プロジェクト全体の意図を把握していなかったために不要な機能を実装してしまったのです。
フランケンシュタイン・コードのリスク
「コンテキストの喪失」と密接に関連するのが、フランケンシュタイン・コードのリスクです。 複数のAIエージェントにより生成されたコードを組み合わせる際、各エージェントが異なるスタイルやアーキテクチャを採用していると、全体の一貫性や品質の低下を招く恐れがあります。
例えばReactを用いたフロントエンド開発では、複数の状態管理手法が存在します。ReduxやRecoil、Context API、Zustandなど、選択肢は多岐にわたります。 AIエージェントがそれぞれ異なる手法でコードを生成すると、コードベース全体の一貫性が失われ、保守が著しく困難になります。
実際、私のプロジェクトでも、一部でReduxが使われ別の箇所ではContext APIが使われるといった、ちぐはぐな状態になったことがありました。
分からないことが分からない問題
この問題は、エンジニア以上に、AIで開発を始めた非エンジニアのユーザーにとって顕著ですが、私自身も同様の経験をしています。 特に経験の浅い分野で設計をAIエージェントに任せた場合、提示された設計の妥当性を判断するのが難しい場面は少なくありません。
例えばフロントエンド開発において、「サーバーサイドレンダリング（SSR）」「静的サイト生成（SSG）」「クライアントサイドレンダリング（CSR）」のどれを採用すべきかという選択があります。最適な選択にはプロジェクト要件の深い理解が不可欠ですが、AIエージェントに丸投げしていると、最適な構成を見逃してしまうリスクがあります。
加えて、ユーザー自身に技術的知識が不足していると、生成された設計の問題点にすら気づけません。まさに「何が分からないのかが分からない」状態に陥ってしまいます。
「仕様書駆動開発」
今年の夏頃から、「仕様書駆動開発」という言葉を耳にする機会が増えました。 前述の通り、AIエージェントへ中長期的なコンテキストを適切に提供する難易度は高いと言えます。 この課題を解消するため、AI駆動開発を取り入れているチームの間で注目され始めているのがこの手法です。
私も今年の8月以降、AIエージェントへいかにコンテキストを伝えるかを試行錯誤してきました。時にはAI任せにしてフランケンシュタイン・コードを生み出すこともありましたが、最終的に「仕様書駆動開発」へ行き着いたことで、開発の安定性を確保できるようになりました。
GitHubのSpec KitやKiro、国内ではcc-sddなどが代表的なツールです。これらは仕様書をドキュメントとして整備し、それに基づいてAIエージェントへ指示を出す手法です。PRP (Product Requirement prompts)も同様の思想に基づいています。
私は現在、ai-coding-project-boilerplateをベースにした独自の仕様書テンプレートやエージェントを活用しています。具体的な構成はまだブラッシュアップ中ですが、基本的なプロセスはどのフレームワークも共通しています。
sequenceDiagram
participant U as ユーザー
participant A as AIエージェント
participant S as 仕様書
participant C as コード
U->>S: 要件定義を作成・更新
U->>A: 要件に基づいて仕様書を作成・更新を指示
A->>S: 仕様書を生成・更新
loop 仕様書レビュー
S->>U: 生成された仕様書を確認
U->>A: フィードバックを提供・修正指示
A->>S: 仕様書を修正・更新
end
loop コード生成
U->>A: 仕様書に基づいてコード生成を指示
A->>S: 仕様書を参照
A->>C: コードを生成・更新
U->>C: 生成されたコードを確認
U->>A: フィードバックを提供・修正指示
end
loop コードレビュー
C->>U: 生成されたコードを確認
U->>A: フィードバックを提供・修正指示
A->>C: コードを修正・更新
end
AIエージェントへ長期的なコンテキストを明示的に提供することで、設計意図を維持したままコードを生成させる。これが「仕様書駆動開発」の根幹となる考え方です。
「仕様書駆動開発」を導入して感じたメリット
以下に、個人的に感じているメリットをまとめます。
AIだけでなく人間にとっても大きな恩恵がある
以前の記事でも触れましたが、仕様書の有無は人間側の安心感に直結します。 最悪の場合、AIエージェントにはコードを読ませて仕様を把握させることも可能です。しかし、人間にとっては、開発経緯や設計意図を記したドキュメントがあるだけで安心感が格段に増します。 「このコードを修正していいのか分からない」といった意図不明の実装に遭遇し、開発スピードが停滞する事態を避けられます。
また、チーム開発において新規メンバーが参画する際や、既存メンバーが久々にプロジェクトへ戻った際も、仕様書があれば全体像を素早く把握できます。 キャッチアップの時間を短縮し、スムーズに開発へ参加してもらえるのは大きな強みです。
仕様書駆動開発は、ドキュメントの重要性を再認識させてくれました。 従来は開発の最終段階やリリース直前に作成されがちだった仕様書ですが、この手法では初期段階から継続的な更新が求められるため、ドキュメント整備のモチベーションを自然に維持できます。
バグ混入時のコンテキスト提供が容易になる
ソフトウェア開発にバグはつきものであり、AIエージェントに任せていても一定の頻度で発生します。
以前は「どこでバグが紛れ込んだのか」「どのような意図でそのコードが書かれたのか」をエージェントに伝えるのは骨の折れる作業でした。 コードの変更履歴を辿りながら、「このコードは本来こういう意図だったが、結果としてこのようなバグが生じているので修正してほしい」と説明するのは非常に手間がかかります。
仕様書駆動開発の導入以前は、バグ修正を依頼した際に、副作用で既存の機能が消失してしまうことすらありました。 しかし仕様書を参照できる現在は、エージェントへ正確なコンテキストを伝えやすくなっています。
例えば、Claude Codeと仕様書駆動開発を組み合わせれば、以下のように的確な指示が可能です。
@docs/done/2025-12-15-refactor-map-reduce.md で実装された Map-Reduce 機能にバグがあります。reduce 関数が正しく動作していないようです。仕様書の該当箇所を確認し、設計意図に沿って修正してください。コード全体の整合性にも注意をお願いします。
最近では、Claude Codeのコマンド機能を活用することで、より効率的に修正を依頼できるようになりました。
/dev:fix-bug @docs/done/2025-12-15-refactor-map-reduce.md Map-Reduce 機能が動作しません。
進捗状況を把握しやすい
AIによる開発が主流になっても、依然としてタスクの進捗を共有する機会は多くあります。 デイリーの共有なら簡単なメモで済みますが、月次報告などでプロジェクト全体の歩みを整理するのは意外と重労働です。
ここでも仕様書駆動開発が役立ちます。 Claudeへ指示を出すだけで、蓄積されたドキュメントを基に週次や月次の進捗レポートを生成できます。
12月3日から12月17日までの進捗レポートを作成してください。
プロジェクト管理を目的とした状況把握のため、`docs/done`フォルダ内のタスクを参照し、各タスクの概要と完了状況をまとめてください。
類似タスクは整理し、全体の進捗が俯瞰できるようにしてください。
「仕様書駆動開発」の難しさ
一方で、運用を通じて感じた難しさについても触れておきます。
設計フェーズの負荷増大
「仕様書駆動開発」の要は、その名の通り「仕様書」にあります。 仕様書の品質が低いと、生成されるコードの質はもちろん、プロジェクト全体の健全性も損なわれます。
前述の通り「分からないことが分からない問題」も無視できません。 AIエージェントに設計を委ねる場合でも、提示された設計の最適性を判断するには、一定の知識や検証が欠かせません。
ドキュメント作成に丸一日を費やすことも珍しくなく、プロジェクトの管理レベルは向上したものの、純粋な生産性は以前より落ちていると感じる場面もあります。 手戻り（リグレッション）が減っていることを考えればプラスなのですが、人間の負荷が増えている点は今後の改善課題です。
仕様書のメンテナンスコスト
仕様書を常に最新の状態に保つコストも大きな課題です。 内容が古くなってしまうと、AIエージェントが誤ったコンテキストに基づいてコードを生成するリスクが生じます。
また、どのような形式でどこまでの情報を仕様書に含めるべきかという、運用のさじ加減も重要です。 単なる要件定義で十分なのか、Architecture Decision Record（ADR）のような意思決定の記録まで必要なのかなど、検討すべき事項は多岐にわたります。
管理工数の増大に対し、効率化の手法を模索しています。 Claude Codeのフック機能を活用してドキュメントのメンテナンスを部分的に自動化するなど、ツールによる支援も取り入れ始めています。
おわりに
2025年はAIの活用が爆発的に進み、「AIがホワイトカラーの仕事を代替する」といった議論が現実味を帯びた一年でした。 しかし、LLM特有のコンテキスト制限やハルシネーションといった課題に向き合っていると、最終的には人間による関与が不可欠であると強く感じます。
一時期は「すべてをAIに任せられるのではないか」と考えたこともありましたが、現在はAIと人間の役割分担を最適化することが重要だと考えています。 設計や要件定義といった創造的なプロセスは人間が主導し、AIはその補助に回る。一方で、コード生成、テスト、定型的なドキュメント作成といった反復作業はAIエージェントに任せる。このバランスが現在の最適解ではないでしょうか。
将来のことは分かりませんが、日々の進歩を楽しみながら、AI駆動開発のさらなる可能性を追求していきたいと思います。