用途
该技能用于从 issue 跟踪器中取下一项工作,并将其推进到一个开放的 pull request。它执行一次完整流程:frontier → 选择 → 认领 → 分支 → 构建 → pull request → 停止。该技能执行 STD-002(issue 与 agent 工作流)和 STD-003(pull request 与分支)标准。当本文件与标准冲突时,以标准为准。
三条不可逾越的界限
- 永远不将 issue 移入 ready(STD-002 §3.5)。ready 意味着有人确认工作已足够明确,无需再询问任何人。如果 agent 自行提升一个规格不足的工单并认领它,就把规划失败变成了 pull request。如果认为某个 issue 已就绪,应在评论中说明,而不要动标签。
- 永远不合并自己的 pull request(STD-003 §3.12)。打开 pull request 就是本次流程的终点。
- 永远不从 frontier 之外取工作(STD-002 §3.11)。frontier 之外的工作要么未被接受,要么已被认领,要么被尚不存在的东西阻塞。
主要能力
1. 读取 frontier
frontier 是所有满足以下条件的 issue:ready、未分配、且没有开放的阻塞关系(STD-002 §3.11)。
使用命令列出:
gh issue list --label ready --state open --json number,title,body,labels,assignees,url \
--limit 100 | jq '[.[] | select(.assignees == [])]'
阻塞关系在跟踪器支持时原生记录,不支持时记录为 ## Blocked by 部分列出 issue 引用(STD-002 §3.10)。读取正文中的该部分,并丢弃任何阻塞者仍处于开放状态的 issue。
如果 frontier 为空,停止并说明。指出 backlog 中接近 ready 的内容以及各自缺少什么——这是有用的答案,是对人的分诊提示,而不是自行提升某物的邀请。
2. 选择并说明理由
这是判断。没有优先级标签,也没有排序规则;组织有意决定,选择下一项工作是对情境的解读而非排序(ADR-004)。要求的不是特定答案,而是一个被陈述的答案。
大致按以下顺序权衡:
- 它能解除什么阻塞。被多个其他 issue 阻塞的 issue 比其自身规模更有价值。这是唯一可以机械检查的因素——查看
## Blocked by部分中命名它的内容。 - 它是否可完成。一次流程就能推进到可审查 pull request 的工单,胜过会半途而废并持有认领的更大工单。
- 它是否消除实时故障。生产环境中损坏的东西优先于仅仅缺失的东西。
- 仓库当前的目标是什么。阅读 AGENTS.md 和最近的提交。推动既定当前目标的工作胜过仅仅整洁的工作。
- 延迟成本。有些工单等待越久越昂贵——任何阻塞人的事,任何即将被依赖变更超越的事。
然后写下理由。认领时,评论说明取了哪个 issue 以及判断它优先于什么。未记录的判断与选择第一行无法区分,下一个读者(通常是另一个 agent)无法判断选择是否经过考虑。
3. 竞态安全地认领
多个 agent 同时读取同一 frontier,因此第 1 步学到的内容已经过时。在认领时重新读取,并在写入后回读(STD-002 §3.7, §3.8)。
gh issue view "$N" --json assignees,state,labels \
| jq -e '.assignees == [] and .state == "OPEN"' || exit 0
gh issue edit "$N" --add-assignee "@me" --add-label active
gh issue view "$N" --json assignees \
| jq -e '[.assignees[].login] == ["'"$AGENT"'"]' || exit 0
如果任一检查失败,另一个会话赢了。静默地取下一个 issue。不要评论,也不要取消分配赢家。
一旦认领成立,评论。用一两句话说明发生了什么以及接下来会发生什么,并附上第 2 步的理由(STD-002 §3.12, §3.13)。不要开场白,不要热情,不要 emoji。
示例:
Claimed. Taking this ahead of #98 and #103 because both of those are blocked by it. Next: branch 142-preview-check-not-comment, then a pull request with the preview reachable from the check list.
4. 创建分支
命名为 <issue-number>-<slug>,从默认分支创建,在工作开始时创建(STD-003 §3.1, §3.2)。不要从另一个功能分支或过时的本地副本创建。
git fetch origin && git checkout -B "$(gh issue view "$N" --json title \
| jq -r '"'"$N"'-" + (.title | ascii_downcase | gsub("[^a-z0-9]+"; "-"))')" origin/HEAD
5. 执行工作
针对 issue 中的验收标准进行普通工作。处理工单时有两件特定事项:
- 如果 issue 结果并不 ready——标准矛盾、缺少决策、方法需要只有人才能给出的答案——停止并将其移至 blocked,附上评论准确说明需要什么以及来自谁(STD-002 §3.9)。blocked 意味着等待人。等待另一个 issue 是阻塞关系,不是标签。
- 如果它超出一次流程,在 issue 上说明并为已完成部分打开 pull request,标记为 draft,而不是静默持有认领。
6. 打开 pull request
成功标准优先——在 why 之上、diff 摘要之上、一切之上(STD-003 §3.6)。需要滚动才能发现变更本应实现什么的审查者,会审查代码而不是结果。
四个部分,按此顺序(STD-003 §4):
## Success criteria— 可检查的陈述,每项一个复选框## Why— Closes #N,以及之前哪里错了## What changed— 用散文描述 diff 的形态## Evidence— 将每个标准映射到证明它的表格
证据存在于 pull request 本身——附加的截图和录屏,或粘贴的命令输出——而不是在会过期的链接后面。对于不是功能构建的变更,证据可能简化为证明它的检查。
7. 停止
说明取了什么、为什么优先于其他内容、以及处于什么状态。然后停止。
由人合并(STD-003 §3.12)。如果仓库使用自动合并选择加入(STD-003 §3.13),仍由人应用。
再次运行是新一轮流程:回到第 1 步,针对已改变的 frontier。
适用场景
- 需要从 issue 跟踪器中自动选取并推进下一项工作的 agent 工作流。
- 遵循 STD-002 和 STD-003 标准的仓库。
- 多个 agent 并发读取同一 frontier 的场景,需要竞态安全的认领机制。
限制
- 不编写 issue。指定工作是分诊,分诊是 ready,是人的决定。
- 不决定排序规则。没有排序规则。参见 ADR-004 了解原因以及什么会改变答案。
- 不审查或合并。两者都需要作者以外的人。
- 不将 issue 移入 ready。
- 不合并自己的 pull request。
- 不从 frontier 之外取工作。