Whiteboard如何让AI写出RFC式文档6步authoring提示词工作流深度拆解【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboardWhiteboard 是一款开源软件设计白板它能引导 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_beginscope: document获得排他写入权并向用户广播我正在画文档。租约 3 分钟无写入即过期读者据此判断评审是否就绪。第 5 步读 diff然后立刻写第一稿这是整个工作流最反直觉的一条读完 diff 后不做任何其他工具调用立即写下 what/why 章节的第一稿。如果 diff 列不出文件说明目标定错了要先用session_set_target修正再动笔先写结论、再补细节让画布上几秒内就出现可见进度第 6 步动笔前定结构收稿前回读自检动笔前按固定顺序建立四个顶级章节见下文收稿前则有一条硬性要求authoring.mdread the whole whiteboard back and fix any contradictions/unverified claims.把整块白板读回一遍修正所有自相矛盾或无证据的论断——相当于给 agent 加了一道自我 code review。三、RFC 文档的四大章节一份提示词写出的目录authoring.md 规定的章节顺序几乎复刻了经典 RFC 的叙事弧线章节写什么关键约束What/Why这次变更是什么、为什么改简洁给 staff 工程师看的密度Requirements需求尽量用用户原话写成短要点没有上下文就整节省略Design组件、数据与控制流层面的方案讲组件不讲函数附关键决策、取舍与备选方案Implementation函数与文件层面的落地从入口点开始按读者应跟随的顺序走读变更代码两个值得注意的细节小变更可省略章节。Guidelines 明确说尽量短小精悍自由地省略章节——提示词防止了模板化灌水。凡描述真实代码默认挂代码链接。链接格式如[label](https://link.gitcode.com/i/3e20d414130e3b421337731e686f6caf)行号必须经过验证用base侧引用旧代码这让文档里的每句话都能一键跳回源码。四、选图的决策树sequence / flow_diagram / database_lensDesign 章节要求选一张最能体现变更形状的图提示词给出的选择逻辑非常清晰 参与者之间随时间交互谁调用谁、异步交接→sequence时序图 亮点是分支、重试、状态迁移 →flow_diagram流程图 亮点是数据表结构变更、谁读写 →database_lens数据库透镜 变更主要是新增/修改的契约 → 直接用code_peek展示关键类型/接口而 Implementation 章节则有固定搭配call_stack_diff展示用户流的新旧调用路径对比且必须以用户/agent 入口点为根如一次按钮点击、一条 CLI 命令沿途未变更的节点也要带上code_peek只留给承载机制或不变量的少数代码段其余一律行内链接五、实时视觉进度写给人看的工程Guidelines 里有一条加粗的IMPORTANTWrite 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-lensesDiff 视图的文件分桶规则第 3 步子代理使用scratchpad不属于任何变更的草稿板用于口头解释、跨文件流程草图新想法置顶、像记日志一样书写见 scratchpad.mdtrace-archaeology通过whiteboard traceCLI 追溯这段代码为什么存在把 what/why 改写成用户原始提示词的直接引文instructions.ts 会在 trace 启用时自动附加此要求七、一句话总结提示词工程在流程层的胜利Whiteboard 的 authoring 工作流给出了三个可复用的启示把读-写-自检编排成强约束流程而不是把格式期望丢给模型自由发挥章节、图表选择、链接规范全部写成可执行的决策规则让文档深度稳定在资深工程师评审的水位把生成过程可视化租约 实时活动 增量绘制让等待变成观看想动手试试克隆仓库后可以阅读完整源码git clone https://gitcode.com/gh_mirrors/whiteboard36/whiteboard核心文件清单authoring.md主工作流、instructions.ts指令分发、authoring-tools.ts30 个画布工具的完整 schema、review-api/README.md服务端存储与租约机制。【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考