Human-in-the-Loop型コーディングエージェント：レビューワークフロー

ヒューマン・イン・ザ・ループのコーディングエージェントは、たいてい「設定」として語られます。つまり、編集前にツールが確認を求めるモードのことです。しかしそれは一つのループにすぎず、しかも最も小さなループです。開発者一人のターミナル内で、一回のセッションのあいだだけ動き、セッションが終われば消えてしまいます。全員がClaude CodeをManualモードのままにしているからといって人間の監督があると考えるチームが監督できているのは、キーストロークであって成果ではありません。

このガイドでは、レビューのワークフローを5つのゲートとして整理します。ランタイム内の許可プロンプトから、共有された記録上での受け入れ判断までをたどり、各ゲートで誰が決めるのか、その判断がどこに書き残されるのかを説明します。ランタイム側のゲートは各ツールの公式ドキュメントに基づいています。チーム側のゲートにはSharklyを使います。誰かのスクロールバックではなく、Task上にそれらを記録してくれるからです。まずこの実践の定義を知りたい場合は、AIエージェントのプロジェクト管理に関するガイドで、このワークフローが属するループ全体を扱っています。

TL;DR

コーディングエージェントのヒューマン・イン・ザ・ループのレビューワークフローには5つのゲートがあります。ランタイムの許可モード、作業がTaskになる前の計画確認、いつ実行を開始してよいかを決める実行境界、レビューを指名された担当者へ振り分ける注意シグナル、そしてその担当者によるステータス変更として記録される受け入れです。ツールの設定であるのは最初のゲートだけです。残りの4つはチームの判断であり、実効性を持たせるには共有された記録が必要です。エージェントは調査し、実行し、テストし、報告します。人間は方向性を定め、権限を与え、成果を受け入れます。

ゲート1：ランタイム内の許可モード

本格的なコーディングエージェントには、いずれも承認ダイヤルが備わっています。Claude Codeの許可モードは、編集・シェルコマンド・ネットワークアクセスの前に確認を求めるdefault（Manualと表示される）から、acceptEdits、plan、そしてあなたの代わりに「分類器」と呼ばれる第二のモデルが操作をレビューするautoを経て、隔離されたコンテナ専用のbypassPermissionsまで幅があります。切り替えはShift+Tabまたは--permission-modeで行います。Codexも同じ考え方を/permissionsコマンドで提供しており、ファイル編集やコマンド実行を確認なしで行ってよい条件を設定できます。

このゲートは必要ですが、十分ではありません。セッションごと、開発者ごとのものであり、要件ではなくマシンを守るもので、チームメイトが読める記録を何も残しません。Pro、Max、Teamプランでは、Claude Codeは現在デフォルトでautoモードで起動します。これは妥当な選択です。分類器のほうが、疲れた人間が「はい」をクリックするよりも速く、一貫しているからです。教訓はダイヤルに抗うことではありません。ダイヤルをレビューそのものと見なすのをやめることです。

ゲート2：計画の確認

チームレベルの最初のゲートは、コードがまだ存在しない段階で訪れます。SharklyのAgentチャットでは、PlanモードでAgentがあなたのレビュー用にアクションを提案し、計画されたTaskとサブタスクは、人がその提案を確認して初めて作成されます。開始せずに確認することも、確認して開始することもできます。

ここでスコープが決まり、しかもコストは安く済みます。提案されたサブタスクを修正するのは1分ですが、頼まれていないリファクタリングをレビューするのは半日がかりです。分析だけをしたいときはExploreを選んだままにしてください。リーダーがゴールを解釈し、他のAgentメンバーを巻き込む必要がある場合はCrewを使います。一つの役割で作業が完結するなら、儀式的な手順を省いて単一のAgentを使いましょう。AIエージェントとチャットするかTaskを割り当てるに関するガイドで、この3つのモードを扱っています。

ゲート3：実行境界

Agentに割り当てられたTaskは、Backlogにあるあいだは開始されません。作業準備完了（ready for work）カテゴリのステータスへ移動させることが実行の開始であり、完了・キャンセル・重複の各カテゴリからは初期実行が始まることはありません。したがってステータスカテゴリは、人が意図的に操作するゲートであり、ボード上で可視化されています。

このゲートを単なる形式以上のものにする要素が2つあります。各実行には隔離されたディレクトリが与えられ、リポジトリ連携の実行では新しいworktreeが用意されるため、承認された実行が、誰も承認していない実行を壊すことはありません。そして実行は、Taskの説明、最近のコメント、そしてTaskタイプであるWorkflowを引き継ぎ、これがAgentの選択できるステータスを制約します。Workflowがそのステータスを与えていなければ、Agentが自分の作業を「受け入れ済み」にすることはできません。AIコーディングエージェントとGit worktreeの記事で、この隔離について説明しています。

ゲート4：注意シグナル

