AI Coding Workflow：AIがコードを何度も修正する問題をどう減らすか？

Plan → Scoped Edit → Verify / Cursor Rules / 小さな diff / 受け入れチェックリスト / デッドループ対処

Cursor、Claude Code、Copilot Workspace で機能を書いていると、こんな夜を経験したことはないでしょうか。AI が A ファイルを直したらテストが落ちる。B を直したら A が壊れる。「もう一度やって」と言うと、昨日まで動いていたコードまで消えてしまう。これはモデルが「賢くない」からではなく、再現可能な AI Coding Workflow がないからです。「計画・変更範囲・検証」を独立した段階に分けていないと、Agent は同じ誤った仮説の上で無限にループします。

本記事では、2026年のチーム現場で実証済みのフローを紹介します：まず Plan してから手を動かし、各ラウンドは小さな範囲だけを変え、Verify を通過してから次へ進む。Cursor Rules と Git の小さなコミットを組み合わせると、「同じバグを8ラウンド直す」状況を2ラウンド以内に圧縮できます。クラウド Mac 上の MCP Server を構築中の方や、GitHub AI Agent オープンソースプロジェクト を選定中の方にも、このワークフローはそのまま使えます。

なぜ AI は「修正しきれない」ループに陥るのか？

Agent モードの本質は、不確実な環境で試行錯誤することです。「ログインのバグを直して」とだけ言うと、OAuth コールバックなのか、セッション期限切れなのか、フロントのルーティングなのか——モデルは判断できません。最もそれらしい答えを推測して修正し、テストを走らせ、失敗したら別の方向を試します。各ラウンドで前ラウンドの仮説の一部が覆されるため、diff はどんどん大きくなり、コンテキストには矛盾する変更履歴が積み重なり、最終的に「直せば直すほど混乱する」状態に陥ります。

3つの根本原因

• 目標が曖昧——「成功の姿」が書かれていないため、AI はテストエラーを手がかりに逆算するしかない。エラーは症状を示すことが多く、根本原因を指し示すとは限らない
• 範囲が制御不能——1タスクで10ファイル以上をまたぐ。認証を直しながら utils をリファクタし、新たなリグレッションを生む
• 受け入れゲートがない——「通過してから次へ」という硬いルールがなく、失敗時のデフォルトが「もう一版生成」であり、「ロールバックして範囲を再定義」ではない

経験則：3ラウンド連続で「違う、もう一度直して」と言っているなら、問題はモデルではなくタスクが再 Plan されていないことにあります。

3段階ワークフロー：Plan → Scoped Edit → Verify

AI との協働を3つのスキップ不可な段階に分けることは、より強いモデルに乗り換えるより効果的です：

1. Plan（計画）——Plan モードか対話のみで、変更するファイル・触らないもの・受け入れコマンド（例：npm test -- auth）を列挙。コピペ可能な「タスク仕様」を出力し、Agent にすぐ手を動かさせない 仕様を確認してから進む
2. Scoped Edit（範囲限定の変更）——「src/auth/login.ts だけ変更、他ファイルは禁止」と明記。各ラウンドの目標：1〜3ファイル、純変更200行未満
3. Verify（検証）——テスト、lint、手動スモークテストを実行。通過 → コミットして次タスクへ。失敗 → 完全なエラーログを持って Plan に戻る。「もう一度やって」ではない

プロンプト構造：目標・境界・受け入れ基準を一度に伝える

コピペ可能なテンプレート（括弧内を自分のプロジェクトに置き換え）：

## 目標
（一文：ログイン後3秒以内にダッシュボードへ遷移）

## 範囲
- 変更可：src/auth/login.ts, src/auth/session.ts
- 変更禁止：ルーティング、スタイル、その他モジュール

## 受け入れ基準
- npm test -- --grep "login"
- 手動：誤パスワードで「アカウントまたはパスワードが違います」と表示。ユーザー存在の有無を漏らさない

