如何把一条 issue 从请求跑到完成

issue 是 Rudder 把人类意图变成可检查 agent 工作的主要方式。这篇指南讲实际操作：什么时候创建 issue、什么时候分配执行者、什么时候加 reviewer、状态怎么设，以及怎么关闭。

​

默认旅程

大多数有用的 Rudder 工作会走这条路径：

1. 在 Chat 中捕获请求，或直接创建 issue。
2. 放进 backlog 里塑形，直到结果和上下文清楚。
3. 当执行者不需要再讨论产品意图就能开始时，移到 todo。
4. 下一步属于一个 agent 或人时，分配唯一执行者。
5. Assignee checkout 后进入 in_progress。
6. 下一步属于其他人或外部条件时，移到 blocked。
7. 输出准备好被判断时，移到 in_review。
8. 证据被接受后，再关闭为 done。

​

Backlog 还是 todo？

问题真实、但还没准备好执行时，用 backlog。 好的 backlog 示例：

• “改善 onboarding docs”，但还没有验收标准。
• “调查为什么截图数据看起来很假。”
• “也许应该加一个 Calendar 页面”，但还没定义它回答什么用户问题。

工作已经可以执行时，用 todo。 好的 todo 示例：

• “把安装截图命令替换成 npx @rudderhq/cli@latest start。”
• “新增 Calendar 概念页面，解释 run-history 使用场景。”
• “用非空 agent transcripts 重新生成 docs 截图。”

​

什么时候分配执行者

当一个 agent 或人应该执行下一步时，再给 issue 分配 assignee。 可以立即分配的情况：

• issue 在 todo
• 执行者有需要的 runtime、仓库或上下文
• 重复执行会浪费时间或产生冲突
• 你希望 heartbeat 自动接手

先不要分配的情况：

• 工作还模糊
• 多个执行者需要拆分不同部分
• 下一步其实是人类决策
• 权限或凭据缺失

Rudder 有意让一个 issue 只有一个 assignee。如果 Growth、Engineering 和 QA 都要参与，就创建多个 issue 或子 issue。

​

什么时候加 reviewer

关闭 issue 需要独立判断时，加 reviewer。 适合 reviewer 的工作：

• 公开文档、发布说明、营销文案和 UX copy
• 影响用户可见流程的代码改动
• 数据迁移、发布操作和预算敏感工作
• agent 生成、需要产品判断的 proposal
• done 应该表示“结果被接受”，而不是“有人尝试过”

可以不加 reviewer 的工作：

• 低风险记录整理
• 会变成另一个 issue 的探索笔记
• 关闭评论已经足够作为证据的小型内部修复

有输出可以判断时，再把 issue 移到 in_review，让 reviewer 留下明确结论。

​

Agent reviewer 如何工作

一条 issue 可以同时有 agent assignee 和 agent reviewer。适合这种设置的情况是：你希望一个 agent 负责产出，另一个 agent 用不同职责、技能、模型、runtime 或权限边界来检查结果。 Assignee 和 reviewer 不会在同一条 issue 上同时执行同一种工作：

1. issue 处于 todo 或 in_progress 时，assignee agent 负责执行。
2. Assignee checkout issue，完成工作，并留下关闭证据。
3. 输出准备好被判断后，issue 进入 in_review。
4. Rudder 可以把 reviewer agent 作为 reviewer 唤醒，而不是作为 assignee 唤醒。
5. Reviewer 阅读 issue 上下文、run transcript、评论、产物和验证证据。
6. Reviewer 留下结构化结论：通过、要求修改、需要跟进或阻塞。
7. 如果要求修改，下一步执行会带着 reviewer feedback 回到 assignee。
8. 如果 reviewer 通过，issue 可以带着执行证据和评审证据关闭为 done。

这样 agent-to-agent 协作是可检查的。实现 agent 不会默默把自己的输出判定为完成；review agent 也不会接管实现，除非 issue 被明确重新分配，或拆成新的 follow-up issue。 适合 agent reviewer 的场景：

• 工程 agent 实现代码改动；QA 或 reviewer agent 检查测试、风险和证据。
• Docs agent 撰写公开文档；产品 reviewer agent 检查表达清晰度、定位和缺失用例。
• Release agent 准备版本或 changelog；release reviewer agent 检查命令、产物和回滚风险。
• 数据或迁移 agent 产出方案；安全 reviewer agent 检查组织边界、不可逆步骤和备份证据。

如果判断依赖业务优先级、客户承诺、法律解释、预算批准，或 agent 不应该持有的凭据，就用人类 reviewer。

​

状态最佳实践

​

如何阅读下面的用例

下面这些例子来自真实 Rudder 工作场景，已经做过脱敏改写。阅读重点是路由判断：来了什么信号，应该沉淀成哪条 issue，下一步归谁，谁判断结果，以及什么证据可以关闭。

​

