让 Agent 先问清楚、画出来、再证明：我的 Ryugi 工作流
内容提要
作者介绍其为编码代理开发的工具Ryugi：代理将设计决策写成文档、界面方案画在画板上、验收结果做成并排页面，用户的点选和评论直接回传代理会话。作者以博客编辑器白板为例，用一句话启动，经两轮设计问答、画板选型、19个任务实现、审查与验收页逐组通过，半天完成自研白板替换Excalidraw、发版及三个下游项目适配，聊天框发言不到20条。
延伸解读
把决策从聊天框搬到页面
作者在聊天框里只发了不到20条消息，大部分决策是在设计文档里点选、画板上挑方案、验收页上通过或驳回。这种方式让每个决定都留在页面上，后续实现和验收都对着页面来，不用翻聊天记录。对于需要频繁确认的编码任务，这能减少沟通成本，也方便回溯。
设计文档的提问与归属标注
agent 把问题嵌在设计文档正文里，每题附带推荐和理由，用户直接点选。每轮答完，结论并入“已定”一节，并标明是用户定的还是 agent 替用户定的。这样用户扫一眼就知道哪些需要再看。这种标注方式让决策来源清晰，避免混淆。
验收页并排对比与未验证项
验收页左边是批准的方案，右边是运行截图和录屏，用户逐组通过或驳回。有一组用户留评论后，agent 改完重新截图放回同一位置。agent 没能验证的部分单独列出，不混进“已完成”。这让验收更直观，也明确了边界。
流程的边界与人工介入点
这套流程不替用户做判断。开放题用户没填，agent 会按自己的理解补上并标出来。npm 发布需要用户本人登录验证，agent 替不了。验收页列出未验证部分，要不要补由用户决定。它做的是把需要判断的东西摆到面前，并让用户看出哪些已定、哪些还没有。
Q&A
Ryugi 是什么？它主要解决什么问题？
Ryugi 是作者为编码代理（coding agent）开发的一套 artifact 工具。它把代理需要用户决策的问题、方案选择、验收结果都放在可直接操作的页面上：设计决策写成文档供逐题选择或评论，界面方案画在画板上供点选，验收页将批准方案与运行截图并排供逐组通过或驳回。用户在页面上的每个选择都会直接回传到发起它的 agent 会话中，从而减少在聊天框中的来回沟通。
Ryugi 的工作流程大致分为哪几个阶段？
根据文章，Ryugi 的工作流程大致为：1）用户用一句话提出需求，代理阅读代码后生成一份包含问题的设计文档；2）用户在设计文档中逐题选择或评论，代理根据选择推进；3）界面方案通过画板展示，用户点选推荐项；4）批准后，代理将设计稿拆成多个小任务，按测试驱动开发（TDD）逐个实现；5）完成后由独立审查代理审查，并生成验收页（批准方案与运行截图并排）供用户逐组通过或驳回；6）最后发版并适配下游项目。
在 Ryugi 中，设计文档是如何帮助用户做决策的？
设计文档将需要用户决策的问题嵌入正文，每题附带推荐和理由，用户直接在页面上点选即可。第一题通常是分岔题，决定后续问题的方向。每轮答完后，结论会并入“已定”一节，并标明是用户定的还是代理替用户定的，方便用户快速识别哪些需要再看。代理不会在聊天框里追问，而是把所有问题集中到文档中。
Ryugi 如何确保实现结果符合预期？
Ryugi 通过多个环节确保实现符合预期：1）实现前，代理将设计稿切成小任务，每个任务先写失败测试再实现，并记录自主决策的台账；2）完成后，由未参与开发的审查代理冷读审查，列出问题并逐个补测试修复；3）生成验收页，左侧是用户批准的方案（画板或参考图），右侧是真实浏览器中的运行截图和录屏，用户逐组通过或驳回；4）代理未验证的部分单独列出，不混入“已完成”。
使用 Ryugi 时，用户还需要在聊天框里输入很多内容吗？
不需要。文章中的案例显示，整个半天的工作中，用户在聊天框里打的字不到 20 条，主要包括启动需求、批准、要求扩展、发版等关键指令。其余决策都是在设计文档里点选、在画板上挑选、在验收页上通过完成的。用户无需在聊天记录里翻找代理说过什么，每个决定都留在页面上，后续实现和验收都对着页面进行。
Ryugi 的边界是什么？它不做什么？
Ryugi 不替用户做判断。对于开放题，如果用户没有填写，代理会按自己的理解补上并标出来，用户可以选择是否查看。验收页会列出代理未验证的部分，是否补充由用户决定。Ryugi 的作用是把需要用户判断的东西摆到面前，并让用户一眼看出哪些已经定了、哪些还没有。此外，npm 发布需要用户本人登录验证，代理无法替代。
如何安装和使用 Ryugi？
Ryugi 是开源的，项目地址为 github.com/Innei/ryugi。在终端中运行 `npx ryugi-artifacts install`，选择你正在使用的 agent 即可安装。可以选择只安装 artifacts，或者安装完整的 brainstorm → spec → TDD 工作流。支持 Claude Code、Codex 等代理。
