afk-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The AFK loop

AFK 循环

How the team runs AFK agents: which work to hand over, how to dispatch it, what to check when a pull request lands, and what to do when a run goes wrong.

Your repo's

AGENTS.md

is the other half of this. It states the contract an agent works to; this skill is the human procedure around it.

Dispatch is manual on purpose. A team member assigns each

Ready for Agent

issue to Copilot by hand while we dogfood the coding agent's cost and performance. No workflow fires when a project field changes, so there is nothing to automate against yet in any case. Once agents pick work off the frontier themselves, this file loses its reader and should be deleted rather than maintained.

Work state is the

Status

field on the board — see the

issue-tracker

skill.

团队如何运行AFK Agent：哪些工作可以移交、如何分配任务、收到pull request时要检查什么，以及运行出错时该如何处理。

你所在仓库的

AGENTS.md

是这一流程的另一半。它定义了Agent需要遵守的工作契约；而本skill 是围绕这一契约的人工操作流程。

任务分配刻意采用手动方式。 在我们内部试用编码Agent、测试其成本与性能期间，团队成员会手动将每个标记为

Ready for Agent

的issue分配给Copilot。项目字段变更时不会触发任何工作流，因此目前也没有可自动化的对象。一旦Agent能够自行从前沿任务队列中领取工作，本文档就不再有受众，应当直接删除而非维护。

工作状态由看板上的

Status

字段标识——参见

issue-tracker

skill。

Copilot or Claude Code

选用Copilot还是Claude Code

Can the work run unattended?

Copilot — the brief is complete enough that nobody needs to be present. A defined change, acceptance criteria that can be checked without asking anyone, no decisions left open.
Claude Code — the work needs a human in the loop: an unfamiliar area to explore, decisions that will surface mid-flight, or anything you would want to steer as it happens.

That is the question

Ready for Agent

already answers, so an issue carrying that status is a Copilot candidate by definition. See Triage roles in the

issue-tracker

skill.

这项工作能否无人值守运行？

Copilot — 任务简报足够完整，无需人员在场。变更明确，验收标准无需咨询他人即可验证，没有待决策的事项。
Claude Code — 工作需要人在回路：需要探索不熟悉的领域、执行过程中会出现待决策的问题，或是任何你希望在运行时能够引导方向的任务。

这个问题

Ready for Agent

状态已经给出了答案，因此处于该状态的issue按定义就是Copilot的候选任务。参见

issue-tracker

skill中的分诊角色部分。

The agent brief

Agent任务简报

A structured comment posted on the issue when it moves to

Ready for Agent

, written by

/triage

with

writing-lean

. The issue body and discussion are context; the brief is the contract — it is what the agent works from.

A brief is complete when it has all of:

Category and summary —
```
bug
```
or
```
enhancement
```
, and one line on what needs to happen
Current and desired behaviour — including edge cases and error conditions
Key interfaces — types, signatures and config shapes to look for, described rather than located. No file paths, no line numbers: an issue may sit ready for weeks and the tree will move under it
Acceptance criteria — concrete and independently verifiable, so the agent can tell it is done
Out of scope — what must not change

The full reference, with worked good and bad examples, is

AGENT-BRIEF.md

in Matt's

/triage

skill. It ships with the skills rather than this repo, so it is absent from a Copilot container — which is why the checklist above is inlined, and why that link points at GitHub rather than a local path.

It is written in label vocabulary (

ready-for-agent

), which we no longer use. Read that as

Ready for Agent

; everything else about a brief is unchanged.

当issue转为

Ready for Agent

状态时，会在issue下发布一条结构化评论，由

/triage

配合

writing-lean

生成。 issue正文和讨论是背景信息；任务简报才是契约——Agent是基于任务简报开展工作的。

一份完整的任务简报需要包含以下所有内容：

类别与摘要 — 标明是
```
bug
```
还是
```
enhancement
```
，并用一句话说明需要完成的事项
当前行为与期望行为 — 包括边界情况和错误场景
关键接口 — 需要关注的类型、签名和配置结构，只需描述特征而非指定具体位置。不要写文件路径，也不要写行号：一个issue可能会在就绪状态停留数周，代码树会发生变化
验收标准 — 具体且可独立验证，让Agent能够判断任务是否完成
排除范围 — 明确哪些内容_不能_改动

包含正反示例的完整参考文档位于Matt的

/triage

skill中的

AGENT-BRIEF.md

。该文档随skills包发布，而非存放在当前仓库中，因此Copilot容器中没有这份文件——这也是为什么上面的检查清单被直接内嵌在这里，以及链接指向GitHub而非本地路径的原因。

该文档使用的是标签命名格式（

ready-for-agent

），我们已经不再使用这种写法。请将其理解为

Ready for Agent

；任务简报的其他所有内容都没有变化。

Dispatching to Copilot

分配任务给Copilot

Read the agent brief before you assign. The status is a queue position; the brief is the gate. The person dispatching is the last human to look before an agent spends a run, so refuse anything that doesn't say what changes in behaviour, how you would know it's done, and what must not change.

To dispatch:

Open the issue on GitHub — the 🤖 Frontier view lists what is dispatchable.
Under Assignees, choose Copilot.
Set
```
Status
```
to
```
In progress
```
.
Copilot opens a draft pull request shortly afterwards and works in it, pushing commits and ticking off its own task list as it goes.

