AIエージェントに自分で検証させる — 検証ループの組み方

エージェントを使っていて最も消耗するのは、「できました」と言われた内容を毎回自分で確かめる状態です。作業自体は速くなっているのに、確認の負荷だけが自分に残る。しばらく続けると、結局ずっと画面を見ていることになります。

この状態を抜ける方法ははっきりしています。エージェント自身が回せる検証手段を渡すことです。

エージェントは「終わったように見えたら」止まる

Claude Codeの公式ベストプラクティスは、この問題を的確に言い当てています。エージェントは仕事が終わったように見えた時点で止まる。そして自分で回せるチェックがなければ、「終わったように見える」が唯一の判断材料になります。

その結果どうなるか。公式の表現を借りれば、あなた自身が検証ループになるという状態です。ミスはすべて、あなたが気づくまで待機します。

検証手段を渡していないエージェントは、間違いに気づく方法を持っていません。

逆に、合否が出るものを渡せばループは自分で閉じます。エージェントが作業し、チェックを走らせ、結果を読み、通るまで繰り返す。人間はその外側に出られます。

検証手段は「合否が返るもの」なら何でもよい

公式が挙げている検証手段は、テストだけではありません。会話の中でエージェントが読み取れる信号を返すものであれば何でも使えます。

公式は、指示の書き方についても対比を示しています。

停止をどこまで強く縛るか

検証手段を用意したうえで、次に決めるのがそれをどこまで強く「止まる条件」にするかです。公式は4段階を示しています。

段階が上がるほど設定の手間はかかりますが、その分だけ「見ていない間に正しく終わる」確率が上がります。

いちばん手軽な1段目は、今日から使えます。一方で、席を外している間に正しく終わってほしいなら、3段目か4段目が必要になります。

フックは「お願い」ではなく「保証」

指示ファイルの章で触れたとおり、指示ファイルに書いたルールは助言であり、守られる保証はありません。対してフックは決定的です。公式も「例外なく毎回起きてほしい処理にはフックを使え」と明記しています。

検証との関係で効くのは主に2種類です。

編集後に自動で走らせる。 ファイルを編集したら整形と lint を必ずかける、といった処理です。「整形してください」という指示が要らなくなります。

ツール実行の前に入力を加工する。 公式が挙げている例が秀逸で、テスト実行コマンドを横取りして失敗した部分だけを抜き出すようにフィルタします。1万行のログをエージェントに読ませる代わりに、エラー行だけを返す。検証を成立させながら、コンテキストの消費も同時に抑えられます。

主張ではなく証拠を出させる

もう1つ、公式が挙げている実務的な指針があります。成功を主張させるのではなく、証拠を出させるというものです。

• 実行したコマンドと、その出力
• テストの結果そのもの
• 結果のスクリーンショット

理由は単純で、証拠を読むほうが、自分で検証をやり直すより速いからです。しかもこれは、自分が見ていなかったセッションに対しても機能します。「テストが通りました」だけの報告では、通したのか、通ったことにしたのかを区別できません。

書いた本人以外にレビューさせる

4段目の「第三者の目」は、少し性質が違います。公式の説明によれば、新しいコンテキストで動くレビュー役は、差分と与えられた基準だけを見て、その変更を生んだ思考過程を見ません。だから自分の判断に引きずられずに評価できます。

よくあるハマりどころ

信じてから確かめる。 公式が失敗パターンとして挙げているものです。もっともらしい実装が出てきて、エッジケースを踏んでいないことに後から気づく。対策は「常に検証手段を用意する。検証できないものは出荷しない」です。

検証手段のない領域に大きな仕事を投げる。 テストのない箇所に大量の変更を入れると、合否の判定ができません。タスクの切り方で触れたとおり、先にテストを書かせるタスクに切るほうが結果的に速いことがあります。

書いた本人に採点させる。 実装とテストを同じ前提から作れば、前提が間違っていてもテストは通ります。独立した目が要るのはここです。

ログを丸ごと読ませて検証させる。 検証にはなりますが、コンテキストを大量に消費します。フックで絞ってから渡します。

8回ブロックを成功と取り違える。 前述のとおりです。ゲートを入れたら、通ったのか諦めたのかを区別できるようにしておきます。

ちゃんと使うためのポイント

• エージェントは終わったように見えたら止まる。チェックがなければ、あなたが検証ループになる
• 検証手段は合否が返るものなら何でもよい。テスト・ビルド・lint・スクリーンショット比較
• 指示は「実装して」で終わらせず、「確認して、直して」まで1つに入れる
• 停止の縛りは4段階。席を外すつもりなら、決定的なゲートか第三者レビューまで上げる
• 指示ファイルは助言、フックは保証。毎回必ず起きてほしいものはフックへ
• 成功の主張ではなく証拠を出させる
• レビュー役には「正しさか要件に関わる欠落だけ」を挙げさせる。全指摘を潰すと過剰設計になる

次の章では、この検証ループを一度きりで終わらせないための仕組み——評価とリグレッションを扱います。1回通ったことと、次も通り続けることは別の問題です。

参考リンク

• Best practices for Claude Code（公式） — 検証手段を渡す理由、停止を縛る4段階、証拠を出させる指針、レビュー役の落とし穴
• Get started with hooks（Claude Code 公式） — 決定的な処理をフックとして書く方法
• Manage costs effectively（Claude Code 公式） — フックでツール入力を加工し、出力を絞る実例