## コンテキスト
- 現在のエラー：（完全な stack trace を貼り付け）
- 関連ルール：Session は Redis 保存、docs/auth.md 参照

この構造は、Anthropic の Claude Code ベストプラクティスが強調する「明確な境界」と一致します。モデルが意図を推測する必要がなく、リグレッション面も制御しやすくなります。

Rules / Skills：プロジェクト制約をリポジトリに書き込む

毎回の会話で「pnpm を使う、class コンポーネントは使わない、テストは __tests__ に置く」と繰り返すと、トークンを浪費し、AI も時々守り、時々忘れます。約束ごとを .cursor/rules やプロジェクトの AGENTS.md に書き込みましょう：

Rules（ルール）

永続的な制約：命名スタイル、禁止パターン、コミット前に走らせるコマンド。Cursor は Agent 呼び出しのたびに自動注入します。

Skills（スキル）

再利用可能なタスク台本。例：「新 API エンドポイント追加」のステップチェックリスト。AI が毎回プロジェクト構造をゼロから探る手間を減らします。

User Rules vs Project Rules

個人の好み（「日本語で返答」など）は User に。チームの合意（「明示的な指示がない限り backend は触らない」など）は Project に。協業時の認識ズレを防ぎます。

Cursor Skills ドキュメントを参考に、高頻度フローを固定化すると、同種のエラーを何度も直す回数が明らかに減ります。

小さな diff と Git 規律

AI は一気に大きなコードブロックを生成するのが得意ですが、人間が大きな diff をレビューする能力には限界があります。推奨事項：

• 各 Agent タスクを1コミットに対応させる——メッセージに「Plan 要約」を書き、git revert しやすくする
• 混乱したら reset——大きな diff にパッチを重ねない。git checkout -- . でグリーンテスト地点に戻り、より小さな範囲でタスクを再開
• ブランチで実験——クラウド Mac や CI 環境で Agent を試すときは、git worktree や独立ブランチで「AI の暴走」を隔離

コンテキスト管理：Agent をファイルの海に溺れさせない

monorepo 全体を Agent に渡すのは、ノイズの中からシグナルを探させるのと同じです。より効果的な方法：

1. @filename で関連ファイル3〜5個を正確に参照。「プロジェクト全体をスキャン」は避ける
2. 大きなリファクタは複数の Plan に分割：まずインターフェース、次に実装、最後にテスト。各ステップで Verify
3. 会話が15ラウンドを超えたら、新しい会話を開き「タスク仕様 + 現在の状態」を貼り付ける。履歴の重荷を抱えたまま直すよりクリーン

4つの典型的デッドループと打開策

Agent で複雑なパイプライン（バッチ文書処理や MCP ツールチェーンなど）を組んでいるなら、「ルーティング → 実行 → 検証」のレイヤー分けは、PDF 一括認識パイプラインで説明した分流アーキテクチャと同じパターンです：まず判断してから手を動かし、すべてのタスクを最も遅く、最もエラーが出やすい経路に通さない。

よくある質問

1. モデルが強いほど反復は減る？——強いモデルは「構文レベル」のエラーを減らしますが、範囲の制御不能によるリグレッションはモデルグレードと無関係。Workflow が主因です
2. チームでどう統一する？——Rules、PR テンプレート、受け入れチェックリストをリポジトリに置く。Code Review で「小さなコミットか」を確認
3. Agent に全部任せられる？——実行の自動化は可能ですが、Plan と Verify は特に決済・認証・データ移行では人手のゲートを推奨
4. TDD とどう組み合わせる？——まず AI に失敗テストを書かせる（Plan）、次に実装（Scoped Edit）、グリーンになったらリファクタ——3段階と自然に噛み合います

タイトルに戻ると：AI の反復修正を減らすのは「何度も試す」ことではなく、Plan → Scoped Edit → Verify の規律、明確なプロンプト、リポジトリ内の Rules、そして git revert する勇気にかかっています。フローを固定すれば、時間は「第 N 回のパッチ」ではなく「問題の定義」に使えるようになります。