AIコーディング：どうやって開発を進めるか

はじめましてKappanKappaです。

ゲーム業界で37年間、エンジニアとして仕事をしています。

最近はClaude CodeやCodexを使って、ゲームやアプリの開発、古いプロジェクトの移植などを行っています。

AIコーディングの話では、「どう指示すれば、思ったとおりのコードを書いてくれるのか」が話題になりがちです。

もちろん指示の書き方は大切です。ただ、実際にいくつかの開発を進めて感じたのは、プロンプトの文章を練ることだけでは足りない、ということでした。

重要なのは、次の一連の進め方です。

1. 自分で分かっている仕様を書く

2. AIが判断するための材料を渡す

3. まず小さく動くものを作る

4. 実行結果をそのまま返す

5. AIが作ったものを確認する

6. 迷走したら、修正を止めて調査方法を変える

この記事では、これまでの開発経験から、この流れを具体的に説明します。

---

最初に渡すのは「長い指示」ではなく、仕様と判断材料

昔に自作したWindows Mixed Realityヘッドセット向けのVRゲームをMeta Quest向けに移植したときのことです。

用意したのは元のプロジェクト一式。Unityのバージョンも古いため今では動きません。

最初の指示は簡単なものでした。

 このプロジェクトを読んで、Meta Quest向けに移植してください

これだけを見ると、短い指示でもAIが何とかしてくれるように見えるかもしれません。

しかし、このとき重要だったのは指示の短さではありません。AIが既存プロジェクトのソースコードや設定ファイルを直接読める状態だったことです。

既存プロジェクトの移植なら、現在のコードそのものが大きな判断材料になります。AIはそこから、使っているライブラリ、プロジェクト構成、古くなった設定、移植に必要な変更を調べられます。

実際にAIはソースコードを解析して、古いUnity向けのプロジェクトであること、Windows MR用SDKが使われていることなどを理解しました。そして、使用するUnityバージョンを最新のものにし、Windows MR用SDKを削除し、Meta Quest用SDKを追加して移植作業を始めました。

一方、新しいゲームを作る場合は事情が違います。企画メモや仕様書など、どんなゲームか分かるものを渡します。画面のイメージサンプルがあればそれも渡します。

私が別のゲームを作ったときには、10年前に書いた企画メモを出発点にし、そこから不足している仕様を詰めていきました。

つまり、AIに渡すものは作業によって変わります。

・ 既存コードの不具合を直すなら、ソースコード一式と共にエラーログ、再現手順、実際に起きた現象などの情報

・ 新しく作るなら、企画メモ、仕様書、画面案、参考にしたいものなど

自分で書ける仕様は、最初から書いたほうがよいです。決まっていない部分まで無理に埋める必要はありませんが、決まっていることをAIの推測に任せる理由もありません。

これらはファイルとして渡して、

error.txtに出力されたエラーコードと再現手順があります。

あるいは、

documentディレクトリに現時点での仕様と画面イメージのPNGがあります。

のように、プロンプトでファイルの場所を示します。長いプロンプトの中でソースファイルやログを要約するより、ファイルで置いてAI自身に読ませたほうが正確です。

最初の依頼には、少なくとも次の項目があれば十分です。

・ 何を作る、または何を直すのか

・ 参考にするファイルはどれか

・ 今回どこまで作業するのか

・ 何ができれば完了なのか

完璧なプロンプトを先に作るのではなく、分かっている仕様と、AIが調査に使える材料を揃える。ここが出発点です。

---

いきなり完成品を作らせず、まずプロトタイプを作る

新しいゲームの開発では、最初からすべての仕様を実装させませんでした。

RPGを作ったときの最初のプロトタイプでは、たとえば次のように範囲を絞っています。

・ 戦闘コマンドはダミーでよい

・ ボタンを押せば勝敗が決まるだけでよい

・ マップは一直線でよい

・ 敵画像は仮でよい

・ 合成画面は見た目だけでよい

ここで確認したかったのは、完成品として遊べるかどうかではありません。画面を触ったときに、ゲーム全体の流れが想像できるかどうかです。

ちなみにAIが作ってくれた敵画像は、仕様として渡したモンスターの名前から類推できる雑な絵でした。

文章で仕様を考えているだけでは、気づかないことがあります。実際に画面が出て、ボタンを押して、次の画面へ進むだけでも、「この流れは分かりにくい」「ここは思っていたより面白くない」「この機能は先に必要だ」といったことが見えてきます。

プロトタイプは、完成品の安い代用品ではありません。仕様についての疑問に答えるための、動く確認材料です。

そのため、AIには「作ってほしいもの」だけでなく、次の2点も伝えます。

・ 今回は何を確認したいのか

・ その確認に不要なので、何を作らないのか

AIは、書かれた要求をできるだけ実現しようとします。範囲を決めなければ、確認したいことに必要のない部分まで作り込みます。

