作業中のエージェントをレビューする

10 時 40 分、あなたは請求サービスでマネージド実行を開始します。タスクは「サービスをローカルでセットアップして動かす方法をドキュメントにまとめる」。11 時 02 分、新しい docs/setup.md を含む pull request が届きます。悪くない出来です。ただ、12 行目は新しく入ったメンバーに go build ./... を実行するよう書いていて、これはサービスに必要な build tag を読み飛ばすので、最初のビルドはドキュメントのどこにも説明のない形で失敗します。そして 6 分目あたりのどこかで、エージェントは README の Docker セクションが古いと判断し、書き直していました。誰もそんなことは頼んでいません。

どれもレビューで直すのは難しくありません。レビューで取り戻せないのは、その間の 20 分です。エージェントはこうした選択を早い段階で、誰の確認もないまま行い、その後のすべてをその上に積み上げました。修正するには、ゼロから始まり、同じファイルをもう一度読み、2 つ目の pull request を開く 2 回目の実行が必要になります。

これまでの Archyl のマネージドエージェント実行は、このように動いていました。実行ページにはイベントフィードと指示ボックスがあったので、タブを開いたままにしておけばノート PC からでもスマートフォンからでも、ツール呼び出しを追うことはできました。しかし、エージェントが何をしようとしているのか、ここまでに何を書いたのかは、ツール呼び出しのペイロードからつなぎ合わせるか、pull request を見て知るしかありませんでした。夜間の依存関係監査ならそれで問題ありません。どうせレビューする変更の場合は、レビューがいちばんコストの高いタイミングに来てしまいます。

実行にレビューループが加わりました。変わった点は次のとおりです。

この記事の残りでは、同じタスクを新しいやり方でもう一度、あなたが体験する順番で追っていきます。タスクは例ですが、以下に引用するメッセージはすべて、エージェントが実際に受け取る形式です。

まず計画から

ファイルに触れる前に、エージェントは 1 文の要約といくつかの具体的なステップを添えて propose_plan を呼ぶよう指示されます。プロンプトは 3〜8 ステップを求め、ツールは 12 を超えるステップを拒否するので、計画はひと目で読める長さに収まります。実行ページ上部の 計画 パネルは、これをチェックリストにします。作業を進めながら、エージェントは各ステップを 進行中、完了、スキップ のいずれかにし、短いメモを添えることもあります。パネルには現在のステップと進捗(2/4)が表示されます。

既定では、計画は共有されるだけで、エージェントはすぐに作業を始めます。エージェントプロファイルの 連携 にある 先に計画をレビューする をオンにすると、エージェントはあなたを待つようになります。パネルはレビューモードに切り替わり、ステップの名前変更や詳細の追加に加え、ステップの追加、削除、並べ替えができます。

セットアップドキュメントについて、エージェントは 5 つのステップを提案しました。4 つ目は「README の Docker セクションを更新する」で、誰も頼んでいない書き直しです。あなたはこれを削除し、ステップ 2 に詳細を追加します。すると 計画を承認 だったボタンが 編集した計画を承認 に変わります。エージェントに返されるのは次の内容です。

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

あなたが編集したバージョンが、エージェントの従う計画になり、チェックリストが追跡する計画になります。計画が少しずれているのではなく間違っている場合は、変更を依頼 で代わりにフィードバックを送ります。エージェントは計画を修正して新しいリビジョンを提案し、以前のリビジョンはフィードに残るので、あなたのフィードバックで何が変わったかを確認できます。

計画が承認されるまで、エージェントはファイルを書き込むことも、Archyl のツールでアーキテクチャモデルを変更することも、コネクタ経由でリポジトリにプッシュすることもできません。これは、エージェントが言いくるめて回避できるようなプロンプトの一文ではありません。呼び出しそのものが拒否され、エージェントは次のメッセージを読みます。

changes are refused until your plan is approved: call propose_plan and wait for the review

1 時間以内に誰も計画をレビューしなければ、実行は何も変更しないまま失敗します。レビューを求めるプロファイルは、誰も現れなかったからといってレビューを飛ばすことはありません。

人が決めるべきときは質問する

エージェントが単独で下すべきではない判断があります。あいまいな要件、明確な勝者のいないトレードオフ、破壊的な操作などです。そうした場面のために ask_human があります。指示には、自分で調べられることは決して質問しないよう書かれており、質問は 1 回の実行につき最大 5 件までです。質問を小出しにして作業をあなたに投げ返すことはできません。

ステップ 2 の途中で、エージェントは設定の中に STAGING_DATABASE_URL を見つけます。ドキュメントに書けば役に立ちそうですが、staging には VPN アクセスが必要で、新しく入ったメンバーは最初の 1 週間それを持っていません。リポジトリのどこにもそのことは書かれていないので、エージェントは質問します。

質問はフィードの上に表示されます。エージェントが候補を示した場合は 回答の候補(「staging は含めない」「VPN アクセスについての注記を付けて記載する」)が並び、自分で回答を書く欄もあります(Cmd/Ctrl + Enter で送信)。プロジェクトを編集できる人なら誰でも回答でき、誰が回答したかはフィードに記録されます。エージェントは The human answered: Leave staging out を読み、作業を続けます。

1 時間以内に誰も答えなかった質問は、実行を失敗させません。エージェントは自分の判断で作業を続け、置いた前提を成果に記載します。計画とは逆の扱いで、その違いは何が懸かっているかにあります。レビューされていない計画は何も合意されていないことを意味しますが、答えのない質問は、エージェントが実行中ずっと下している判断がひとつ増えるだけです。

待つことのコスト

エージェントが計画のレビューや回答を待っている間、実行には あなたの対応待ち と表示され、実行一覧では 対応が必要 に分類されます。フィードの上のバナーが、何を待っているのか(計画のレビューを待っています または エージェントから質問があります)を示し、その場所へ案内します。

待機時間は実行の時間上限に含まれません。期限は待った時間の分だけ後ろにずれるので、上限 30 分の実行があなたを 20 分待ったとしても、作業時間は 30 分のままです。ただし、同時実行枠は使ったままです。承認待ち の実行はまだ始まっていないので何も保持しませんが、対応待ちの実行は会話の途中で、ワークスペースを開いたまま、あなたの返答が届けばすぐ再開できる状態にあるからです。

書かれるそばから見える差分

実行ページには 2 つのビューができました。イベントフィードである アクティビティ と、変更 です。変更 には、エージェントが書き込むファイルが書き込みと同時にすべて一覧表示され、ステータス(追加、変更、ブロック)と、ファイルごとおよび実行全体の追加行数・削除行数が表示されます。ファイルを選択すると、最終状態だけでなく、各書き込みで何が変わったか(編集 2/3)を確認できます。

すべてのファイル書き込みに対する適合性チェックであり、いまはワーカーの中で動いている Guard も、ここに表示されます。Guard が拒否した書き込みは ブロック になります。その内容がファイルに届くことはありませんでしたが、差分にはエージェントが書き込もうとした内容と、違反したルールが表示されます。警告だけが出た書き込みは反映され、ファイルに警告が付きます。以前ならツールの結果の中で見つけていた拒否が、読める差分になりました。

制限が 2 つあります。長い差分は 600 行で打ち切られ、128 KB を超えるファイルは差分なしで表示されます。

12 行目へのコメント

go build ./... の話に戻りましょう。pull request を待つ必要はありません。変更 で行番号をクリックし、コメントを書いて エージェントに送信 します(Cmd/Ctrl + Enter)。エージェントは次のステップで、ファイル、行、その内容を含むコードレビューのコメントとしてこれを受け取ります。

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

エージェントは行を修正してから、元のステップに戻ります。行の下のコメントには、エージェントが受け取るまで 送信待ち、受け取った後は 配信済み と表示されます。コメントは アクティビティ にも表示され、一覧の各ファイルにはコメント数が表示されます。修正はそのファイルの次の編集として届くので、コメントを残した差分が、そのまま修正を確認する場所になります。

追加された行、変更のない行、削除された行のいずれにもコメントできます。削除された行へのコメントは「the lines you removed」へのコメントとしてエージェントに届くので、チェックを元に戻すよう伝えるときに使えます。コメントはエージェントが作業中でも対応待ちでも受け付けられ、待機中のエージェントは再開時にそれを読みます。実行終了時にまだ 送信待ち のコメントには 未配信 と表示されます。Guard がブロックした書き込みにはコメントできません。