用例：Chat 图片附件 bug

用户在 Chat 里发了一张截图，然后问：为什么 Codex agent 还要在 transcript 里运行一条可见的 curl ... Authorization ... 命令才能读取图片？这是具体的信任问题：transcript 暴露了实现细节，让用户觉得 agent 原生看不了图。

1. 把 Chat 反馈沉淀成 bug issue：“Optimize Chat image attachment handling for Codex runtime”。
2. 只有在证据还没收集完时，才放在 backlog：截图、受影响 runtime、当前 prompt、失败的用户旅程。
3. 期望行为清楚后移到 todo：图片附件应该先由 Rudder 准备给 runtime，用户可见 transcript 里不应该出现带认证信息的下载命令。
4. 分配一个工程 agent，因为下一步会跨 server prompt、runtime handoff 和测试。
5. 加 reviewer，因为这会改变用户可见 Chat 流程和 transcript 隐私预期。
6. 只有当 issue 里有证据时才进 in_review：prompt 行为、runtime bridge、transcript 截图，以及证明原始下载命令已经消失的测试。
7. Reviewer 接受行为和证据质量后，才能关闭为 done。

​

用例：Backlog 评论唤醒了错误 agent

一个 backlog issue 已经挂着 engineer assignee。Operator 评论时只 mention 了 designer，但 engineer 也被唤醒开始运行。这里已经破坏了 backlog 的含义，不只是多发了一条通知。

1. 创建高优先级 bug issue：“Backlog issue comment should not auto-wakeup assignee”。
2. 原来的 backlog issue 只作为证据，不要直接在那里面修。
3. 规则清楚后移到 todo：backlog 普通评论不能唤醒 assignee；显式 mention 只唤醒被 mention 的 agent。
4. 分配给负责 wakeup 语义的工程 agent。
5. 加 reviewer，因为它影响“agent 什么时候允许开始运行”的控制面不变量。
6. 只有在复现无法确认，或状态语义还没决定时，才使用 blocked。
7. 当测试覆盖 backlog 普通评论、显式 mention、非 backlog assignee wakeup 后，进入 in_review。

​

用例：Chat 需要结构化提问组件

Operator 希望 Chat 像 Codex 一样，在缺少关键决策时弹出一到三个结构化问题，让用户选择后继续。产品决策很具体：只使用一个持久化 kind，ask_user，不要同时出现 ask_user 和 user_input_request 两套命名。

1. 产品契约还没定时先放 backlog：payload 结构、未回答状态、历史显示方式、非目标。
2. 验收标准足够具体后，移到 todo。
3. 分配一个工程 agent，因为 schema、server 解析和 UI 渲染需要一致落地。
4. 加人类 reviewer，因为这是用户交互行为，不只是代码管道。
5. 活跃面板、已回答历史状态、后续 assistant turn 都能看到时，移到 in_review。
6. Reviewer 接受 UX 后再关闭：这个组件应该只在缺少阻塞性决策时出现，而不是把所有普通澄清都组件化。

​

用例：带截图的文档站整改

需求是搭建公开官网文档：双语导航、结合用例的讲解、产品截图。它应该是一个 parent issue，而不是一个巨大的单 assignee issue。

1. Parent issue 只描述最终结果：“ship public Rudder docs that explain why and how to use the product”。
2. 拆成可以独立关闭的子 issue：
   • 内容结构和双语文档
   • 英文产品截图
   • 导航和下一步链接
   • 视觉 QA 和 broken-link 验证
3. 每个子 issue 只有一个 owner。不要把 writer、截图生产者、QA reviewer 都塞到同一个 issue 里当共同 assignee。
4. 需要判断质量的地方加 reviewer：公开定位、截图质量、Mintlify 导航。
5. 子 issue 都有关闭证据后，parent 才进入 in_review。
6. 最终 docs preview、截图、验证命令和剩余风险都链接回 parent 后，再关闭 parent。

​

用例：Windows 安装验证

issue 内容是：“在 Windows 下测试 npx 安装命令，并用 Claude Code 跑起来。” 这件事很具体，但不应该自动分配给本地 macOS agent。

1. 测试命令和期望结果已知时，可以放进 todo。
2. 只有当某个人或 agent 真有 Windows 环境时，才分配执行者。
3. 如果没有合适 runtime，就保持未分配或分配给人类 owner。
4. 缺少 Windows 机器、凭据或安装包时，移到 blocked。
5. 关闭证据要包含：终端输出、OS 版本、实际命令、失败截图（如果有），以及 docs 命令是否需要修改。

​

关闭前检查

标记 done 前确认：

• 输出可以从 issue 中看到
• 验证证据已经包含
• 有 reviewer 时，reviewer 决定已记录
• 剩余风险已说明
• 后续工作已创建，或明确决定不做
• Calendar 和 activity history 指向真实工作，而不是孤立对话

​

下一步