コーディングエージェントにプロンプトを出すのはもうやめるべきです。エージェントにプロンプトを出すループを設計すべきです。これは捨て台詞のように聞こえるかもしれませんが、現在の優れたエンジニアがAIとどのように連携するかにおける、最も大きな変化を指し示しています。AIコーディングエージェントから真のレバレッジを得ている人々は、エージェントをチャットパートナーとして扱うことをやめました。彼らはエージェントを、自身が構築したループ内のワーカーとして扱っています。
button
TL;DR
コーディングエージェントループとは、エージェントを繰り返し実行する制御構造のことです。変更を生成し、実行し、厳格なシグナルと照合して結果をチェックし、失敗をフィードバックし、チェックが合格するか、制限に達するまで繰り返します。難しいのはエージェントではありません。検証ゲートです。「問題なさそう、もう一度試して」という曖昧なゲートを持つループは、迷走し、「完了」を幻覚します。決定的ゲート（失敗するテスト、スキーマの不一致、契約違反）を持つループは収束します。APIおよびバックエンドの作業では、自動テストスイートと契約チェックがそのゲートとなり、これがAPIテストがエージェントワークフローの中心にあり、最後に付け足すものではない理由です。
プロンプトからループ設計へ
ほとんどの人は、チャットボックスを通じてAIコーディングに出会います。リクエストを入力し、回答を読み、うまくいったものをコピーし、再度入力します。それがプロンプトです。これは、単一の関数や簡単な説明には問題ありません。しかし、タスクが正しくなるまでに複数のフィードバックラウンドを要するような場面では、ほとんどの実際の作業と同様に、破綻してしまいます。
手動でプロンプトを出すことの問題点はここにあります。あなたがループなのです。あなたが結果を読み、バグを見つけ、次に何を言うべきかを決め、エラーを貼り付けます。すべてのイテレーションは人間を待つことになります。エージェントは数秒でコードを生成できますが、あなたがコンテキストを切り替え、スクロールし、入力している間、数分間アイドル状態になります。あなたは高速なシステムの遅い部分になってしまうのです。
ループを設計することで、その状況は逆転します。出力を見て次のプロンプトを決定する存在である代わりに、それを自動的に行うハーネスを構築します。エージェントがコードを記述します。スクリプトがそれを実行します。結果がキャプチャされます。もし失敗した場合、その失敗は次のプロンプトとして直接エージェントにフィードバックされます。内部ループに人間はいません。あなたは、タスクを設定し、結果を承認し、うまくいかない場合に実行を停止する、という端の部分でのみ介入します。Anthropic自身の効果的なエージェントの構築に関する記事でも、異なる言葉で同じ点を指摘しています。勝利は、より賢い単一のプロンプトからではなく、モデルの周りに構築する環境からもたらされるのです。
このメンタルモデルの転換は小さいですが、完全に異なります。「エージェントに何を伝えるべきか？」と尋ねるのをやめましょう。「エージェント自身に何を伝えさせるループを設計すべきか？」と尋ね始めるのです。
コーディングエージェントループとは具体的に何か
誇張を取り除けば、コーディングエージェントループには5つの部分があります。1つでも欠けていると、ループは決して終了しないか、間違って終了します。
- タスク仕様。完了がどのような状態であるかを明確に記述したものです。「動かせ」ではなく、「POST /orders エンドポイントは作成された注文とともに201を返し、スキーマに対してボディを検証し、不足しているフィールドを422で拒否する」といった具合です。
- エージェント。モデルとそのツール（ファイルの読み書き、シェルコマンドの実行など）です。これは誰もが注目し、あなたが最も制御できない部分です。
- アクションステップ。エージェントが変更を加え、何かが実際にそれを実行します。テスト、ビルド、型チェック、ライブエンドポイントに対するリクエストなどです。
- 検証ゲート。具体的な理由を付けて合格または不合格を返す決定論的なチェックです。これがステアリングホイールです。この投稿のほとんどをここで費やします。
- 終了条件。ループはいつ停止するのか？ゲートが合格した場合、最大反復回数に達した場合、またはコスト予算を超過した場合です。出口のないループは暴走であり、ワークフローではありません。
擬似コードでは、このパターン全体が数行に収まります。
task = load_spec("orders-endpoint.md")
for attempt in range(MAX_ITERATIONS):
agent.run(task, feedback=last_result) # 生成
result = run_verification() # 実行 + ゲートのチェック
if result.passed:
break # 終了: 成功
last_result = result.failures # 失敗をフィードバック
else:
escalate_to_human(last_result) # 終了: 諦め
このループがアイデアの全てです。エージェントが生成し、ゲートが判断し、失敗が次のプロンプトとなり、合格するか試行回数が尽きるまで全体が実行されます。「Ralph」テクニックとしてオンラインで共有されているバリアントは、`MAX_ITERATIONS` を高く設定し、仕様を厳密に記述したものです。当社のエージェントハーネスアーキテクチャの分析を読まれた方なら、これがその最小限で誠実な形のハーネスであることがわかるでしょう。
ワンショットプロンプトが限界に達する理由
単一のプロンプトは、モデルが初回で正しく理解するか、あるいはあなたがモデルが間違った点を捉えることを前提としています。どちらの仮定も大規模では破綻します。
モデルはもっともらしいコードを生成することには長けていますが、そのコードが正しいかどうかを知ることには弱いです。見た目は正しく、コンパイルも通り、しかしエッジケースでひっそりと間違ったステータスコードを返すエンドポイントを作成することがあります。チャットでは、本番環境になるまで気づかないかもしれません。モデルにはエッジケースが壊れていることを伝えるフィードバックがないため、自信を持って成功を報告します。「できたように見える」と「実際にできている」との間のそのギャップこそ、ループがその真価を発揮するところなのです。
ループは、モデル自身の作業に対する意見を受け入れないことでギャップを埋めます。エージェントは完了したと言うことはできません。ゲートがそう言うのです。テストを実行し、もし赤であれば、タスクは完了していません。そして、その赤色の出力がエージェントが次に読むものとなります。モデルの自信はもはや問題ではありません。シグナルだけが重要です。
生産性の観点もあります。手動プロンプトは、あなたが積極的に監視している1つのエージェントの処理能力を制限します。ループを使用すると、複数のエージェントを同時に実行できます。それぞれが独自のゲートに対して独自のタスクに取り組むため、内部サイクルであなたを必要としません。これは、動的で並行的なエージェントワークフローに関する当社の記事が触れている飛躍です。一度ループが自動化されれば、入力速度を上げるのではなく、ループを追加することでスケールするのです。
誰もが過小評価している部分：検証ゲート
これが不都合な真実です。ほとんどのエージェントワークフローの失敗は、モデルが弱すぎたからではありません。フィードバックシグナルが甘すぎたからです。
ゲートが何をするか考えてみてください。イテレーションごとに、エージェントに2つのことのどちらかを伝えます。合格、停止。または不合格、その理由はここにある。この「その理由はここにある」の質が、次のイテレーションが改善するか、それとも迷走するかを決定します。エージェントに42行目を指す正確なスタックトレースと、爆発したアサーションをフィードバックすれば、適切な部分を修正します。「何かがおかしいようです、レビューしてください」とフィードバックすれば、エージェントは推測し、しばしばより自信を持って聞こえながらコードを悪化させます。
決定論的なゲートは収束します。曖昧なゲートは迷走します。それがゲームの全てです。
良いゲートとは何か？
- バイナリで再現性があること。同じ入力に対して、常に同じ判定が下されること。「モデルの気分次第」ではないこと。
- 理由を明確にして大きく失敗すること。テスト名、期待値と実際の差分、行番号、エラーコードなど。その理由が次のプロンプトとなるため、具体的である必要があります。
- エージェントが密かに編集できないこと。エージェントがテストを変更してパスできるようにするなら、そのゲートは単なる茶番です。ゲートを保護してください。それをエージェントが所有するコードとしてではなく、仕様として扱ってください。
- ループに耐えうるほど高速に実行できること。20分かかるゲートは反復速度を制限します。緊密なループには高速なチェックが必要です。
優れたゲートは、すでにすべての成熟したコードベースに存在します。ユニットテスト、型チェッカー、リンター、コンパイラ、スキーマバリデーター、契約テスト。これらは決定論的なオラクルです。これらは人間に「これは間違っていて、その理由はここにある」と伝えるために作られており、それはエージェントループが必要とするシグナルそのものです。あなたはゲートを発明する必要はありません。すでに信頼しているゲートにループを向け、カバレッジが薄いところに新しいゲートを記述するだけです。もしそのレイヤーを体系化したことがないなら、自動テストとは何かに関する私たちのガイドが、それをループに組み込む前の良い基礎となるでしょう。
APIおよびバックエンドの作業では、テストスイートがループです
これは、抽象的なアイデアがサービスを構築するすべての人にとって具体的になる部分です。エージェントがAPIエンドポイントを記述するとき、それが機能していると判断する根拠となる真実とは何でしょうか？モデルの要約ではありません。テスト対象のエンドポイントの実際の動作です。正しいステータスコード、スキーマに一致するレスポンスボディ、認証の強制、不正な入力の拒否、契約の順守です。
これらすべては、決定論的な結果をもって自動的にチェック可能です。これは、あなたのAPIテストスイートが、エージェントループが必要とする検証ゲートとまったく同じ形になっていることを意味します。あなたは常にゲートを構築していたのです。ただ、それをテストと呼んでいたに過ぎません。
エンドポイント作業の具体的なループは次のようになります。
- エージェントがタスク仕様とOpenAPI定義を読み取り、エンドポイントを記述または編集します。
- ハーネスが実行中のサービスに対してAPIテストスイートを実行します。ステータスアサーション、すべてのレスポンスに対するJSONスキーマ検証、仕様に対する契約チェックです。
- 失敗は構造化されて返されます。「`customer_id` がない場合に422が期待されたが、500が返された。」「レスポンスフィールド `total` は文字列だが、スキーマでは数値になっている。」「仕様内のエンドポイント `/orders/{id}` に実装がない。」
- その構造化された失敗がエージェントの次のプロンプトになります。エージェントは特定のギャップを修正します。
- スイートがグリーンになるまで繰り返し、その後、レビューのために人間に引き渡します。
重要なのは、ステップ3のフィードバックが漠然としたものではなく、正確で機械生成されたものであることです。これにより、ループが迷走する代わりに収束し続けます。スキーマファーストと契約テストは、OpenAPI仕様がエージェントとゲートの両方が読み取る共有の真実の源となるため、これまで以上に重要になります。コードと仕様の間の乖離は、もはやゆっくりとしたドキュメントの問題ではなく、即座に赤いゲートとなります。
これは、Apidogがエージェントワークフローで果たす役割です。デザイン、スキーマ、モックサーバー、および自動テストがすべて1箇所に集約されたオールインワンAPIプラットフォームであり、これによりゲートと仕様がデフォルトで同期した状態を保ちます。ループをApidogテストシナリオに向けると、エージェントは各イテレーションでスキーマ検証済みの合格/不合格を取得し、モックサーバーはまだ構築されていない依存関係の代わりとなるため、エージェントは安定したターゲットに対して作業できます。すでにこのパターンを実行しているチームは、Apidog AIエージェントデバッガーのようなものを介してエージェントのツールアクセスを接続し、エージェントが人間のテスターと同じようにエンドポイントを叩いて検査できるようにしています。テストランナーを手作業で作成するのではなく、視覚的にゲートを構築したい場合は、Apidogをダウンロードしてください。
今日から最小限の自己修正APIループを構築する
始めるのにフレームワークは必要ありません。必要なのは仕様、テストコマンド、そしていくつかの接続コードだけです。これが、実際に機能する最小限のバージョンです。
ステップ1：ゲートの意図として仕様を記述する。契約をOpenAPIファイルに、動作をテストケースに記述します。エージェントは両方を読み取ります。これはドキュメントとしても機能するため、無駄な作業ではありません。
ステップ2：失敗時にゼロ以外の終了コードを返すテストコマンドを選択する。終了コードが正直である限り、何でも機能します。pytestスイート、Newmanの実行、Apidog CLIテストシナリオなど。ループは、合格/不合格とキャプチャされた出力のみに関心があります。
# ゲート、単一コマンドとして
apidog run ./tests/orders-suite --reporter json > result.json
ステップ3：ループを接続する。エージェントを実行し、ゲートを実行し、結果に応じて分岐します。
MAX_ITERATIONS = 8
feedback = None
for attempt in range(MAX_ITERATIONS):
run_agent(task="implement orders API per spec", feedback=feedback)
gate = subprocess.run(["apidog", "run", "./tests/orders-suite",
"--reporter", "json"], capture_output=True)
if gate.returncode == 0:
print(f"green on attempt {attempt + 1}")
break
feedback = parse_failures(gate.stdout) # 次のプロンプトが自動で記述される
else:
print("8 attempts, still red; escalating to a human")
ステップ4：ゲートを保護する。テストファイルと仕様を、エージェントが編集を許可されているファイルセットから除外します。もしエージェントがテストを書き換えてパスできるようにするなら、あなたは進捗を偽装するための機械を作ったことになります。
ステップ5：コストを制限する。イテレーション回数を制限します。使用量を制限します。すべての試行をログに記録して、ループが収束しているか、それとも空転しているかを確認できるようにします。トークン使用量に注意している場合、エージェントのトークンコストを削減する方法に関する当社のメモが直接適用されます。なぜなら、収束しないループは予算をあっという間に使い果たすからです。
これが機能する自己修正ループです。エージェントが記述し、スイートが判断し、失敗が方向を定め、あなたは自信に満ちた嘘ではなく、成功したエンドポイントまたは明確なエスカレーションを得られます。
良いループを設計する：陥りやすい間違い
うまく機能するループと、気づかないうちにコストを浪費するループを分けるいくつかのパターンがあります。
- エージェント自身に宿題を採点させる。唯一のチェックが「エージェント、終わった？」である場合、ループはなく、余分な手順のあるチャットボットがあるだけです。ゲートはエージェントの外部になければなりません。
- ゲートが粗すぎる。3つの浅いテストで「テストがパスした」というのは、エージェントが3つのテストを満たし、カバーされていない部分にバグを残すことを意味します。ループの品質はゲートのカバレッジによって上限が設定されます。薄いテストは薄い結果をもたらします。
- 終了ガードがない。最大反復回数とコスト上限がないループは、モデルが解決できないタスクで永遠に回り続ける可能性があります。常に終了条件を設定し、それがトリガーされた場合は必ず人間にエスカレートしてください。
- 遅いゲート。15分かかる統合スイートは、夜間チェックとしては優れていますが、内部ループとしては最悪です。ループには高速なゲートを、マージには徹底的なゲートを維持してください。外部依存関係をモックして、ループが不安定なサードパーティを待たないようにします。
- 変更可能な仕様。エージェントがバグのあるコードに合わせてOpenAPIファイルを編集する場合、契約テストは間違った理由でグリーンになります。仕様は憲法です。エージェントはそれに従って作業し、それを変更しません。
- 一つの巨大なタスク。「サービス全体を構築する」という巨大なタスクに取り組むループは、めったに収束しません。エンドポイント単位のタスクに分解し、それぞれに独自のゲートを持たせます。小さなループは完了しますが、大きなループは空転します。
これらのほとんどは、同じ規律に行き着きます。プロンプトではなく、シグナルに投資することです。ここでの配線パターンと失敗モードは、エージェントワークフローツールの配線でカバーした内容と一致しており、あなたのエージェントがClaude Code、Cursor、Codex、または自作のものであっても変わりません。
この先どうなるか
「プロンプトをやめて、ループを始めよう」という言葉は、より長期的なトレンドの一端を示しています。価値が高まっているスキルは、プロンプトの技巧ではありません。それはループの技巧です。つまり、明確な仕様の記述、決定論的なゲートの構築、終了条件の選択、そしてエージェントが何に触れてよくて何に触れてはいけないかの決定です。これはプロンプトエンジニアリングよりもシステム設計に近く、テスト、契約、CIの観点ですでに考えているエンジニアに報いるものです。
また、優れたテストインフラストラクチャの価値も変化させます。長年、自動テストは必要ないと願う保険のようなものでした。エージェントワークフローでは、それらがステアリングメカニズムとなり、高速だが信頼できないジェネレーターを、正しく収束するシステムに変えるものとなるのです。すでに強力な自動テストカバレッジとクリーンな契約を持つチームは、すぐにエージェントを組み込んでレバレッジを得られます。それがなければ、自信を持って未テストのコードを高速で生成する方法を手に入れることになります。
したがって、実践的な動きは、より優れたモデルやより巧妙なプロンプトを追いかけることではありません。それはゲートを構築することです。仕様を厳格にし、APIテストを決定論的で高速なものにしてください。スキーマを真実の源として維持してください。そして、その周りにループを巻き付け、ゲートがグリーンになるまでエージェントに周回させましょう。
要点
この変化は言葉で表すのは簡単ですが、内在化するのは困難です。コーディングエージェントにプロンプトを出すのが上手になるのではなく、それをプロンプトするループの設計と、そのループが実行されるフィードバックシグナルを改善することです。エージェントは、自分が正しいかどうかを確実に判断できない高速な生成器です。ループは、決定論的なゲートを通じてその判断を提供します。APIを構築する人にとって、あなたはすでにそのゲートを持っています。あなたのテストスイート、スキーマ、そして契約は、意欲的な生成器を正しい方向に収束するシステムに変える、揺るぎない真実なのです。
小さく始めましょう。厳密な仕様を1つ書き、1つの高速なAPIテストスイートにループを向け、ゲートを保護し、反復回数を制限し、あなたが内部ループに介入することなく、エージェントが赤いエンドポイントを緑に変えるのを見てください。そして、次のループを構築しましょう。ゲートを視覚的、スキーマ対応、チーム間で共有可能なものにしたいなら、Apidogがデザイン、モック、自動テストを1つのワークスペースで提供します。ダウンロードして、テストをエージェントを駆動するものにしましょう。
button