AIに頼む変更の大きさを決める:一度に任せる範囲と、確認しやすい単位の目安

公式資料が共通して勧めていること

ツールごとに用語は違いますが、各社のドキュメントが述べている方向は近いものです。

GitHub Copilot のコーディングエージェント向けガイドでは、よいタスクの要素として、問題の説明、受け入れ基準、変更が必要なファイルの指示の3つを挙げています。向いている作業にはバグ修正やテスト追加、ドキュメント更新が並び、横断的な大規模リファクタリング、認証など重要度の高い変更、要件があいまいな作業は人が担当する側に分類されています(GitHub Docs: Copilotでタスクに取り組む際のベストプラクティス)。

Cursor のブログでは、エージェントのタスクを絞ること、生成中に差分を見て方向が違えば止めること、型・linter・テストのようにエージェントが正否を判断できる手がかりを用意することを勧めています(Cursor: Best practices for coding with agents)。

Claude Code のベストプラクティスも、リポジトリを読んでもわからない情報を伝えることと、実行できる確認(チェック)を渡すことを冒頭の柱にしています(Claude Code Docs: Best practices)。なお、私が内容を確認できたのはこのページの冒頭部分までです。

以降の数値の目安は、これらを踏まえた編集上の提案です。公式の基準値ではなく、実測にもとづくものでもないので、自分のチームの読む速度に合わせて調整してください。

一回の依頼に入れる条件の目安表

• 目的、一回に入れてよい目安：一文で言える。1種類の変更だけ、分割のサイン：「〜も」「ついでに」が入る
• 変更の種類、一回に入れてよい目安：機能変更、整形・改名、テスト追加のうち1つ、分割のサイン：整理と機能変更が同じ依頼に混在
• 変更ファイル数、一回に入れてよい目安：数ファイル(目安は5前後まで)、分割のサイン：UI・API・DBなど層をまたぐ
• 差分の量、一回に入れてよい目安：集中して読み切れる量(目安は数百行以下)、分割のサイン：スクロールしても全体像がつかめない
• 確認手段、一回に入れてよい目安：テスト、型、lint、手動手順のどれかが事前に決まっている、分割のサイン：「動くはず」としか言えない
• 触らない範囲、一回に入れてよい目安：公開API、設定、依存関係などを明記できる、分割のサイン：どこまで触るか自分でも決めていない
• 戻しやすさ、一回に入れてよい目安：1コミットで戻せる、分割のサイン：戻すと別の作業も巻き込む

認証・課金・データ削除のように影響が大きい領域は、小さな差分でも一回で完結させず、人が設計を決めてからAIに実装の一部を頼むほうが安全です。上のCopilotのガイドも、重要度の高い変更は人向きとしています。

依頼を分割する手順

1. 完了状態を一文で書く。 「注文一覧でキャンセル済みを非表示にできる」のように、画面や挙動で書きます。
2. 変更を4種類に仕分ける。 準備(テスト追加)、機械的な整理(改名・整形)、振る舞いの変更、後片付けです。種類が違うものは別の依頼にします。
3. 確認手段を先に作る。 既存の挙動を固定するテストが足りなければ、機能変更の前に「テストだけ追加」を一回目の依頼にします。
4. 依頼ごとに条件を書く。 対象、触らない範囲、実行する確認コマンドを入れ、「それ以外は変えず、気づいた点は報告だけ」と添えます。
5. 一回ごとに差分を読んでコミットする。 次の依頼は、確認が済んだ状態から始めます。
6. 想定を超えたら止めて切り直す。 途中で差分が目安を超えたら、続きを頼まず、そこまでの変更を捨てるか保存して、分け方を考え直します。

説明用の依頼文の例

次は説明用の架空の例で、実際に実行した結果ではありません。「注文一覧画面にキャンセル済みの非表示フィルタを付け、ついでに日付表示も統一したい」という要望を3回に分けます。

悪い例(一回にまとめた依頼)

注文一覧にキャンセル済みを隠す機能を付けて、日付の表示形式も
全画面で統一して、古いコードも整理しておいてください。

分割後の1回目(確認手段を作る)

目的:注文一覧の現在の絞り込み処理に対するテストを追加する。
対象:orders/filter.ts と、そのテストファイルのみ。
触らない:本体コードは変更しない。
確認:テストコマンドが通ること。
完了後:追加したテストの観点を箇条書きで報告し、
気づいた不具合があっても修正せず報告だけにする。

2回目(振る舞いの変更)

目的:注文一覧に「キャンセル済みを隠す」オプションを追加する。初期値は従来どおり表示。
対象:orders/filter.ts、一覧画面のコンポーネント、1回目のテストへの追記。
触らない:日付表示、API、依存パッケージ。
確認:既存テストと追加テストが通ること。
変更したファイルと理由を最初に一覧で示すこと。

3回目の日付表示の統一は、機能変更とは別の「整形」として切り離します。どの依頼も、指示と確認手段がセットになっています。

人が差分で確認すること

AIが依頼どおりに作ったかどうかは、次の点で見ます。

• 依頼にないファイルが変更されていないか
• テストが削除・スキップされたり、期待値が書き換えられたりしていないか
• 依存パッケージや設定ファイルが増減していないか
• 報告された変更理由と、実際の差分が一致しているか

GitHub のドキュメントも、エージェントの出力には脆弱性を含む誤ったコードが含まれうるため、ログは自分のレビューやテストの代わりにならないとしています(GitHub Docs: GitHub.comとGitHub MobileのCopilot)。

見る前から差分が大きいと感じるなら、その時点で分割のサインです。差分を小さく保つことが、レビューの質を保つ最も確実な方法になります。