また、相談だけしたいときには「ファイルは変更せず、意見だけください」、調査だけなら「まだ修正しないでください」と書きます。作業範囲だけでなく、相談・調査・実装のどこまで任せるのかも明示しておかないと、意図しない変更が発生してしまいます。

仕様書は見た目に凝る必要はありません。自分で書ける範囲をテキストファイルに書き、そのファイル名をAIに指示して読ませれば十分です。

---

AIにフィードバックする

AIコーディングの実作業は、次の繰り返しです。

1. AIが調査し、修正する

2. 人間が実際に動かす

3. 起きた現象やエラーをAIへ返す

4. AIがもう一度調査する

VRゲームの移植では、ビルドが通ってもMeta Quest実機では動かないことがありました。そのときは、実機で起きたことを渡すと、AIは接続されたMeta Quest上でゲームを実行し、エラーログを取得して解析を進めてくれました。

ここで、人間が先回りして原因を決めないことも大切です。

「この設定が悪いと思う」と伝えると、AIはその仮説に沿って調査しやすくなります。自分の見立てを伝える場合でも、まずは次の事実を分けて渡します。

・ 何をしたか

・ 何を期待していたか

・ 実際には何が起きたか

・ 表示されたエラーやログ

ログはファイルで渡せばよいですが、短ければプロンプトの中に書いても構いません。

AIに足りないのは、巧妙なプロンプトより、AIからは見えていない実行結果です。「修正しました」という報告で一区切りにせず、実際に動かした結果まで含めて次の判断材料にしていきます。

---

成果物は「増えたもの」と「消えたもの」の両方を見る

AIで文章を作成したときにも、出来上がった文書を人間が確認したほうがよいです。

AIが出力するものは冗長になりがちです。プロンプトで細かく指示していた内容を残しておくために仕様書として出力してもらったとき、こんなことがありました。

1. 仕様Aを実装

2. 実行したがいまいちなので、Aを修正するにあたり要素Bを付け加える

3. 動かしてみると、いまいちだったので、要素Bは取り消してCに変更

4. A+Cで納得できたので、これで完成とし、仕様書として出力させる

すると出来上がった仕様書には、消したはずのBの内容が書かれていました。疑問に思いながら読み進めると、その後に「Bは取り消してCに変更」と書かれ、さらにCの内容が続いていました。

AIはなるべく記録を残そうとします。不要になって消したものも、消した記録として残してしまうのです。

私はその仕様書から、Bについて書かれている箇所をすべて消しました。

仕様書は試行錯誤の記録ではないからです。

反面、残しておきたい内容が記載されていないこともあります。

それも読まないと分かりません。

コードについても同じです。

AIは力業でコードを大量に書き換えるため、同じ処理が何か所にも生成されてしまいやすいです。

時には、必要だったコードが不要物として削除されていることもあります。

これも目視で確認しないと分かりません。

コードが読める人は、AIが作ったコードをざっと眺めるだけでもよいので、チェックするとよいです。

---

AIにチェックさせる

個別の変更だけでなく、全体を横断した確認もAIに向いています。ゲームの仕様が固まってきた段階で、仕様書全体を読ませ、疑問点、矛盾点、曖昧な点をすべて出すように頼んだところ、28件の指摘が出たことがありました。

仕様書の文章量が増え、最初のほうと後のほうで内容に矛盾がありました。これは私のミスをAIが指摘してくれた形です。

人間が一つずつ仕様を決め、AIに全体を横断して抜けや矛盾を探させる。この分担はうまく機能しました。

 現在の仕様全体を読み、疑問点、矛盾点、曖昧な点を挙げてください。
 内容は変更せず一覧にしてください。

このように、確認のみと明示することで、意図しない変更を防ぐことができます。

---

同じ方向の修正で変化がなければ、いったん止める

AIが「修正しました」と報告しても、同じ不具合が残り続けることがあります。

あるゲームの開発中、画面にオーバーレイが表示されない不具合がありました。AIは描画方法が原因だと考え、その方向で修正を続けました。しかし、何度直しても現象は変わりません。

そこで修正作業を止め、いま何を疑い、何を変更しているのかを説明させました。実際の原因は描画方法ではなく、シーンリストの順番でした。そのシステムはシーンリストの順番が描画順に直結しており、オーバーレイ表示がシーンリストの先頭にあるため上書きされて見えない、という不具合でした。

このときは、半透明描画フラグが消えて不透明になっているのではないかとAIは描画命令を延々と書き換えていました。

描画命令の不備以外に、描画順などは影響しませんか

と聞くと、

描画優先度はシーンリストの順になるので、オーバーレイはシーンリストの最後に書く必要があります

と返ってきました。そこで私は下記のように伝えました。

それについても問題ないか確認して修正を続けてください

その結果、すぐに直りました。

問題は、何回失敗したかではありません。同じ仮説に基づく修正を続けても、現象が変化していないことです。

何度直しても直らない。その状態になったら、いったん作業を止めます。

まだ修正しないでください。
現在の仮説、これまでに変更した箇所、変更後も現象が変わらない理由、まだ確認していない可能性を整理してください。

