AIに丸投げしない“設計ドリブンAIコーディング”を導入してみた話
AIコーディング、今アツいですよね。
Cursor Composer、ClineやWindsurfなどのAIコーディングが日夜タイムラインを賑わせています。
確かに試してみるとライブラリのインストールまでしてくれてすごい時代が来たな…と驚きます。
しかし、いざ本格的な機能を実装しようとするとエラーのループや不要ファイル量産など手戻りが目立ったため、実践するのは保留していました。
今回、Skylar Payneさんの「How to stop saying 'Fuck you Cursor'」を参考にした“構造化されたワークフロー”を取り入れ実践してみたところ、意外なほどスムーズにAIをコントロールできるようになりました。
この記事ではその流れを解説します。
なぜ“設計ドリブン”が必要なのか？
業務で使う機能をAIに丸投げすると、以下の問題が起こりがちです。
- AIのコンテキストオーバー
一度に膨大なファイルを扱いきれず、トンチンカンな変更が混在する。 - 意図しないファイル増殖
AIが「たぶん必要」と勝手に判断したファイルをどんどん生成してしまう。 - 実装漏れ
“思い込み”で外せない箇所をAIが見落とし、人間が後追いで気づく。
こうした“勝手な拡張”や“漏れ”を防ぐためにも、最初の設計段階で「どのような変更を行うか」と「どのファイルをどう変えるか」を明確にし、その上で実装を小さくフェーズ分割するのが効果的なのです。
ワークフロー概要
ざっくりいうと、
- 人間同士で仕様を固める
- AIと“どのファイルをどう変えるか”を話し合い、設計ドキュメントを作る
- フェーズ別に実装を依頼し、レビュー
- 完了
という流れです。
ワークフロー解説
ここでは、「Userモデルにbioカラムを追加し、フロント側で表示・編集できるようにする」という例を使って実際のワークフローについて解説します。
👉 1. 要件概要を作成
この段階ではAIは挟まずに、タスクの概要をまとめます。
詳細に書く必要はありませんが、漏れなく変更点と目的を書き出します。
概要例
ユーザーのデータにbioを追加し、プロフィールページで表示したい。
また、編集機能も同時に実装したい。
👉 2. 設計ドキュメント作成
この段階では人間の変更要望に従ってAIが作成した設計ドキュメントについて人間がフィードバックを行いながら完成を目指していきます。
以下のようなステップを踏んで完成させていきます。
Step 1. 変更の方針を決定する
要件概要をAIに伝えて、AIの作成する設計ドキュメントにフィードバックを加えながら変更の方針を決定します。
プロンプト例：
ユーザーのデータにbioを追加し、プロフィールページで表示したい。
また、編集機能も同時に実装したい。
---
あなたは設計について議論し、設計ドキュメントを完成させてください。完成するまで実装はしないでください。
このように指示を出しておくと、AIは実装に取り掛からずに設計ドキュメントを作成し始めます。
なお、この時点で変更対象のファイルをコンテキストに含めておくとAIが書き出す設計の精度が上がりますし次の関連ファイルの洗い出しなどがスムーズです。
Step 2. 関連ファイルの洗い出し
自分でコンテキストとして関連ファイルを追加してもいいですし、AIにプロジェクトを探ってもらって関連ファイルを追加してもらってもいいです。
ここでしっかり関連ファイルを洗い出しておくことで実装における手戻りが格段に減ります。
ファイル例：
prisma/schema.prisma
src/components/users/UserProfileCard.tsx
src/components/users/UserProfileEditForm.tsx
services/users/UserServices.ts
Step 3. フェーズ分割
開発フェーズを分割するようにAIにお願いし、適切な粒度になるようにAIにフィードバックしながら調整します。
分割例：
* フェーズ1: DBまわり（マイグレーションファイル＋Userモデルの修正）
* フェーズ2: 編集機能の改修
* フェーズ3: 編集画面の改修
* フェーズ4: フロントUI（表示画面の反映）
* フェーズ5: テスト、スタイリング調整など
Step 4. 完成したドキュメントをファイルに書き起こし
設計ドキュメントが完成したらファイルに保存しておいてください。
新しいチャットを始めてもAIが設計ドキュメントを参照できますし、後々変更を振り返る時に役に立ちます。
👉 3. AIに実装を依頼
設計ドキュメントが完成したら、いよいよAIに実装を委ねます。
ここでは、たとえば 「設計ドキュメントに従ってフェーズ1を実装してください」 とだけシンプルに指示します。
- 注意: ファイル化した設計ドキュメントをコンテキストに含めることを忘れないようにしましょう。
- 変更の詳細はドキュメントに既に書いてあるので、AIはそれを参照して実装を進められます。
プロンプト例：
設計ドキュメントに従ってフェーズ1を実装してください。
👉 4. 人間がレビュー＆修正
AIが生成したコードが設計ドキュメントどおりになっているか、指定外のファイルが変更されていないかをチェック。もし想定外の修正が混ざっていれば再度AIに修正を依頼したり、必要に応じて自分で手を加えるだけで済みます。
- 都度フェーズを分割しているので、変更範囲が小さいためレビューしやすい。
- 不要な手戻りやトラブルを最小限に抑えられます。
- 今のところ、スタイリングについては人間の手で行ってしまうのが早いかもしれません。
👉 5. Rules for AIを改善する
ワークフローを実践していると、AIエージェントが想定外の挙動をしたり、こちらの意図とずれた実装をしてしまうことがあります。そんなときは、AIエージェントの振る舞いを定義する“Rules”に改善策を追記していくのがおすすめです。ルールを明示的に積み重ねることで、次回以降のやりとりでより正確なアウトプットが得られやすくなり、手戻りの回数も減っていきます。
ルール例：
- コーディングルールはドキュメントには記載しないこと
- 変更や参照が必要なファイルはドキュメントに明記すること
- ドキュメントをファイルに起こす時は、 `touch "docs/features/$(date +%Y%m%d_%H%M%S)_{snake_case_document_name}.md"` で作成すること
- ドキュメントをファイルに書き起こす場合は必ずマークダウン形式にすること
よくあるトラブルと解決策
-
実装漏れ
- 対策: 設計段階でAIに「ファイルはこれで全部？」と聞く。洗い出した内容を必ずドキュメントに落とし込む。
-
ファイルの勝手な増殖
- 対策: 「どのファイルをどう変えるか」を設計ドキュメントにしっかり書き、AIにも「ここ以外は触らないで」と念押しする。
-
レビューが大変
- 対策: 1フェーズに絞ってコード生成させる。差分が小さければレビューも楽。AIに「変更箇所をリストアップして」と頼むとさらにスムーズ。
まとめ：設計ドキュメントの明確化 + フェーズ分割で“無駄な混乱”を防ぐ
- 「どのような変更を行うか」と「どのファイルをどう変えるか」を明示
- 実装はフェーズに小分割し、都度ドキュメントをコンテキストに含めてAIに指示
- 完了後に人間がレビューし、必要があれば再修正
これらを徹底すれば、AIにありがちな勝手な拡張や実装漏れ、ファイル増殖といったトラブルをグッと減らせます。私自身、このアプローチに切り替えたら「AIが素直に動いてくれて、かつレビューもしやすい！」と感じることが増えました。
参考: How to stop saying 'Fuck you Cursor'
「問題定義→設計文書作成→段階的実装→テスト」という4ステップの構造化されたワークフローを提唱。AIペアプログラミングエディタ「Cursor」を使いこなすコツとして紹介されています。
あとがき
AIエージェントを活用していると、「思い通りにならない」「こんなはずじゃなかったのに…」と感じる場面が少なくありません。しかし、それはAIが“間違って”いるわけではなく、私たち自身がどれだけ正確に“何をしてほしいか”を伝えられているかにかかっているのだと痛感させられます。
今回ご紹介したワークフローのポイントは、「やみくもに頼むのではなく、明確に何をどう変えるかを設計してから、段階的に実装を依頼する」 という一点に尽きます。適切に状況を整理し、AIがすべき作業範囲を明確に定義してあげれば、無駄な混乱や二度手間をかなり減らすことができます。
私自身も半信半疑で試した当初、最初の設計段階に手間を割くのは「面倒だな…」と思っていました。しかし、いざフェーズごとにAIに実装させてみると、驚くほど素直に成果物があがってきて、レビューも手戻りも最小限になり、“AIに振り回される”場面がグッと減りました。
AIエージェントはまだまだ“完璧”とは言いがたい存在ですが、使い方ひとつで生産性の向上に大きく貢献してくれます。この記事が皆さんのプロジェクトの助けになってより円滑に進むことを願っています。
補足
筆者は今のところ o3-mini を制限なく使える Cursor Composerを使用していますがこのワークフローはClineなどの他のAIエージェントでも実践できると思います。
Discussion