AI開発で「これじゃない」コードが出てくる悩み
開発において、AIを使っていてこんな経験はありませんか？
- 自分が思っているコードが出てこないし、修正指示を出すと別の場所が壊れる
- 想定外の実装をされ、レビュー負荷が高まる。逆に時間が奪われる
自分もこうした経験何度もしてきました。
時短・効率化のためにAIを使っているはずが、これでは本末転倒ですよね・・・
原因：AIは「超優秀だけど指示待ちの新人」
なぜAIは、こちらの意図と異なるコードを出力してしまうのでしょうか？
AIの性能限界も要因の一つですが、実は私たち「人間の指示」に問題があるケースがほとんどです。
AIはいわば「超優秀だけど指示待ちの新人」です。
知識は豊富で、技術力が高い。
ただ、新人なので周りの環境がわからず、教えてもらうまではルールも知らない。
そして、指示されたこと以外はできない。
そんな存在がAIです。
いきなり「いい感じに作って」と投げても、うまくいかないのは当然ですね。
解決策は「仕様書」を書くこと
この「超優秀な指示待ち新人」のポテンシャルを引き出すにはどうすればいいでしょうか？
答えは「仕様書」を作成することです。
詳細な仕様書こそが、AIにとって「最強のプロンプト」となり、迷いをなくします。
「仕様書を作るなんて、余計に時間がかかるのでは？」と思うかもしれません。
安心してください。その仕様書作成自体もAIに任せればいいのです。
ここからは、私が実践している 仕様駆動開発（SDD） という仕様書を用いてAIに開発を進めるフローを紹介します。
仕様書を作って開発してみよう（実践編）
ここからの作業は、すべてAIと対話しながら進めていきます。
ちなみに私は GitHub Copilot を使っていますが、Cline や Cursorなど、使い慣れたツールで実践していただいて構いません。
STEP1：現状の調査と方針決め
いきなり「コードを作って！」と指示は出さず、まずは「相談」をするところから始めていきましょう。
特に既存のプロジェクトの場合は、参考になるコードや似た機能がある可能性があるので、この作業はとても重要です。
- 既存コードから参考箇所を探させる
- 実現したい機能が実装可能か調査させる
スクリプト例：
## 事前調査・実現方法の検討 実装したい機能について: - <機能の説明> 行ってほしいこと: - 機能に関連しそうな既存の実装の調査 - 関連するモデル・クラス等はメモとして残してください - <その他気になること（影響範囲・セキュリティ上の考慮事項など）> - 実現可能かの調査 - 実装できる場合はアプローチの選択肢とそれぞれのメリット・デメリットを教えてください - 調査内容のマークダウン出力 注意点: - 調査段階なので実装はしないでください - 追加で必要な情報があれば教えてください
STEP2：AIに仕様書を作成させる
STEP1の調査結果を元に、AIに仕様書（設計図）を書かせ、人間はそれをレビューします。
ポイントは以下の2点です。
- コミット計画を立てる：「1機能1コミット」になるように作業手順を分割させる
- 処理フローを図示させる：Mermaid記法などで可視化し、認識のズレを防ぐ
ここでAIと「実装方針のすり合わせ」を行うことで、手戻りを劇的に減らせます。
スクリプト例： ※ 調査結果のマークダウンファイルを添付してください
## 仕様書の作成 調査結果を元に、実装のための仕様書をマークダウンファイルで作成してください。 ### 出力する内容について 1. 機能概要: 実装する機能の目的と概要 2. 処理フロー: Mermaid 記法を用いたシーケンス図、またはフローチャート - 正常系だけではなく異常系の考慮も含めてください 3. 実装計画: - 作業をPhase（コミット単位）に細分化してください - 各Phaseには以下を含めてください - 編集・作成するファイルについての説明 - 実装内容 - 関連・参考ファイル・コード
STEP3：仕様書に沿った実装を行う
作成した仕様書（マークダウンファイル）を添付しAIに実装を依頼します。
- 必ずPhase（コミット）ごとに実装する：一気にやらせると、バグの特定がしづらくなります。「新人のキャパシティ」を考慮しましょう
- テストコードもセットで書かせる：動かないコードを受け取らないためにも動作の担保まで行いましょう
AIの実装が完了したら、人間が動作確認を行い、次のSTEPに進みます。
STEP4：AIによる客観的なレビュー
実装完了後はAIに自分のコードをレビューをさせましょう。
ここで重要なのは、必ず「新しいチャット（別スレッド）」を立ち上げることです。
- 理由: AIはチャット内の会話に引きずられる癖があるため、あえて記憶をリセットさせます
- 効果:「背景を知らない第三者」として、客観的に厳しいレビューを引き出せます
STEP5：人間による最終レビュー
最後は自分自身でレビューをしましょう。
- プロジェクト固有の命名規則や、不要な処理がないかを確認
- 処理として通っているものの、無駄な変数を定義している場合や、処理をまとめることができる場合があります
- 既存プロジェクトへの追加や運用をする場合は、チーム全員が効率よく開発できるように保守性の観点でレビューをする
以上で仕様書を用いたAI実装が完了です。
まとめ
今回は、AIに振り回されず確実に実装を進める「仕様駆動開発」について紹介しました。
- AIは「超優秀な指示待ち新人」。指示（仕様書）次第で仕事の出来が決まる
- 急がば回れ。いきなりコードを書かせず、仕様書と計画を作らせることでイメージを合わせる
- 実装・レビューを分ける。役割が違う場合は別チャットにすることで品質を担保する
自分も以前は「AIなんだから自分で考えてくれないかな〜」とか思っていましたが、
「自分がしっかり仕様を理解して、適切な指示（仕様書）を渡す」というスタンスに変えてから、AIの精度が上がり「最強のアシスタント」に変わりました。
最初は仕様書を作るのも手間に感じるかもしれませんが、手戻りが減り、結果的に開発スピードもコードの品質も上がると思います。
「AIに振り回されている感」がある方は、ぜひ一度このフローを試してみてください！