指示ボックスも引き続き使えます。実行をキャンセルせずに、自由記述でエージェントの方向を変えるためのものです(「マイグレーションは飛ばして、ハンドラーに集中して」)。行コメントは、同じ仕組みを行に固定したものです。省けるのは前置きです。「docs/setup.md の、go build と書いたところで」という情報は、最初からメッセージに含まれています。

レビューするものが何もなかった実行

変更 を作っている最中、私はある実行に、社内の Git リポジトリの 1 つへドキュメントを追加するよう頼み、ビューが空のままなのを眺めることになりました。ファイルもなければ差分もなく、コメントする対象もありません。

プロジェクトにはリンクされたリポジトリがなかったので、Archyl は何もクローンしていませんでした。その実行にあったのは GitHub コネクタで、エージェントは手元のツールで妥当なことをしました。コネクタの push_files ツールで、ファイルを GitHub に直接書き込んだのです。ワークスペースを通ったものは何もありません。だから Guard を通ったものも、変更 に表示されたものもなく、私が作っていたレビューループにはレビューするものが何もありませんでした。

いまでは、エージェントはどちらの場合もワークスペースで作業します。

• プロジェクトにリポジトリがリンクされている場合。 これまでどおり、実行の開始時に Archyl がクローンします。
• リンクされたリポジトリはないが、GitHub コネクタが接続されている場合。 エージェントはファイルに触れる前に、コネクタの認証情報で open_repository を呼び出し、タスクの対象となるリポジトリを自らクローンします。これは GitHub のホスト型 MCP サーバー(api.githubcopilot.com)でのみ動作し、トークンにはリポジトリへのアクセス権が必要です。

ワークスペースが開いた後は、リポジトリに書き込むコネクタのツール(push_files、create_or_update_file、delete_file、create_pull_request)が拒否され、エージェントは次のメッセージを読みます。

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

このルールがあるからこそ、すべての変更が Guard を通り、変更 に表示され、1 つの pull request にまとまります。

実行が終わるとき

Archyl はワークスペースの変更を、実行 ID の先頭 8 文字を使った archyl/agent-<run id> にコミットし、クローン元のブランチに向けて pull request を開きます。リンクは 変更 の上部(プルリクエストを開く)と結果に表示されます。何が公開されるかは、実行がどう終わったかで決まります。

GitLab では、ドラフトは Draft: のマージリクエストになります。Bitbucket では、pull request は作らずにブランチだけをプッシュします。ファイルを 1 つも変更しなかった実行は、何も公開しません。

コメントが次の実行になる

実行が止まっても、レビューは止まりません。pull request は開いていて、あなたは 変更 で最終的な差分を読んでいます。終了した実行へのコメントには届けるエージェントがいないので、次の実行へのメモになります。継続用に追加 で、コメントはブラウザに保存されます。ファイル一覧の上のバーがその数を示し(継続用のコメントが 3 件あります)、これらで継続する を提示します。

終了した実行には、結果にかかわらず 2 つのボタンがあります。もう一度実行 は、同じタスクとプロファイルで開始ダイアログを開き、ゼロから新しく実行します。最初の試みが、その上に積み上げたくない方向に進んでしまったときに選ぶボタンです。継続 は、この実行の作業を引き継ぐ新しい実行を開始します。継続用のコメントを残していれば、指示にはそれが 1 行に 1 件ずつあらかじめ入力されます。

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

内容は自由に編集できます。プロファイルはデフォルトで元の実行と同じになり、コネクタも選択できます。

同じブランチ、同じ pull request

継続は、プロンプトが長くなっただけの新しい実行ではありません。前の実行が公開したブランチから始まってそこにコミットし、別の pull request を開くのではなく、同じ pull request に変更を追加します。前の実行が GitHub コネクタ経由でリポジトリを開いていた場合は、エージェントが始まる前に、継続した実行がそのブランチでリポジトリを開き直します。

エージェントには、何の上に積み上げるのかも伝えられます。前のタスク、その実行が何をしたか(成果の要約、または止まった理由)、そしてその作業がどこにあるかが、すべてプロンプトの先頭に入ります(ID、URL、要約は例です)。

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

レビュアーが目にするのは、1 つの pull request が育っていく様子であって、pull request が次々と並ぶ様子ではありません。GitHub の Copilot cloud agent もフォローアップを同じように扱います。pull request のコメントで @copilot にメンションすると、既定ではその pull request のブランチにコミットをプッシュします(GitHub Docs)。1 つの作業に 1 つの pull request、というのが正しい形であり、継続もその形を守ります。

境界的なケースで起きることは次のとおりです。

• ブランチがもう存在しない(マージ後に削除された場合など)。継続した実行はデフォルトブランチから始まって新しい pull request を開き、フィードにはその旨を示すアンバー色の行が表示されます。「前回の実行のブランチ archyl/agent-4f1c2a9e をチェックアウトできませんでした。この実行はデフォルトブランチから始まり、新しいプルリクエストを作成します。」
• pull request がドラフトの場合。 ドラフトのままです。作業が終わったら、レビュー可能としてマークしてください。
• エージェントのブランチのみ。 Archyl が継続するのは Archyl のエージェントが作成したブランチ、つまり archyl/ 配下のブランチだけで、人が作ったブランチにコミットすることはありません。

2 つの実行は相互にリンクされます。新しい実行には 継続元の実行、前の実行には 継続先の実行 が表示されます。実行中の実行は継続できません。代わりにその行にコメントしてください。

継続した実行は、アーキテクチャのコンテキストも引き継ぎます。その作業セッションは、フォローアップだけでなく、前のタスクとフォローアップを合わせた内容で開かれるので、継続元の実行と同じアーキテクチャ要素とメモリにたどり着きます。これは見た目以上に重要です。「make seed にはデータベースの container が起動している必要があると書く」という行はサービスの名前をひとつも含んでおらず、この行だけで開いたセッションでは、照合できるものがほとんどありません。

できないこと

ワーカーにはシェルがありません。 ファイルの読み取り、書き込み、編集、一覧表示、検索はできますが、プロジェクトのビルドやテストの実行はできません。この例で言えば、Makefile は読めても、ドキュメントが正しいか確かめるために make build を実行することはできません。きれいな差分は、通ったビルドではありません。その役目は引き続き CI が担います。

行コメントはガイダンスであって、ゲートではありません。 解決済みの状態はなく、エージェントがコメントに対応したかどうかを確認する仕組みもありません。差分でエージェントの次の編集を見て、判断するのはあなたです。

継続用のメモは 1 つのブラウザにしか残りません。 実行を継続するまで、あなたが継続用に追加したコメントはチームメイトには見えません。作業中のエージェントに送ったコメントは別で、フィードに残り、全員が見られます。

計画のレビューは、誰かがいることを前提にしています。 これはプロファイル単位の設定で、既定ではオフです。そのプロファイルのすべての実行がこの設定に従い、スケジュール実行も例外ではありません。レビューがオンのプロファイルで午前 3 時に始まった実行は、1 時間待ってから、何も変更せずに失敗します。質問も 1 時間待ち、その後はエージェントが単独で判断します。

コネクタ経由のクローンは GitHub 専用です。 open_repository は GitHub のホスト型 MCP サーバーで動作します。それ以外のホストでは、リポジトリをプロジェクトにリンクしてください。

どこから始めるか

どうせレビューすることになる小さなタスクを選び、先に計画をレビューする をオンにしたプロファイルで実行してください。実行ページは開いたままにしておきます。承認する前に計画を編集してください。頼むつもりのなかったステップを削除するだけでもかまいません。変更 では、pull request で指摘していたはずの最初の行にコメントし、それが 送信待ち から 配信済み に変わるのを見てください。実行が終わったら、残りを継続用のコメントとして残し、継続 を押します。

スケジュールで使っているプロファイルでは、レビューのために起きている人がいない限り、計画のレビューはオフのままにしておいてください。

計画、質問、ライブ差分、行コメント、継続は、Archyl のマネージドエージェント実行の機能です。ここで挙げた設定とラベルはすべてマネージドエージェント実行のドキュメントに載っています。関連記事：これらの土台となる Guard と作業セッションについてはマネージドエージェントが Harness に従うようになりましたを、あわせてマネージドエージェント実行のリリースもご覧ください。