プロンプトエンジニアリングからループエンジニアリングへ - AIコーディングの開発ループ設計

AIコーディングを始めると、最初はプロンプトの書き方を工夫します。しかし、実務で詰まりやすいのは指示文そのものではありません。

AIが「完了した」と言ったが、要件を満たしていない
テスト失敗のたびに、人間がログを貼り直している
修正を重ねるほど変更範囲が広がる
同じ失敗を繰り返し、いつ止めるべきか分からない
buildは通ったが、本当にマージしてよいか判断できない

この状態でプロンプトだけを長くしても、開発は安定しません。必要なのは、AIに一度で正解させる文章ではなく、失敗を観測し、証拠で検証し、修正するか止めるかを決める仕組みです。

この記事では、プロンプトエンジニアリングからLoop Engineeringへ重心を移し、Claude CodeやCodexを使った開発をどう進めるかを整理します。1回のrunへ渡す情報の選び方はAIエージェントのコンテキスト設計ガイド、ツール・権限・Hooksを含む実行環境はHarness Engineering入門に分け、ここでは複数の試行をどうつなぐかに絞ります。

先に結論: 強いプロンプトより、失敗できるループを作る

Loop Engineeringは、AIエージェントが目標へ近づくまで、行動、観測、検証、修正を繰り返す仕組みを設計する考え方です。IBMの解説では、prompt engineeringが1回の効果的な指示を作るのに対し、loop engineeringはAIの作業を確認し、導き、目標まで反復させるシステムを設計するものと整理されています。

ただし、「テストが通るまで無限に直して」と指示するだけではLoop Engineeringになりません。最低でも次の7要素が必要です。

要素	決めること
Goal	何を改善し、どの状態を完了とするか
State	現在地、試したこと、残課題をどこに記録するか
Action	AIが変更できるファイル、使えるツール、操作範囲
Observation	テスト結果、ログ、画面、差分をどう取得するか
Verifier	結果を何で判定するか
Decision	pass、retry、escalateをどう分けるか
Budget / Memory	反復上限と、次の試行へ残す情報をどう制限するか

プロンプトはこの中のGoalやActionを伝える部品として残ります。置き換わるのはプロンプトそのものではなく、人間が毎回プロンプトを書き直して進行管理する働き方です。

Prompt・Context・Harness・Loopの役割を分ける

4つを混ぜると、どこを直せば品質が上がるのか分からなくなります。

Engineering	設計対象	問い
Prompt	1回の指示	今回、AIへ何を依頼するか
Context	1回のrunへ渡す情報	判断に必要な仕様・コード・履歴は何か
Harness	AIが動く環境	どのツール・権限・制約・検証を使えるか
Loop	run間の状態遷移	次に進む、やり直す、止めるをどう決めるか

たとえば「認証バグを直して」という指示はPromptです。再現手順と関連設計書を渡すのはContext、テストコマンドとworktreeを使えるようにするのはHarnessです。テスト結果を読み、修正を再試行し、同じ失敗が続けば人間へ戻す流れがLoopです。

Loop Engineeringは、Claude Codeの/loop機能とも別です。/loopは開いているセッション内で同じ仕事を定期実行する機能であり、開発全体の成功条件や検証器を自動的に設計してくれるわけではありません。製品機能としての制約はClaude Code /loop完全ガイドで確認してください。

内側のagent loopと、外側のdevelopment loopを分ける

コーディングエージェント自体も、モデルとtool callを往復するagent loopを持っています。OpenAIのCodex解説では、モデルがtool callを要求し、実行結果を次の入力へ加え、最終応答を返すまで反復する内部構造が示されています。

しかし、エージェントが最終応答を返したことと、ソフトウェアが完成したことは同じではありません。

内側のagent loop
  推論 -> tool call -> tool結果 -> 推論 -> 最終応答

外側のdevelopment loop
  仕様 -> 実装run -> 独立検証 -> review -> retry / stop / merge

Loop Engineeringで設計する中心は外側です。AIの「できました」をそのまま完了条件にせず、コード、テスト結果、スクリーンショット、ログ、レビュー結果といった環境側の証拠で次の状態を決めます。