Agentは実行を、有用な2つの地点のいずれかで終えます。成果を伴って終えるか、問いを残して終えるかです。Sharklyはその両方に名前を付けています。AgentはTaskを「人間の返信待ち」または「人間のレビュー待ち」の状態にでき、失敗またはブロックされた作業は注意項目として表面化します。これらのシグナルはInboxのPrimaryセクションに、責任者に向けて届き、実行の失敗は全購読者ではなく担当者に送られます。

ここでのゲートは振り分けであり、多くのチームが意図せず間違えるのがまさにこれです。チャンネルに流れるレビューは、誰にも届きません。人間の担当者へ、Task上で、実行ログをワンクリックで見られる状態で届くレビューは、後から問い合わせることのできる相手に届きます。AIエージェントのインボックスに関するガイドで、キューの仕組みを扱っています。

返信は作業を続ける手段でもあります。準備完了のAgent担当者が割り当てられたTaskにメンバーがコメントすると、次の実行をキューに積むことができ、レビューのフィードバックが別のプロセスを立ち上げるのではなく、同じ作業を続けさせます。個人へのメンションや全体メンションは、それ自体ではAgentを起動しません。これにより、人間同士のやり取りがAgentを呼び覚ますことはありません。

ゲート5：記録上での受け入れ

受け入れとは、証拠を読んだうえで人がTaskのステータスを変更することです。読む順番は次のとおりです。説明に書かれた受け入れ基準、実行したチェックと不確実な点を明記したAgentのコメント、実行ログ、そしてdiffです。ログには、実行がなぜキューに積まれたのか、いつ始まりいつ終わったのか、ツール呼び出しとRuntimeイベント、トリガー元、失敗の詳細が記録されます。変更をレビューすることと、変更についての物語をレビューすることの違いは、ここにあります。

このゲートを守る2つのルールがあります。リンクされたプルリクエストをマージしてもTaskのステータスは変わらないため、マージが受け入れと誤解されることはありません。また、完了したAutomationの実行は、その実行について述べているのであって、下流のあらゆる成果が正しかったという約束ではありません。どちらも製品ドキュメントにそのまま書かれていることであり、どちらも「終わった」と「正しい」を混同し続けたチームがあったからこそ存在します。

ワークフローを1つの表にまとめる

ゲートをより広く開くべきとき

すべてのTaskが5つの関門に値するわけではなく、そうでないふりをすることがレビューを劇場にしてしまいます。リポジトリ監査のような読み取り専用の作業に必要なのはゲート1とゲート5だけです。隔離されたworktree内の可逆的な作業、たとえばテスト付きの依存関係の更新は、計画の確認を飛ばせます。スケジュールで実行されるAutomationには、人がいつレビューまたは判断すべきかを手順に明記させ、誰かがそのスケジュールに依存する前に手動で実行して点検すべきです。これについてはSharklyのAutomationsのガイドで扱っています。

公開インターフェースを変えるもの、データに触れるもの、コマンド1つで元に戻せないものについては、5つすべてを維持してください。そしてどこでも一つのルールを守りましょう。すべてのAgent Taskに、指名された人間の担当者を置くことです。Sharklyは人間の責任とAgentの実行を意図的に分けており、そのため1つのTaskに人とAgentを同時に割り当てられます。説明責任は委譲されません。誰がそれを負っているかを記録が示すべきです。

ヒューマン・イン・ザ・ループではないもの

ターミナルを見つめる人のことではありません。疲れ果てたレビュアーが背後にいる許可プロンプトのことでもありません。そして「Completed（完了）」と表示されるステータスのことでもありません。チームの判断が必要なところで自動化は止まり、完全なコンテキストと検証可能な証拠を備えた成果物を返します。この一文がワークフローのすべてであり、ゲートはそれが強制される場所にすぎません。SharklyはClaude Code、Codex、その他の実行ツールの置き換えではありません。これらの判断を書き留めるレイヤーです。

FAQ

Claude Codeのautoモードは人間をループから排除しますか？ 排除するのは、許可プロンプトから人間を外すことです。分類器はあなたのリクエストに対して操作をレビューしますが、成果が要件を満たしたかどうかはレビューしません。ゲート2から5は依然として人間の担当です。

実行中のAgentを止めるにはどうすればよいですか？ キュー済みまたは実行中の実行はキャンセルできます。Taskをキャンセルまたは重複のステータスに移動しても実行中の実行は止まりますが、完了に移動しても止まりません。Agentがまだ作業中なら、先にキャンセルしてください。

レビュアーは誰が務めるべきですか？ Taskの人間の担当者です。Sharklyはレビュー待ちと失敗のシグナルをその人物へ送ります。だからこそ、すべてのAgent Taskに一人を指名すべきなのです。SharklyのAgentsに関するガイドで、2つの割り当て枠について説明しています。

新しいTaskを作らずに、レビューのフィードバックをAgentへ返せますか？ はい。Taskへのコメントで、割り当てられたAgentの追加実行をキューに積めます。また、連続したコメントはまとめられるため、重複した実行は作られません。