コーディングエージェントへのプロンプトをやめて、自動プロンプトループを構築する

コーディングエージェントに「次のプロンプト」を投げ続けるのではなく、エージェントが自分で修正を繰り返せるループを設計しましょう。実装、実行、検証、失敗のフィードバック、再実行までを自動化すると、AIはチャット相手ではなく、検証ゲートの中で動くワーカーになります。AIコーディングエージェントを実務で活かすには、プロンプトの技巧よりも、ループとテストの設計が重要です。

今すぐApidogを試す

TL;DR

コーディングエージェントループとは、次の処理を自動で繰り返す制御構造です。

1. エージェントがコードを変更する
2. テスト、ビルド、型チェック、APIテストを実行する
3. 決定論的なゲートで合否を判定する
4. 失敗内容を次の入力としてエージェントに返す
5. 成功するか、上限に達するまで繰り返す

重要なのはエージェントそのものではなく、検証ゲートです。

「問題なさそう。もう一度試して」のような曖昧なフィードバックでは、エージェントは迷走し、完了を幻覚します。一方で、失敗したテスト、スキーマ不一致、契約違反、ステータスコード差分のような明確なシグナルを返すと、ループは収束します。

APIやバックエンド開発では、自動テストスイートと契約チェックがそのゲートになります。だからこそ、APIテストはエージェントワークフローの最後に追加するものではなく、中心に置くべきものです。

プロンプトからループ設計へ

多くの開発者は、チャットボックス経由でAIコーディングを始めます。

「この関数を書いて」

「このエラーを直して」

「このAPIを実装して」

小さな関数や説明ならこれで十分です。しかし、実際の開発タスクは通常、1回の回答では終わりません。テストが落ち、型が合わず、エッジケースが漏れ、仕様と実装がずれます。

手動プロンプトの問題は、あなた自身がループになっていることです。

• 出力を読む
• バグを見つける
• エラーをコピーする
• 次の指示を書く
• もう一度待つ

エージェントは数秒でコードを書けますが、人間がコンテキストを切り替え、ログを読み、次のプロンプトを考えている間は停止しています。高速なシステムの中で、最も遅い部分が人間になります。

ループを設計すると、この構造が変わります。

エージェントがコードを書く。

スクリプトがテストを実行する。

結果をキャプチャする。

失敗したら、その失敗を次の入力として返す。

成功したら停止する。

内部ループに人間は不要です。人間は、タスクの定義、最終レビュー、失敗時のエスカレーションだけを担当します。

Anthropicの効果的なエージェントの構築でも、価値は単一の賢いプロンプトではなく、モデルの周囲に構築する環境から生まれると説明されています。

問いを変えましょう。

「エージェントに何を言うべきか？」ではなく、

「エージェント自身に次の入力を与えるループをどう設計するか？」です。

コーディングエージェントループの構成要素

実装レベルで見ると、コーディングエージェントループは5つの部品で構成できます。

1. タスク仕様
   
   完了条件を明確に書きます。
   
   「動くようにする」では不十分です。
   
   例: POST /orders は作成された注文を含む 201 を返し、レスポンスボディはスキーマに一致し、必須フィールド不足は 422 で拒否する。

2. エージェント
   
   モデルとツールです。ファイルの読み書き、シェルコマンドの実行、コード編集などを行います。

3. アクションステップ
   
   エージェントが変更を加え、何かがそれを実行します。テスト、ビルド、型チェック、APIリクエストなどです。

4. 検証ゲート
   
   合格または不合格を、具体的な理由付きで返す決定論的なチェックです。ここがループのステアリングホイールです。

5. 終了条件
   
   いつ止めるかを決めます。ゲートが合格したとき、最大反復回数に達したとき、またはコスト上限を超えたときです。出口のないループはワークフローではなく暴走です。

擬似コードにすると、基本形はこうなります。

task = load_spec("orders-endpoint.md")
last_result = None

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 を高めに設定し、仕様と検証を厳密にしたものです。エージェントハーネスアーキテクチャの観点で見ると、このループは最小構成のハーネスです。

