はじめに
Codex、Claude Code、AntigravityなどのCoding Agentを使うと、
「この機能を実装して」
だけでも、ある程度コードを書いてくれます。
ただ、実際の開発で使っていると、
- 想定していないファイルまで変更された
- 既存仕様を壊された
- 実装自体は正しいが設計思想が違う
- テストが不足している
- 途中からAgent自身が何をしているのか分からなくなる
といったことが起きます。
自分の場合、AI Agentの性能そのものよりも、
「AIに渡すタスクの切り方」
の方が結果に大きく影響すると感じました。
この記事では、AI Agentに実装を依頼するときに、どのくらいの粒度でタスクを切ればよいのか整理します。
AI Agentへの「丸投げ」が失敗しやすい理由
例えば、こんな依頼をします。
ユーザー管理機能を追加してください。
人間からすると意味は分かります。
しかし実際には、
- DB設計
- API設計
- バリデーション
- 権限制御
- 一覧画面
- 登録画面
- 更新画面
- 削除
- エラー処理
- テスト
など、複数の判断が含まれています。
AIは判断できないわけではありません。
問題は、判断できてしまうことです。
こちらが指定していない部分をAIが補完し、
おそらくこうだろう
という推測で実装を進めます。
小規模な個人開発なら便利ですが、既存システムでは、この「善意の補完」が事故につながります。
タスクは「1つの目的」で切る
自分が使いやすいと感じている基準は、
1タスク = 1つの確認可能な目的
です。
例えば、
ユーザー管理機能を実装する
ではなく、
1. 既存のユーザー管理周辺の実装を調査する
2. DB変更案を提示する
3. User APIを追加する
4. 登録時のバリデーションを追加する
5. 一覧画面を追加する
6. 単体テストを追加する
7. 既存機能への影響を確認する
という単位に分けます。
重要なのは、
調査と実装を分けること
です。
いきなりコードを書かせない
大きめの変更では、まず次のように依頼します。
まだコードは変更しないでください。
ユーザー管理機能を追加したいです。
まず既存コードを調査し、以下を整理してください。
- 関連ファイル
- 現在のデータフロー
- 使用している共通処理
- DBへの影響
- 変更が必要になりそうな箇所
- 既存機能への影響
- 実装手順
不明な仕様については推測で実装せず、
「確認が必要な点」として整理してください。
この段階では実装させません。
先にAIがシステムをどう理解したのか確認します。
自分が使っているタスク分割
大きめの改修なら、だいたい次の順番にしています。
① 調査
↓
② 影響範囲整理
↓
③ 実装方針
↓
④ 実装
↓
⑤ テスト
↓
⑥ セルフレビュー
それぞれ別タスクにします。
① 調査
今回の変更に関係する既存実装を調査してください。
確認してほしい内容：
- 関連クラス
- 関連API
- DBテーブル
- 共通部品
- 類似機能
- テストコード
この段階ではコードを変更しないでください。
② 影響範囲整理
先ほどの調査結果をもとに、
今回の変更による影響範囲を整理してください。
以下に分類してください。
- 必ず変更する箇所
- 変更する可能性がある箇所
- 影響確認のみ必要な箇所
- 影響なしと判断した箇所
それぞれ理由も記載してください。
「影響なし」も出させるのがポイントです。
AIがどこまで考慮したか確認できます。
③ 実装方針
まだ実装は行わず、
実装方針だけ提示してください。
以下を含めてください。
- 変更対象ファイル
- 変更内容
- 新規作成ファイル
- 既存ロジックを流用する箇所
- テスト方針
- リスク
ここで人間がレビューします。
④ 実装
方針に問題がなければ、ようやく実装させます。
提示した実装方針に沿って実装してください。
制約：
- 対象外ファイルは変更しない
- 既存の命名規則に合わせる
- 既存の共通処理がある場合は再利用する
- 不要なリファクタリングは行わない
- 仕様が不明な場合は勝手に補完しない
この、
不要なリファクタリングは行わない
はかなり重要です。
AIは良かれと思って周辺コードまできれいにしてくれることがあります。
レビュー差分が大きくなり、逆に確認しづらくなります。
「やること」より「やらないこと」を書く
AIへの依頼では、
○○してください
だけではなく、
○○しないでください
も重要です。
例えば、
今回のタスクでは以下を行わないでください。
- DB定義の変更
- 共通クラスのリファクタリング
- 関係のない警告修正
- UIデザインの変更
- ライブラリ追加
と書きます。
これだけで差分がかなり安定します。
完了条件を定義する
AI Agentにとって一番困るのは、
「どこまでやれば完成なのか分からないタスク」
です。
そのため、完了条件を明示します。
完了条件：
- 登録が正常に行える
- 必須項目未入力時にエラーになる
- 重複データを登録できない
- 既存の更新処理に影響がない
- 追加したテストがすべて成功する
- 既存テストがすべて成功する
これだけで、AIが自分で確認できる範囲が増えます。
GitHub Issueを書くつもりで依頼する
個人的に一番分かりやすい考え方は、
AIへのプロンプト = GitHub Issue
です。
例えば、
## 目的
商品登録APIに商品コードの重複チェックを追加する。
## 対象
backend/products/service.py
backend/products/tests/test_service.py
## 現状
同一の商品コードを複数登録できてしまう。
## 期待する動作
既に同じ商品コードが存在する場合、
ValidationErrorを返す。
## 参考
ユーザー登録時のメールアドレス重複チェックと
同じ実装方針にする。
## 制約
DBスキーマは変更しない。
APIレスポンス形式は変更しない。
## 完了条件
- 重複登録時のテストを追加
- 正常登録の既存テストが成功
- 全テスト成功
このレベルまで書けば、かなり安定します。
タスクを細かくしすぎるのもよくない
逆に、
変数を追加してください
↓
if文を書いてください
↓
メソッドを呼び出してください
まで細かくすると、人間がコードを書いた方が早くなります。
自分の基準は、
人間なら30分〜1時間程度で終わりそうな、目的が1つの作業
から始めることです。
もちろんモデル性能やコードベースによって最適なサイズは変わります。
AI Agent用タスクテンプレート
最終的には、以下のテンプレートをよく使います。
# 目的
何を実現したいのかを書く。
# 背景
なぜ変更するのかを書く。
# 対象
変更対象の機能・ファイル・画面などを書く。
# 現在の動作
現在どうなっているかを書く。
# 期待する動作
変更後にどうなってほしいかを書く。
# 制約
- 変更してはいけない箇所
- 使用する既存処理
- DB変更可否
- ライブラリ追加可否
# 実施内容
1. 関連コード調査
2. 影響範囲整理
3. 実装
4. テスト追加
5. 既存テスト実行
# 完了条件
- ○○できる
- ○○の場合エラーになる
- 既存テストが成功する
# 注意
仕様が不明な場合は推測で実装せず、
確認事項として報告してください。
まとめ
AI Agentを使っていて感じるのは、
AIの性能が高くなるほど「何を任せるか」の設計が重要になる
ということです。
自分の場合は、
丸投げ
↓
調査
↓
方針
↓
実装
↓
テスト
↓
レビュー
と分解した方が安定しました。
特に重要なのは、
- 1タスク1目的
- 調査と実装を分ける
- やらないことを書く
- 完了条件を書く
- 不明点を勝手に補完させない
の5点です。
AI Agentに長いプロンプトを書くことが目的ではありません。
「何をもってこの仕事が完了なのか」をAIと共有すること
が、タスク設計で一番重要だと思っています。
参考資料
-
OpenAI「How OpenAI uses Codex」
https://openai.com/business/guides-and-resources/how-openai-uses-codex/ -
OpenAI「Prompt engineering」
https://developers.openai.com/api/docs/guides/prompt-engineering