Assigning from the command line does not work — Copilot isn't in the repo's assignee list, so

gh issue edit <n> --add-assignee Copilot

fails. Use the UI.

分配前请先阅读Agent任务简报。 状态只是队列中的位置；任务简报才是准入门槛。分配任务的人是Agent运行前最后一个检查的人类，因此任何没有说明行为会如何变更、如何判断任务完成、哪些内容_不能_改动的任务，都应当驳回。

分配步骤：

在GitHub上打开issue——🤖 Frontier 视图会列出所有可分配的任务。
在Assignees（经办人）下方，选择Copilot。
将
```
Status
```
设为
```
In progress
```
。
之后Copilot会很快创建一个draft pull request（草稿pull request）并在其中工作，推送提交，同时逐步勾选自己的任务清单。

无法通过命令行分配任务——Copilot不在仓库的经办人列表中，因此

gh issue edit <n> --add-assignee Copilot

会执行失败。请使用UI操作。

Reviewing an agent's pull request

审核Agent的pull request

Every run ends by requesting review, including the runs that failed. A review request means the agent stopped, not that it succeeded — so classify the pull request before reading any code.

The three states a run can end in, the

Status

each carries, and what the agent must leave behind in each are in How a run ends, in the repo's own

AGENTS.md

— that table is deliberately per-repo. Read the pull request against it, then act:

Complete — review it as you would anyone's pull request, and against the acceptance criteria in the issue's agent brief. The pull request template asks about this directly.
Blocked — the agent named a question it could not answer or an action it could not take. Resolve it, then reply in the session so the run carries on. It is waiting on you, not stalled, and the work resumes where it stopped.
Error — nothing resumes on its own. Decide whether the work goes back to an agent with a better brief or to a human, and set the
```
Status
```
to match that decision.

A pull request in none of the three states — ready for review but empty, or draft with no explanation — is an agent defect rather than something to review. clhbid/clhbid.com#2254 is the worked example: no changes, no acceptance criteria addressed, review requested anyway.

每次运行结束都会发起审核请求，包括运行失败的情况。 审核请求仅表示Agent已经停止运行，不代表任务成功——因此在阅读任何代码之前，先对pull request进行分类。

运行可能结束的三种状态、对应的

Status

值，以及每种状态下Agent必须留下的产出，都在仓库自身

AGENTS.md

的运行如何结束部分中——该表格是特意按仓库定制的。对照该表格检查pull request，然后采取相应行动：

Complete（完成） — 像审核任何人的pull request一样审核它，并对照issue的Agent任务简报中的验收标准检查。pull request模板会直接询问这一点。
Blocked（受阻） — Agent提出了它无法回答的问题，或是无法执行的操作。解决该问题，然后在会话中回复，让运行继续进行。它是在等待你的处理，而非停滞不前，工作会从停止的地方继续。
Error（错误） — 无法自动恢复运行。判断是应该提供更完善的任务简报后重新交给Agent，还是转交给人类处理，然后设置对应的
```
Status
```
。

如果一个pull request不属于上述三种状态——比如已请求审核但内容为空，或是没有任何说明的草稿——那这是Agent的缺陷，而非需要审核的内容。clhbid/clhbid.com#2254是一个实际案例：没有任何变更，也没有满足任何验收标准，却仍然发起了审核请求。

When a run goes wrong

运行出错时的处理

Steer a run that's heading the wrong way without stopping it: open the session from the pull request and type a follow-up in the prompt box below the session log.
Stop a run in flight with Stop session in the session log viewer. Commits already pushed are kept.
Close a bad pull request rather than fixing it in place, and comment on the issue with what went wrong so the next attempt starts with it.
Set the status before you unassign. A dispatched issue stays assigned to Copilot — through success, failure, and closure — and the frontier skips anything assigned, so a stalled issue is already out of the queue. Unassigning is what puts it back. Before you do, decide whether the failure showed the work isn't agent-suitable after all: set
```
Ready for Human
```
, or
```
Waiting on input
```
when it isn't specified well enough to hand over again. Unassign it still on
```
Ready for Agent
```
and the next dispatch walks into the same failure.
Suspect the brief before the agent. A run that goes wrong usually traces back to a brief that left something open, and fixing the brief is what stops it recurring.

引导方向跑偏的运行 无需停止它：从pull request中打开会话，在会话日志下方的输入框中输入后续指令即可。
停止正在进行的运行 使用会话日志查看器中的**Stop session（停止会话）**按钮。已经推送的提交会被保留。
关闭有问题的pull request 而不是直接在上面修改，然后在issue下评论说明出错原因，以便下一次尝试时参考。
取消分配前先设置状态。 已分配的issue会一直分配给Copilot——无论成功、失败还是关闭——前沿队列会跳过所有已分配的任务，因此停滞的issue已经不在队列中了。取消分配才会让它重新回到队列。在取消之前，先判断这次失败是否说明该任务根本不适合Agent处理：如果是，设置为
```
Ready for Human
```
；如果是任务说明不够完善、无法再次分配，则设置为
```
Waiting on input
```
。如果在
```
Ready for Agent
```
状态下直接取消分配，下一次分配还是会遇到同样的失败。
先怀疑任务简报，再怀疑Agent。 运行出错通常可以追溯到任务简报有遗漏的地方，修复任务简报才能避免问题重复发生。