给 agent 加人工确认层的具体工程实现,工作流设计可直接借鉴。
ai_agent工具工程实践
Ryugi (流儀)
—Ryugi is a set of interactive artifacts I built for coding agents. Whenever the agent needs to ask me questions or have me pick an approach, it puts them on interactive pages where I can answer directly: design decisions are written up as a document where I choose options item by item and leave sentence-level comments; UI proposals are laid out on a canvas for me to click and choose; and when the work is done, an acceptance page places approved designs side by side with live screenshots so I can approve or reject them group by group. Every choice I make on these pages feeds right back into the agent session that started it.
Repository
· Innei
503
ryugi
Ryugi (ryoo-ghee) — artifacts for coding agents: artboards of mockups, design docs, whiteboards, HTML benches and verify reports you comment on, with every comment sent back to the agent. Install artifacts only, or the full brainstorm → spec → TDD workflow. Claude Code, Codex and more.
JavaScript
The project here was the whiteboard inside my blog editor, haklex. Its editing features had always leaned on Excalidraw, which pulled in a heavy bundle and clashed with the rest of the editor's visual style. I wanted to drop the dependency and roll our own whiteboard around Excalidraw's data format, without touching a single field in existing articles.
From my opening sentence to `git push` took about half a day: two rounds of development, one release, and three downstream projects updated. I typed fewer than 20 messages in chat; wherever I had to make a call, it was turned into questions in a doc or mockups on a canvas. Here is how it went, step by step.
After one prompt: a doc that asks questions
My opening prompt was just one sentence: "Drop the excalidraw dependency and roll our own whiteboard based on its data structures."
The agent first inspected the code to confirm the scope of changes, then opened a design doc and put its questions directly into it, without following up in the chat box.
The questions were embedded right inside the document, each with a recommended option and the reasoning behind it; all I had to do was click my choice on the page. The first question was a fork in the road that determined how big v1 should be—everything that followed depended on it. For two of the questions I skipped the recommendation, and the next round simply picked up from what I chose.
After each round, the conclusions were merged into a "Decided" section, noting whether I made the decision or the agent made it for me. I could tell at a glance which items needed another look.
Section 4 of the design doc, "Decided": each conclusion is tagged with who decided it
After two rounds, the document was fleshed out into a full design spec. Before handing it back to me, the agent had an uninvolved reviewer agent do a cold read; it resolved most of the feedback on its own, leaving just two questions for me to settle.
自研白板编辑器:替换 @excalidraw/excalidraw · Ryugi
View “自研白板编辑器:替换 @excalidraw/excalidraw” on Ryugi Cloud, a document artifact.
Ryugi
"Should we discuss the UI?"
Once the document Q&A was done, I asked: "Should we discuss the UI?" The agent said yes—the design spec had marked the UI as "left to the implementer," but these are things you see every time you open the editor.
Text doesn't do UI justice, so it switched to a visual canvas: each group presented several options side by side, the recommended one highlighted with a red border, and sticky notes explaining the reasoning right beside them.
Round 1 decision fork on the UI canvas: three layout options side by side, with the recommended one outlined in red
Across two rounds and five groups, I went with the recommendations every time. With the options drawn out side by side, it was immediately clear which were good and which were bad. The selected mockups were linked into the design spec to guide both implementation and acceptance. Then I replied with "approve."
白板编辑器界面 · Ryugi
View “白板编辑器界面” on Ryugi Cloud, an artboard artifact.
Ryugi
Once approved, I didn't look at code again
Once approved, the agent broke the design spec into 19 small tasks and tackled them one by one on a separate branch.
Each task followed the same rhythm: write a failing test, watch it fail, write the implementation to make it pass, and commit. Whenever the agent made a call on its own—like minor details that diverged slightly from the spec—it logged it in a ledger. When the chat grew too long and was summarized, it kept working right from that ledger.
For over an hour, I didn't type a single word.
Review, then the acceptance page
Once all 19 tasks were finished, the agent handed the branch over to an independent reviewer agent that had played no part in development. For every issue flagged, it reproduced it with a failing test before writing the fix.
Then it spun up the editor in a real browser, took screenshots and screen recordings, and put together an acceptance page: my approved canvas designs on the left, and how it actually looked running on the right.
Acceptance page: approved design, live screenshot, and screen recording side by side
All I had to do was review each group and approve or reject it. I left a comment on one mockup; it made the fix, took a new screenshot, and placed it right back in the same spot for me to review. Anything it couldn't verify was listed separately on the page, instead of being mixed in with "Completed."
白板编辑器界面 · Ryugi
View “白板编辑器界面” on Ryugi Cloud, an artboard artifact.
Ryugi
Round two: starting from a reference image
Next, I wanted the whiteboard to look sharper. I pasted a reference image featuring clean headings, drop-shadowed sticky notes, and illustrative stickers, and asked whether stock Excalidraw could pull off that aesthetic.
It broke down the elements in the image one by one—what we could already draw, what capabilities were missing—and even guessed I might want an AI to do the drawing. I replied with one sentence: only build general-purpose drawing capabilities.
Next was the same process: open a new design doc, then three rounds of Q&A. In round three, putting rich-text cards on the whiteboard was my own idea. After a cold read, the reviewer agent flagged two questions that needed my call; the agent added its recommendations, I replied with two numbers, approved, and let it implement and review.
The acceptance page for this round measured directly against my reference image: the reference on the left, the recreation inside our editor on the right.
Round 2 acceptance: reference image side by side with the in-editor recreation
白板绘制能力扩展:阴影、SVG 元素、富文本卡片 · Ryugi
View “白板绘制能力扩展:阴影、SVG 元素、富文本卡片” on Ryugi Cloud, a document artifact.
Ryugi
Verify · 白板绘制能力扩展 · Ryugi
View “Verify · 白板绘制能力扩展” on Ryugi Cloud, an artboard artifact.
Ryugi
Release, then downstream projects
With both rounds approved, I asked: "Can we release now, and then adapt the downstream projects?" It cut a new release, then went through three projects using the editor one by one—bumping the dependency, running tests, and verifying in a browser that the whiteboard rendered properly.
Downstream results were posted right on the acceptance page as well, with one screenshot for light mode and one for dark.
The same whiteboard in downstream projects: light and dark mode
Throughout the entire process, logging in to authenticate the npm release was the only thing that needed my manual login—that was the one step the agent couldn't do for me.
What I actually said in the chat
Looking back, nearly everything I typed in chat over that half-day is captured right here:
Time
What I said
What happened next
12:26
Drop the excalidraw dependency and roll our own whiteboard based on its data structures
Read code, opened design doc
13:04
Should we discuss the UI?
Opened canvas for UI discussion
13:18
approve
Sliced tasks, started implementation
16:35
This looks about ready. Now let's work on extra features.
Compared against reference image, kicked off Round 2
16:38
Let's only build general-purpose drawing capabilities
Narrowed scope, opened new doc
17:04
approve
Implemented Round 2
17:56
Can we release now, and then adapt the downstream projects?
Published release, adapted downstream projects
20:06
push
Pushed to remote
Every other decision was made by clicking options in docs, picking mockups on a canvas, or signing off on the acceptance page. I didn't have to scroll through chat history to find what the agent said; every decision stayed on the page, and all the implementation and acceptance were checked against those same pages.
Boundaries
This workflow doesn't make judgment calls for me. If I skip an open-ended question, it fills in its best guess and flags it, leaving me to decide whether to review it. The acceptance page lists what it couldn't verify, and deciding whether to test further is up to me. What it does is put decisions right in front of me, so I can see at a glance what is settled and what isn't.
Ryugi is open source (
github.com/Innei/ryugi
). In your terminal, run
npx ryugi-artifacts install
, and select the agent you use to install it. The two design docs, canvas, and acceptance pages mentioned here are all public, so you can see them in their original form.