最小ループは1 task・1 worktree・1 verifierで始める

最初から複数エージェントや無人デプロイを組む必要はありません。実務で最初に作るなら、次の構成で十分です。

1つの小さなtaskを選ぶ
1つの隔離worktreeで変更する
1つの決定論的verifierを通す
最大3回だけ再試行する
最後は人間が差分を受け入れる

taskを選ぶ基準は次の3つです。

成功をコマンドや画面で確認できる
失敗してもbranchを捨てれば戻せる
1回のPRでレビューできる大きさに収まる

「新規事業を作る」「アーキテクチャを全面刷新する」のような曖昧で大きい仕事から始めると、何をもって改善したのか測れません。「空パスワードで500になる不具合を400へ直す」「特定画面のモバイル表示崩れを直す」といった狭い仕事が向いています。

ループ契約をYAML 1枚で書く

実装前に、ループの契約を人間が読める形へ落とします。特定ツールの設定ではなく、チームで合意する作業仕様です。

id: fix-empty-password-response
goal: "空パスワードのログイン要求を400で拒否し、500を返さない"

scope:
  allowed_files:
    - src/auth/**
    - tests/auth/**
  forbidden:
    - database schema change
    - dependency update
    - production access

evidence:
  reproduce: "pnpm test tests/auth/empty-password.test.ts"
  required:
    - "対象テストがfailからpassになる"
    - "既存authテストがすべてpassする"
    - "pnpm run typecheckがpassする"

decision:
  pass: "required evidenceがすべて揃い、許可外差分がない"
  retry: "原因が特定でき、同じscope内で次の仮説を試せる"
  escalate: "仕様判断、scope拡大、権限追加、同じ失敗の反復"

budget:
  max_attempts: 3
  max_changed_files: 4
  stop_on_same_failure: 2

memory:
  keep:
    - attempted_hypothesis
    - verifier_output
    - remaining_risk

重要なのは、passだけでなくretryとescalateを書くことです。AIへ自由に続行させるのではなく、どの失敗なら自動修正し、どの失敗なら人間の判断へ戻すかを先に決めます。

実際の開発を7段階で進める

1. Goalを結果で書く

「きれいに実装する」「いい感じに直す」では判定できません。ユーザーから見える結果と、機械で確認できる証拠を分けて書きます。

ユーザー結果: 空パスワードを送ると400とエラーコードが返る
機械証拠: 対象テスト、回帰テスト、typecheckがpassする
非目標: 認証方式やDB schemaは変更しない

完了条件は「AIが修正した」ではなく、「環境が期待状態になった」にします。

2. 失敗を先に再現する

修正前の失敗を記録します。バグ修正ならfailing test、UIなら変更前スクリーンショット、性能なら現在の計測値が起点です。

再現できない問題をそのままAIへ渡すと、存在しない原因へ向けてコードを変え始めます。再現できない場合は実装loopへ進まず、調査taskとして切り直します。

3. worktreeで実行を隔離する

AIの試行ごとにbranchと作業ディレクトリを分けます。これにより、失敗した試行を捨てられ、別taskの変更を混ぜず、同じ基準で差分を比較できます。

OpenAIのHarness Engineering事例でも、変更ごとにworktree上でアプリ、ログ、メトリクスを隔離し、エージェント自身が不具合再現と修正確認を行える環境を作っています。ループを長く回す前に、壊しても戻せる実行面を用意する必要があります。

4. ActorとVerifierを分ける

実装したAIに「自分の実装は正しいですか」と聞くだけでは、同じ前提のまま見落とす可能性があります。検証は次の順で独立させます。

テスト、lint、typecheck、buildなどの決定論的check
許可外ファイル、依存変更、secret混入などの差分check
別contextのreview agentによる仕様・保守性・安全性の確認
人間によるプロダクト判断とmerge判断

AIによるreviewは、人間レビューの代替ではなく、見落としを減らす追加レイヤーです。実装agentの要約ではなく、実際のdiffと検証ログをreviewerへ渡します。

5. 証拠を固定順で集める

毎回違う確認をすると、前の試行より良くなったか比較できません。verify scriptやCIに確認順を固定します。

1. targeted test
2. related regression tests
3. typecheck / lint
4. production build
5. diff scope check
6. visual or runtime smoke test

すべてのtaskで全項目を回す必要はありません。ただし、選んだ検証セットは試行中に勝手に弱めません。テストを通すためにテスト自体を書き換える必要があるなら、それは自動retryではなく仕様確認の対象です。

エージェント評価を組織的に作る場合はAIエージェント評価設計ガイドで、outcome、tool call、trajectory、回帰テストまで含むrelease gateへ広げられます。

6. pass・retry・escalateを機械的に分ける

判定は3択にします。

判定	条件	次の動作
pass	必須証拠が揃い、scope違反がない	reviewへ進む
retry	原因と次の仮説があり、同じscopeで修正できる	stateを更新して再実行
escalate	仕様不明、権限不足、scope拡大、同一失敗、環境不安定	人間へ戻す

「失敗したからもう一度」はretry条件ではありません。前回と異なる仮説、変更、追加証拠のいずれかがなければ、同じ処理を回しているだけです。

7. 失敗を次のHarness改善へ戻す

loopが止まったら、プロンプトだけを修正する前に原因を分類します。

必要な仕様が見つからない: repository documentationを直す
テストできない: verifierやfixtureを作る
画面を見られない: browser操作やscreenshot取得を追加する
操作範囲が曖昧: permissionとallowed scopeを固定する
同じ失敗を忘れる: 短いstateと失敗証拠を残す

ループの価値は、1回のtaskを完了させることだけではありません。失敗から、次のtaskでAIが迷わない環境を作ることにあります。

Stateには全文ログではなく、次の判断に必要な差分を残す

長い会話履歴をそのまま次の試行へ渡すと、古い仮説やノイズが残ります。ループのstateは短く保ちます。

attempt: 2
status: retry
current_hypothesis: "validationより前にpassword hash処理が走っている"
changed_files:
  - src/auth/login.ts
last_evidence:
  targeted_test: pass
  regression_test: fail
failure: "valid password case returns 401"
next_action: "validation順序を維持したままempty inputだけ早期returnする"

残すべきなのは、現在の仮説、実際に変えた範囲、検証結果、次の行動です。思考過程の全文や重複ログではありません。

Anthropicのエージェント設計ガイドでも、エージェントはtool結果やコード実行など環境からground truthを得て進捗を判断し、最大反復数などの停止条件を持つことが重要とされています。stateはAIの自己申告ではなく、環境から得た事実を中心にします。

停止条件を成功条件より先に決める

長時間loopで最も危険なのは、失敗ではなく「失敗しているのに動き続けること」です。次の条件では自動停止させます。

停止条件	止める理由
最大試行回数に到達	コストと差分拡大を制限する
同じ失敗が2回続く	新しい情報なしに反復している
許可外ファイルが必要	taskのscopeが誤っている
要件が矛盾している	AIでは決められないプロダクト判断がある
権限追加が必要	自動的な権限昇格を防ぐ
verifierが不安定	flakyな証拠を成功判定に使わない
secret・個人情報検知	情報境界を越える前に止める
差分が上限を超えた	review可能な大きさを維持する

停止は失敗ではありません。人間の判断が必要な状態を正しく検出した、loopの正常な結果です。

PR完了ループは「レビュー指摘ゼロ」だけを目標にしない

実装後も、PRがマージ可能になるまで反復できます。

実装
  -> local verification
  -> PR作成
  -> CI / review取得
  -> 指摘を分類
     -> 明確な不具合: 修正して再検証
     -> 仕様判断: 人間へescalate
     -> scope外改善: 別issueへ分離
  -> required checks green
  -> 人間がmerge判断

ここで「すべてのreviewerが満足するまで直す」だけにすると、相反する指摘や好みの違いで終わらなくなります。受け入れる指摘の重大度、変更予算、required check、最終決定者を先に決めます。

OpenAIの実践例では、Codexがlocal review、追加review、feedback対応を繰り返し、標準ツールから情報を取得してPRを進めています。一方で、この形を再現するには、アプリ、ログ、テスト、設計知識をagentが直接読める状態にする必要があります。チャットへログを手で貼るだけでは、loopのたびに人間がボトルネックへ戻ります。

Verifierは決定論的checkから作る

検証をすべて別のAIへ任せると、実装側と評価側が同じ誤解を共有する可能性があります。順序は、決定論的checkを先にします。

Anthropicのevals解説では、code-based、model-based、humanのgraderを組み合わせ、coding agentには安定したテスト環境とpass / failテストを使う方法が示されています。

実務では次の分担が使いやすいです。

Verifier	任せる判断
コード・スクリプト	test、type、lint、build、禁止差分、上限
review agent	仕様漏れ、設計整合、保守性、潜在リスク
人間	要件の妥当性、UX、事業判断、例外承認、merge

AI reviewerを増やす前に、成功を判定できるテストと観測手段を作る方が、ループ全体の信頼性を上げます。

Loop Engineeringが向かない仕事

すべてをloop化する必要はありません。次の仕事は、対話型のプロンプトや人間主導の設計が向いています。

成功条件をまだ言語化できない探索
複数部門の利害調整が必要な要件定義
一度の判断で大きな不可逆操作が起きる本番変更
検証環境がなく、結果を本番でしか確認できない作業
低頻度で、automation構築コストの方が高い仕事

Loop Engineeringは自律性を最大化する競争ではありません。機械が確認できる範囲だけを反復可能にし、判断が必要な場所で人間へ戻す設計です。

導入は4段階で進める

Level 1: 人間がloopを回す

人間がtaskを切り、AIへ実装させ、決めた検証コマンドを実行し、結果を次の指示へ戻します。まず反復手順が再現できるか確認します。

Level 2: verifierをscript化する

テスト、build、差分確認を1つのverify commandへまとめます。誰が実行しても同じ証拠が出る状態にします。

Level 3: stateとretryを自動化する

失敗結果を短いstateへ記録し、retry条件を満たす場合だけ次のrunを起動します。最大試行回数と同一失敗停止を必須にします。

Level 4: scoped unattended loopへ広げる

限定されたtaskだけ、worktree作成、実装、検証、Draft PRまで無人化します。本番反映、権限追加、仕様変更は人間gateに残します。

Level 1で安定しない手順を、そのままLevel 4へ上げてはいけません。自動化は品質を作るのではなく、すでにある手順を高速に繰り返します。

最初の1週間で作るもの

Loop Engineeringを始めるなら、ツール導入より先に次の5点を作ります。

小さなバグ修正taskを1件選ぶ
Goal、非目標、allowed filesを1ページに書く
failing evidenceとverify commandを用意する
pass / retry / escalateと最大3回の停止条件を決める
完了後に、足りなかったdocs・tool・testを1つだけ改善する

この1周で、人間が毎回補っている情報と判断が見えます。その部分をrepository、script、CI、skillへ移すことが、次のLoop Engineeringです。

まとめ

プロンプトエンジニアリングは、AIへ今回の仕事を伝える技術として残ります。しかしAIコーディングを実務へ広げると、品質を決める中心は一度の指示文から、反復の仕組みへ移ります。

Loop Engineeringで押さえるべき点は次の通りです。

完了はAIの自己申告ではなく、環境の証拠で判定する
1 task、1 worktree、1 verifier、最大3回から始める
Prompt、Context、Harness、Loopの責務を分ける
ActorとVerifierを分け、決定論的checkを先に置く
成功条件だけでなく、retryと停止条件を先に決める
失敗を次のdocs、test、tool、permission改善へ戻す

良いloopは、AIを止まらず働かせる仕組みではありません。正しい証拠が揃ったら進み、判断材料が足りなければ止まり、次の試行へ必要な事実だけを残す開発システムです。