AIコーディングエージェントに、自分のバグを自分で見つけるフィードバックループを与える方法

AIコーディングエージェントが、一見正しそうに見えながら、ひそかに何かを壊してしまうコードを書くとき、その原因はたいていモデルにあるのではない。エージェントがその失敗を一度も見ていないことに原因がある。エージェントは変更を書き、勝利を宣言し、次へ進んでしまった。テストスイートが今や赤になったことを、誰も教えてくれなかったからだ。その修正方法は、ループを閉じることだ。エージェント自身のツールが、自動的にエージェントへ報告し返すようにするのである。

本ガイドでは、あなたが気づくよりも先にエージェントが自分のミスを捕まえられるよう、そのフィードバックループを構築する方法を示す。

核心となる考え方:エラーはコンテキストへと流れ戻るべき

信頼できるエージェントのワークフローには、4つの拍子がある。探索する、計画する、構築する、そして検証するだ。多くの人は「構築する」で止まってしまう。動くコードを生み出すエージェントと、もっともらしく見えるだけのコードを生み出すエージェントとを分けるのが、この検証のステップである。

検証とは、変更のたびに本物のチェック(テストランナー、リンター、型チェッカー)を実行し、その出力をエージェントへ返すことを意味する。チェックが失敗すると、そのエラーメッセージがエージェントのコンテキストに届き、モデルはそれを他のあらゆる指示と同じように扱う。つまり、失敗を読んで、それを修正するのだ。退屈な往復に人間が介在する必要はない。

これを実現する方法は2つある。プロジェクト指示の中で頼むか、スキップできないように自動化するかだ。

選択肢1:プロジェクト設定の中で、ただ頼む

最も手間のかからないやり方は、CLAUDE.mdやAGENTS.md(ほとんどのエージェントが起動時に読み込むプレーンテキストの指示ファイル)に一行加えることだ。

## Verification
After any code change, run `npm run typecheck && npm test`.
If either fails, fix the cause and re-run before reporting done.

これは驚くほどうまく機能する。ただし、あくまで助言にすぎない。忙しいエージェントは忘れることもあるし、ある変更を「小さすぎる」から検証しなくてよいと判断することもある。あなたが大事に思うものについては、検証を決定論的にしておこう。

選択肢2:フックで自動化する

Claude Codeのフックを使えば、モデルが覚えているかどうかとは無関係に、ライフサイクルイベントに応じてシェルコマンドを実行できる。ここで関係するのはPostToolUseで、これはエージェントがファイルを編集した後に発火する。ある実践的なフックガイドが述べているように、PostToolUseは反応(フォーマット、ログ記録、テストの実行)のために作られており、その出力はエージェントのコンテキストへ注入され、次のステップに影響を与える。

以下は、ファイル編集のたびに型チェッカーを実行し、失敗をエージェントに渡し返す最小限のフックだ。.claude/settings.jsonに記述する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck"
          }
        ]
      }
    ]
  }
}

これでサイクルは自動になる。エージェントがコードを書く → フックがtscを実行する → 型エラーがあれば、そのメッセージがコンテキストとして流れ戻る → エージェントが修正する → フックが再び実行される。フックのリファレンスには、ゼロでない終了コードと出力がどのようにモデルへ提示されるかが記載されている。このループは書き込みのたびに実行され、こちらから促す必要はない。

ループを速く、範囲を絞ったものに保つ

フィードバックループは、速くなければ役に立たない。いくつかの経験則を挙げる。

• 安価なチェックは編集のたびに、高価なチェックはそれほど頻繁にではなく実行する。 変更されたファイルに対する型チェックやリンターは速い。フルの統合スイートはそうではない。それはStopフック(エージェントがターンを終えたとき)や手動コマンドの後ろに置き、一打鍵ごとに走らせないようにしよう。
• 変更されたものに範囲を絞る。 たった一行のCSS調整の後にテストスイート全体を走らせるのは、時間を浪費し、コンテキストを溢れさせる。ツールが許す範囲で、影響を受けたファイルを狙い撃ちにしよう。
• 失敗を読み取り可能にする。 エージェントは、読めるものしか修正できない。明確で位置が特定されたエラーメッセージ(file:line: message)を出すリンターや型チェッカーは、モデルに必要なものをそのまま与える。一方、ありきたりな「build failed」ではそうはいかない。

具体的なビフォー・アフター

ループがない場合:あなたはエージェントに関数のリネームを頼む。エージェントは3か所の呼び出し箇所を更新するが、開かなかったファイルにある4か所目を見落とし、完了と報告する。あなたは1時間後、実行時に壊れたインポートに気づくことになる。

ループがある場合:同じリネームが保存時にtypecheckをトリガーする。tscは見落とされた呼び出し箇所でCannot find name 'oldFn'を報告する。そのエラーがコンテキストに届き、エージェントは4つ目のファイルを開いて参照を修正し、次のチェックは通る。すべて、エージェントがあなたに完了を告げる前に起きるのだ。

要点

AIエージェントは、コードを生み出すのは得意だが、それが間違っているときに気づくのは苦手だ。あなたはそのギャップを、自分が頼りにしているのと同じシグナル(赤くなったテスト、型エラー、失敗したリントルール)を、変更の直後に自動で届けることによって埋める。まずはプロジェクト指示の一行から始め、それから最も重要なチェックをフックへと昇格させて、モデルが覚えていようがいまいが実行されるようにしよう。「賢い」と感じられるエージェントは、たいてい、緊密なフィードバックループに接続されているだけのエージェントなのだ。