ワンショットプロンプトが限界に達する理由

単一のプロンプトは、次のどちらかを前提にしています。

• モデルが初回で正しく実装する
• 人間がモデルのミスを見つけて修正指示を出す

どちらも大規模な開発では破綻します。

モデルは、もっともらしいコードを生成するのは得意です。しかし、そのコードが本当に正しいかを判断するのは苦手です。

たとえば、エンドポイントはコンパイルでき、簡単なリクエストにも応答するかもしれません。しかし、次のような問題が残ることがあります。

• 必須フィールド不足で 422 ではなく 500 を返す
• レスポンスの total が数値ではなく文字列になる
• 認証が必要なエンドポイントで未認証アクセスを許可する
• OpenAPI仕様と実装がずれる
• エッジケースだけで誤ったステータスコードを返す

チャット上では、モデルは「完了しました」と自信を持って言うかもしれません。しかし、モデルの自信は合否判定ではありません。

ループは、モデルに自己採点させません。

エージェントは「完了」と宣言できません。

ゲートだけが完了を宣言できます。

テストが赤なら未完了。

スキーマ検証が落ちるなら未完了。

契約違反があるなら未完了。

この構造にすると、次の入力は人間の感想ではなく、機械生成された失敗シグナルになります。

また、ループは並列化しやすいという利点もあります。手動プロンプトでは、人間が監視できる1つのエージェントが限界です。ループ化すれば、複数のエージェントを別々のタスクとゲートに対して同時に走らせられます。

これは、動的で並行的なエージェントワークフローで扱われる発想と同じです。入力速度を上げるのではなく、ループを増やしてスケールします。

検証ゲートがループの品質を決める

エージェントワークフローが失敗する主な理由は、モデルが弱いことではありません。フィードバックシグナルが弱いことです。

ゲートは各イテレーションで、エージェントに次のどちらかを返します。

• 合格。停止。
• 不合格。理由はこれ。

この「理由」の品質が、次の修正の品質を決めます。

良いフィードバック:

Expected 422 when customer_id is missing, but got 500.
Test: orders.validation.missing_customer_id
File: tests/orders_validation_test.py:42

悪いフィードバック:

何かがおかしいようです。確認してください。

前者なら、エージェントは特定の失敗を修正できます。後者では推測が始まり、コードをさらに悪化させることがあります。

決定論的なゲートは収束します。

曖昧なゲートは迷走します。

良いゲートには、次の性質が必要です。

• バイナリで再現性がある
  
  同じ入力なら同じ結果を返す。モデルの気分やレビュー担当者の感覚に依存しない。

• 失敗理由が具体的
  
  テスト名、期待値、実際の値、差分、行番号、ステータスコードを返す。

• エージェントが勝手に変更できない
  
  エージェントがテストを書き換えて合格できるなら、ゲートではありません。テストと仕様は保護します。

• 高速に実行できる
  
  20分かかるゲートは内部ループには向きません。短い反復には高速なチェックが必要です。

実際には、多くの成熟したコードベースにはすでにゲートがあります。

• ユニットテスト
• 型チェッカー
• リンター
• コンパイラ
• スキーマバリデーター
• APIテスト
• 契約テスト

これらは、人間に「ここが間違っている」と伝えるために作られた決定論的なオラクルです。そして、それはそのままエージェントループに必要なシグナルになります。

まだ自動テストの層を整理していない場合は、自動テストとは何かを確認し、ループ化する前にゲートを整備してください。

APIおよびバックエンド開発では、テストスイートがループになる

APIエンドポイントをエージェントに実装させる場合、真実の源はモデルの要約ではありません。実際のエンドポイントの振る舞いです。

確認すべきものは明確です。

• 正しいステータスコードを返すか
• レスポンスボディがJSONスキーマに一致するか
• 認証・認可が強制されるか
• 不正な入力を拒否するか
• OpenAPI仕様と実装が一致するか
• 既存の契約を壊していないか

これらはすべて自動で検証できます。つまり、APIテストスイートは、そのままエージェントループの検証ゲートになります。

