Whiteboard如何让AI写出RFC式文档？6步authoring提示词工作流深度拆解

Whiteboard如何让AI写出RFC式文档？6步authoring提示词工作流深度拆解

【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard

Whiteboard 是一款开源软件设计白板，它能引导 Claude Code、Codex 等 AI 编码代理按照内置的authoring 提示词工作流，自动把一次代码变更写成结构化的RFC 式设计文档：从"变更是什么、为什么改"，到组件级设计、数据流图，再到逐函数的实现讲解，全程实时绘制在画布上。本文将完整拆解这套提示词背后的 6 步流程与四大章节结构。

一、为什么 AI 写的文档常常像"流水账"？

让 AI 解释一次代码变更，它通常输出一大段文字：顺序混乱、深浅不一、图和代码脱节。Whiteboard 的解法是——把"怎么写"本身写成提示词。

这套提示词不是散落在系统提示里的几句口号，而是独立存放、按需下发给 agent 的 markdown 文件：

• 主工作流：packages/review/instructions/authoring.md
• 文件透镜规则：packages/review/instructions/file-lenses.md
• 草稿板规则：packages/review/instructions/scratchpad.md
• 代码溯源规则：packages/review/instructions/trace-archaeology.md

当 agent 调用session_get_instructions({topic:"authoring"})时，服务端会动态拼装这些内容，并根据"桌面端是否可用、草稿板是否开启、trace 是否启用"裁剪出当前机器真正适用的版本，逻辑见 renderInstructions。这正是它被称为"工作流"而非"模板"的原因。

二、6 步主流程：从"登记仓库"到"回读自检"

authoring.md 的第一段规定了严格的开场流程，并强调"严格按照这前六步执行，不要有多余的工具调用"：

第 1 步：登记仓库

先调用register the repository，把本地 Git 仓库注册到 Whiteboard，让后续所有代码引用都能解析到真实提交。

第 2 步：创建白板并"钉住"目标

提示词要求白板必须钉住（pin）到用户描述的 commits/PR 上。如果用户没点名，就用worktree目标对比默认分支；只看未提交改动时传base: "HEAD"。这一步保证了文档始终基于不可变的提交，而不是会漂移的分支。

第 3 步：派发子代理画"文件透镜"

提示词要求用一句精确到字的指令唤起子代理：

Callsession_get_instructions({topic:"file-lenses"})and follow it for whiteboard .

子代理会按 file-lenses.md 把所有变更文件分桶：先剔除测试、文档、锁文件、格式化等"非实现代码"，再把实现代码按设计职责（数据模型、API、UI 层）拆成几个"一眼读完"的透镜。得益于作用域隔离的租约机制（见 authoring-tools.ts 中activity_begin的scope:"lenses"说明），子代理可以一边写透镜，主代理一边写正文，互不冲突。

第 4 步：领取"作者租约"

主代理调用session_activity_begin（scope: "document"）获得排他写入权，并向用户广播"我正在画文档"。租约 3 分钟无写入即过期，读者据此判断评审是否"就绪"。

第 5 步：读 diff，然后立刻写第一稿

这是整个工作流最"反直觉"的一条：读完 diff 后，不做任何其他工具调用，立即写下 what/why 章节的第一稿。

• 如果 diff 列不出文件，说明目标定错了，要先用session_set_target修正再动笔
• 先写"结论"、再补细节，让画布上几秒内就出现可见进度

第 6 步：动笔前定结构，收稿前回读自检

动笔前按固定顺序建立四个顶级章节（见下文），收稿前则有一条硬性要求（authoring.md）：

read the whole whiteboard back and fix any contradictions/unverified claims.

把整块白板读回一遍，修正所有自相矛盾或无证据的论断——相当于给 agent 加了一道"自我 code review"。

三、RFC 文档的四大章节：一份提示词写出的目录

authoring.md 规定的章节顺序，几乎复刻了经典 RFC 的叙事弧线：

两个值得注意的细节：

1. 小变更可省略章节。Guidelines 明确说"尽量短小精悍，自由地省略章节"——提示词防止了模板化灌水。
2. 凡描述真实代码，默认挂代码链接。链接格式如[label](https://link.gitcode.com/i/3e20d414130e3b421337731e686f6caf)，行号必须经过验证（用base侧引用旧代码），这让文档里的每句话都能一键跳回源码。

四、选图的决策树：sequence / flow_diagram / database_lens

Design 章节要求"选一张最能体现变更形状的图"，提示词给出的选择逻辑非常清晰：

• 👉 参与者之间随时间交互（谁调用谁、异步交接）→sequence时序图
• 👉 亮点是分支、重试、状态迁移 →flow_diagram流程图
• 👉 亮点是数据表结构变更、谁读写 →database_lens数据库透镜
• 👉 变更主要是新增/修改的契约 → 直接用code_peek展示关键类型/接口

而 Implementation 章节则有固定搭配：

• call_stack_diff展示用户流的新旧调用路径对比，且必须"以用户/agent 入口点为根"（如一次按钮点击、一条 CLI 命令），沿途未变更的节点也要带上
• code_peek只留给"承载机制或不变量"的少数代码段，其余一律行内链接

五、实时视觉进度：写给"人"看的工程

Guidelines 里有一条加粗的IMPORTANT：

Write incrementally. The user sees you write on the canvas in real-time. Show them visual progress every few seconds.

配合session_activity_update定期汇报"当前在画哪个区域"，白板的绘制本身就是反馈：段落逐块落地、图逐节点描边（见 review-api README 中关于lastEdit绘制动画的说明）。这解决了 AI 长任务最大的体验痛点——黑盒等待。

六、其余三个指令主题：按需加载的能力

authoring只是 INSTRUCTION_TOPICS 之一，服务端还会按环境状态追加指引：

• file-lenses：Diff 视图的文件分桶规则（第 3 步子代理使用）
• scratchpad：不属于任何变更的"草稿板"，用于口头解释、跨文件流程草图；新想法置顶、像记日志一样书写，见 scratchpad.md
• trace-archaeology：通过whiteboard traceCLI 追溯"这段代码为什么存在"，把 what/why 改写成用户原始提示词的直接引文（instructions.ts 会在 trace 启用时自动附加此要求）

七、一句话总结：提示词工程在"流程"层的胜利

Whiteboard 的 authoring 工作流给出了三个可复用的启示：

1. 把"读-写-自检"编排成强约束流程，而不是把格式期望丢给模型自由发挥
2. 章节、图表选择、链接规范全部写成可执行的决策规则，让文档深度稳定在"资深工程师评审"的水位
3. 把生成过程可视化（租约 + 实时活动 + 增量绘制），让等待变成观看

想动手试试？克隆仓库后可以阅读完整源码：

git clone https://gitcode.com/gh_mirrors/whiteboard36/whiteboard

核心文件清单：authoring.md（主工作流）、instructions.ts（指令分发）、authoring-tools.ts（30+ 个画布工具的完整 schema）、review-api/README.md（服务端存储与租约机制）。

【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard