afk-loop

AFK ループ

チームが AFK エージェントをどのように運用するかを説明します。どの作業を任せるか、どのように割り当てるか、プルリクエストが届いたときに何を確認するか、実行がうまくいかなかったときにどうするかを取り上げます。

リポジトリの AGENTS.md が、この手順のもう半分です。エージェントが従う契約を定めており、このスキルはその周辺で人間が行う手順を説明します。

割り当ては意図的に手動です。 コーディングエージェントのコストとパフォーマンスを実際の運用で検証しているため、チームメンバーが各 Ready for Agent イシューを手動で Copilot に割り当てます。プロジェクトのフィールドが変更されてもワークフローは実行されないため、そもそも自動化の対象となるものはまだありません。エージェントが自ら作業を見つけて着手するようになれば、このファイルを読む人はいなくなるため、保守するのではなく削除してください。

作業の状態はボードの Status フィールドで管理します。詳しくは issue-tracker スキルを参照してください。

Copilot と Claude Code

作業を無人で実行できますか？

• Copilot — 誰も付き添わなくてよいほど、依頼内容が十分に明確です。変更内容が定義されており、誰かに尋ねなくても確認できる受け入れ条件があり、未決定の事項がありません。
• Claude Code — 人間が関与する必要のある作業です。調査が必要な不慣れな領域、作業中に表面化する判断事項、進行に合わせて指示したい作業などが該当します。

これが Ready for Agent で既に示されていることです。そのため、このステータスが付いたイシューは定義上 Copilot の候補です。issue-tracker スキルのトリアージの役割を参照してください。

エージェント向け依頼内容

イシューが Ready for Agent に移動したとき、triage が writing-lean を使って投稿する、構造化されたコメントです。 イシュー本文とディスカッションは背景情報です。依頼内容が契約です。エージェントが作業の基準とするものです。

依頼内容が完成しているのは、次のすべてが含まれている場合です。

• カテゴリと概要 — bug または enhancement と、必要な作業を説明する一文
• 現在の動作と期待する動作 — エッジケースやエラー条件も含めます
• 主要なインターフェース — 確認すべき型、シグネチャ、設定の形式を説明します。場所は示しません。イシューが数週間 Ready のままになる可能性があり、その間にコードツリーが変化するため、ファイルパスや行番号は記載しません
• 受け入れ条件 — 具体的かつ個別に検証でき、エージェントが完了を判断できるもの
• 対象外 — 変更してはならないもの

良い例と悪い例を含む完全なリファレンスは、Matt の triage スキルにある AGENT-BRIEF.md を参照してください。このファイルはこのリポジトリではなくスキルとともに配布されるため、Copilot のコンテナには含まれていません。そのため、上記のチェックリストをここに記載し、リンク先もローカルパスではなく GitHub にしています。

このファイルではラベルの用語（ready-for-agent）が使われていますが、現在はもう使用していません。これを Ready for Agent と読み替えてください。依頼内容のその他の点に変更はありません。

Copilot への割り当て

割り当てる前に、エージェント向け依頼内容を読んでください。 ステータスはキュー内の位置であり、依頼内容が割り当ての可否を決めます。割り当てを行う人は、エージェントが実行を開始する前に確認する最後の人間です。動作がどう変わるのか、どうすれば完了を確認できるのか、何を変更してはならないのかが明記されていないものは、割り当てないでください。

割り当てるには、次の手順を実行します。

1. GitHub でイシューを開きます。🤖 Frontier ビューに割り当て可能なイシューが表示されます。
2. Assignees で Copilot を選択します。
3. Status を In progress に設定します。
4. その後まもなく Copilot がドラフトのプルリクエストを開き、その中で作業を進めます。コミットをプッシュし、作業しながら自分のタスクリストにチェックを入れていきます。

コマンドラインからの割り当ては機能しません。Copilot はリポジトリの担当者一覧に含まれていないため、gh issue edit <n> --add-assignee Copilot は失敗します。UI を使ってください。

エージェントのプルリクエストをレビューする

実行が失敗した場合も含め、すべての実行はレビューを依頼して終了します。 レビュー依頼はエージェントが停止したことを意味するだけで、成功したという意味ではありません。そのため、コードを読む前にプルリクエストを分類してください。

実行が終了する3つの状態、それぞれに付与されるStatus、および各状態でエージェントが残すべきものは、リポジトリ独自のAGENTS.mdにある実行の終了方法に記載されています。この表は意図的にリポジトリごとに異なります。これに照らしてプルリクエストを確認し、次のように対応してください。

• Complete — 通常のプルリクエストと同じようにレビューし、イシューのエージェント向けブリーフに記載された受け入れ条件も確認します。
• Blocked — エージェントは、答えられなかった質問や実行できなかった操作を明示しています。解決したら、セッションで返信して実行を再開させます。停止しているのではなく、あなたの対応を待っている状態なので、作業は停止した箇所から再開します。
• Error — 自動的に再開することはありません。より適切なブリーフを用意してエージェントに再度依頼するか、人間に引き継ぐかを決め、その判断に合わせてStatusを設定します。

この3つの状態のどれにも当てはまらないプルリクエスト、たとえばレビュー可能な状態なのに空だったり、説明のないドラフトだったりするものは、レビュー対象ではなくエージェントの不備です。clhbid/clhbid.com#2254はその実例です。変更はなく、受け入れ条件にも何も対応していないのに、レビューが依頼されています。

Copilotが作成していないプルリクエストでは、説明とイシューの編集は自分で行ってください。その場合、Copilotにできるのはブランチへのプッシュとスレッドへの返信だけです。

実行がうまくいかない場合

• 実行を停止せずに誤った方向へ進んでいる実行を軌道修正するには、プルリクエストからセッションを開き、セッションログの下にあるプロンプトボックスに追加の指示を入力します。
• 実行中のセッションを停止するには、セッションログビューアーでセッションを停止を選択します。すでにプッシュされたコミットは保持されます。
• 問題のあるプルリクエストは、その場で修正せずにクローズし、次の試行に問題点が引き継がれるよう、イシューにコメントしてください。
• 割り当てを解除する前にステータスを設定します。 ディスパッチされたイシューは、成功、失敗、クローズのいずれの場合もCopilotへの割り当てが維持されます。また、フロンティアは割り当て済みのものをスキップするため、停滞したイシューはすでにキューから除外されています。割り当てを解除すると、キューに戻ります。その前に、今回の失敗でこの作業はエージェントに適していないと判明したかどうかを判断してください。該当する場合はReady for Human、再度引き継ぐには仕様が不十分な場合はWaiting on inputに設定します。Ready for Agentのまま割り当てを解除すると、次のディスパッチでも同じ失敗が繰り返されます。
• エージェントよりも先にブリーフを疑ってください。 実行がうまくいかない場合、その多くはブリーフに未解決の点が残っていたことが原因です。再発を防ぐには、ブリーフを修正する必要があります。