AIは、一度もっともらしい仮説を立てると、その仮説の中で修正を続けることがあります。人間が同じ不具合報告を繰り返すだけでは、AIに新しい材料が増えません。

AIは知識豊富です。「シーンリストと描画順」について知っています。しかし、現在の不具合と持ち合わせている知識が結びつかないことがあります。

不具合の原因について一度怪しいと思い始めると、ほかの方向性に切り替えずに固執し続けることもあります。

そんなときは、AIにほかの可能性はないか確認すると、AIは調査の方向性を広げてくれます。

---

調べ方を変える

VRゲームの移植では、SDKまわりの問題で画面が正しく表示されない不具合がなかなか解決しませんでした。延々とコードを書き換えては試すものの、どれもうまくいきませんでした。

そこで介入し、方針を変えることにしました。

まず、新規に空のプロジェクトを作り実行させます。

すると、画面は正しく出ました。

次に、正しく表示されないゲームのプロジェクトと、正しく表示される空のプロジェクトを両方確認して比較するように指示しました。

原因を直接当て続けるのではなく、正常に動く最小構成を用意し、差分から原因を絞る方法に変えたわけです。

その結果、設定の一部が適切でなかったことが判明し、画面は正しく表示されるようになりました。

人間がデバッグする場合も、こういった比較は有用なのですが、AIは大量のファイルの読み込みと比較が瞬時にできるので、人間が行うよりもずっと速いです。

ですが、そもそも「正常な状態のものと比較する」という発想が出てきません。

このあたりは、人間の介入が必要なパターンです。

不具合調査では、ほかにも次のような切り分け方があります。

・ ログを増やして、どこまで動いているか確認する

・ 機能や条件を一つずつ外す

・ 入力を最小にする

・ 正常な環境と失敗する環境を比較する

・ 変更前後の差分を確認する

AIに「直して」と頼み続けると、現在の仮説の中で別の修正案を出し続けることがあります。そこで、依頼を変えます。

原因を直接当てるのではなく、切り分け方を考えてください。
正常な最小構成との比較、ログの追加、条件の除外など、現在の仮説を検証できる方法を挙げてください。

「修正案」ではなく「仮説を検証する方法」を求めることで、調査の進め方を変えられます。

---

エンジニアの経験値が必要か

AIが迷走していることに気づくことや、どの切り分け方が有効かを選ぶことには、経験の差が出ます。私が正常な空プロジェクトとの比較を提案できたのも、ソースコードを見て怪しい場所を探せたのも、長く開発をしてきた経験が影響しています。

そのため、「AIを使えば、誰でも同じように原因を見つけられる」とは思っていません。

一方で、経験がなくても使える判断基準はあります。

・ 同じ方向の修正を続けても、現象が変わっていない

・ 修正内容を聞いても、同じ説明が返ってくる

・ AIの仮説を裏づける確認が行われていない

・ 変更箇所が増えているのに、原因の範囲が狭まっていない

この状態に気づいたら、いったん止める。AIに現在調査している仮説以外の原因があり得るか聞く。

それだけでも、AIが視野を広げて、修正がうまくいくケースもあります。

この方法は、AIコーディングを始めたばかりの人でも使えます。

---

まとめ

AIコーディングで重要なのは、一度の指示で正解を出させることではありません。

・ 自分で分かっている仕様は書く

・ ソース、設定、ログ、企画メモなどの実物を渡す

・ プロトタイプを作り、小さく更新して完成を目指す

・ AIの作業結果を実際に動かし、起きた事実を返す

・ 成果物の追加だけでなく、消えたものも確認する

・ 同じ仮説で進まなくなったら一時停止して、ほかの可能性を考える

AIは、材料があれば大量のコードや資料を読み、実装し、横断して問題を探せます。

人間が担当するのは、何を確認したいのかを決め、結果を見て、現在の進め方を続けるかどうかを判断することです。

完璧なプロンプトを書くことより、このやり取りを回すことのほうが、実際の開発では重要だと感じています。

---

AIコーディングが行き詰まった方へ

この記事で紹介した「現在の仮説をいったん止める」「正常な状態と比較する」「AIへ別の可能性を考えさせる」といった判断には、開発経験が役立ちます。

ココナラでは、AIコーディング中の「動かない」「直らない」「次に何を調べればよいか分からない」という状態を、画面共有しながら一緒に整理するサービスを出品しています。

30分3,000円のビデオチャットで、現在の症状を確認し、原因の切り分け方と次にAIへ出す指示を一緒に考えます。私がコードを直接修正するサービスではなく、AIを使ってご自身で先へ進める状態を目指すものです。

30分で解決しない場合、スケジュールが空いていればその場で延長していただくこともできます。

あらかじめ+30分して60分コースでご予約することもできます。

何が分からないのか分からない状態でも構いません。内容がサービスの対象になるか不明な場合は、購入前に見積り相談またはメッセージでお問い合わせください。