エンドポイント実装のループは、次のように設計できます。

1. エージェントがタスク仕様とOpenAPI定義を読む
2. エージェントが対象エンドポイントを実装または修正する
3. ハーネスが実行中のサービスに対してAPIテストを実行する
4. ステータスアサーション、JSONスキーマ検証、契約チェックを行う
5. 失敗を構造化してエージェントに返す
6. テストがグリーンになるまで繰り返す
7. 成功後に人間がレビューする

失敗フィードバックは、次のように具体的にします。

Expected 422 when customer_id is missing, but got 500.

Response field total is string, but schema expects number.

Endpoint /orders/{id} exists in OpenAPI spec but has no implementation.

このような機械生成のフィードバックがあると、エージェントは特定のギャップを修正できます。

スキーマファーストと契約テストは、エージェント時代にさらに重要になります。OpenAPI仕様が、エージェントとゲートの両方が読む共有の真実になるからです。

仕様とコードのずれは、もはや後で直すドキュメントの問題ではありません。即座に赤いゲートになります。

ここでApidogが役立ちます。Apidogは、API設計、スキーマ、モックサーバー、自動テストを1つのワークスペースで扱えるAPIプラットフォームです。

エージェントループをApidogのテストシナリオに接続すると、各イテレーションでスキーマ検証済みの合格・不合格を取得できます。また、モックサーバーを使えば、まだ構築されていない依存関係の代わりに安定したターゲットを用意できます。

すでにこの構成を使うチームでは、Apidog AIエージェントデバッガーのようなツールアクセスを接続し、エージェントが人間のテスターと同じようにエンドポイントを叩いて検査できるようにしています。

テストランナーを一から作るのではなく、視覚的にAPIゲートを構築したい場合は、Apidogをダウンロードしてください。

今日から最小限の自己修正APIループを作る

フレームワークは不要です。必要なのは、仕様、テストコマンド、簡単な接続コードです。

ステップ1：仕様をゲートの意図として書く

OpenAPIファイルに契約を書き、テストケースに振る舞いを書きます。

例:

paths:
  /orders:
    post:
      summary: Create an order
      responses:
        "201":
          description: Created order
        "422":
          description: Validation error

エージェントには、実装対象の仕様とテストを読ませます。ただし、後述するように、仕様やテスト自体は自由に編集させない方が安全です。

ステップ2：失敗時にゼロ以外の終了コードを返すコマンドを用意する

終了コードが正直であれば、ツールは何でも構いません。

• pytest
• Newman
• Apidog CLIテストシナリオ
• 独自のAPIテストランナー

例:

# ゲートを単一コマンドとして実行
apidog run ./tests/orders-suite --reporter json > result.json

ループが必要とするのは、合否と出力だけです。

ステップ3：エージェントとゲートを接続する

最小構成は次のようになります。

import subprocess

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,
        text=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")

parse_failures() では、テスト出力からエージェントに返すべき失敗理由を抽出します。

例:

def parse_failures(output: str) -> str:
    # 実際にはJSONをパースして、失敗テスト名、期待値、実際の値を抽出する
    return f"""
The verification gate failed.

Use the following failures to fix the implementation.
Do not modify the tests or OpenAPI spec.

Failures:
{output}
"""

ステップ4：ゲートを保護する

エージェントが編集できるファイル範囲を制限します。

編集を許可するもの:

src/**
app/**
routes/**
controllers/**
services/**

編集させないもの:

openapi.yaml
tests/**
apidog-tests/**
contracts/**

エージェントがテストを書き換えて合格できるなら、進捗ではなく偽装を自動化しているだけです。

仕様は憲法です。エージェントは従うべきであり、勝手に変更すべきではありません。

ステップ5：コストと反復回数を制限する

必ず上限を設定します。

• 最大反復回数
• 最大実行時間
• 最大トークン使用量
• 最大コスト
• 失敗時のエスカレーション条件

収束しないループは、予算をすぐに消費します。トークン使用量を抑えたい場合は、エージェントのトークンコストを削減する方法も参考になります。

良いループを設計するための注意点

機能するループと、コストだけを消費するループには明確な違いがあります。

エージェント自身に採点させない

唯一のチェックが「完了しましたか？」なら、それはループではありません。余分な手順のあるチャットボットです。

ゲートは必ずエージェントの外部に置きます。

ゲートを粗くしすぎない

浅いテストが3つだけなら、エージェントはその3つだけを満たし、未カバーの部分にバグを残します。

ループの品質上限は、ゲートのカバレッジで決まります。

終了条件を忘れない

最大反復回数やコスト上限がないループは、解けないタスクで回り続けます。

必ず停止し、人間に渡す条件を定義してください。

遅いゲートを内部ループに使わない

15分かかる統合テストは、マージ前や夜間チェックには有効です。しかし、内部ループには遅すぎます。

おすすめは分離です。

• 内部ループ: 高速なAPIテスト、型チェック、限定的な契約テスト
• マージ前: フル統合テスト、E2E、負荷テスト

外部依存関係はモックし、ループが不安定なサードパーティを待たないようにします。

仕様を勝手に変更させない

エージェントがバグのある実装に合わせてOpenAPI仕様を編集すると、契約テストは間違った理由でグリーンになります。

仕様は実装に合わせるものではなく、実装が仕様に従うべきです。

タスクを大きくしすぎない

「サービス全体を構築する」のような巨大タスクは収束しにくいです。

小さく分けます。

• POST /orders
• GET /orders/{id}
• PATCH /orders/{id}/status
• DELETE /orders/{id}

エンドポイント単位で仕様とゲートを持たせると、ループは完了しやすくなります。

これらのパターンは、Claude Code、Cursor、Codex、自作エージェントのどれを使っても同じです。詳細な配線パターンと失敗モードは、エージェントワークフローツールの配線でも扱っています。

これから重要になるスキル

「プロンプトをやめて、ループを始める」という考え方は、AI開発のスキルセットが変わっていることを示しています。

価値が高まるのは、プロンプトの言い回しではありません。次のようなループ設計のスキルです。

• 明確な仕様を書く
• 決定論的なゲートを作る
• テスト出力を構造化する
• 終了条件を設定する
• エージェントが触ってよい範囲を制限する
• 失敗時に人間へエスカレーションする

これはプロンプトエンジニアリングというより、システム設計です。テスト、契約、CIを重視してきたエンジニアほど、エージェントを安全に活用しやすくなります。

自動テストの価値も変わります。

以前の自動テストは、壊れたときに検知する保険のようなものでした。エージェントワークフローでは、テストはステアリングメカニズムになります。高速だが信頼できない生成器を、正しい方向に収束するシステムへ変えるための制御装置です。

すでに強力な自動テストカバレッジとクリーンな契約を持つチームは、すぐにエージェントを組み込めます。逆に、それがなければ、未テストのコードを高速に生成するだけになります。

要点

コーディングエージェントにプロンプトを出すのが上手くなるよりも、エージェントを動かすループと検証シグナルを設計する方が重要です。

エージェントは高速な生成器です。しかし、自分が正しいかを確実には判断できません。ループは、テスト、スキーマ、契約、型チェックのような決定論的ゲートを使って、その判断を外部から与えます。

APIを構築しているなら、ゲートはすでにあります。テストスイート、OpenAPIスキーマ、契約チェックです。

まずは小さく始めましょう。

1. 厳密な仕様を1つ書く
2. 高速なAPIテストスイートを1つ用意する
3. エージェントの編集範囲を制限する
4. 失敗出力を次の入力として返す
5. 最大反復回数を設定する
6. グリーンになったら人間がレビューする

赤いエンドポイントを、あなたが内部ループに介入せずに緑へ変えられるようになります。

ゲートを視覚的に作成し、スキーマ対応で、チーム間で共有したい場合は、ApidogがAPI設計、モック、自動テストを1つのワークスペースで提供します。ダウンロードして、テストをエージェントを駆動するゲートにしましょう。