Reference · Model-invoked · Standalone（主流程 step 2 岔路）

prototype 速查

「一次性代码回答一个设计问题」的口袋版。完整教学见 Lesson 0008； 原文见 SKILL.md、 LOGIC.md、 UI.md、 docs。

一句话

Prototype = throwaway code that answers a question。问题决定形状。 不是 MVP、不是产品雏形——一开始加固（hardening）它，你就已经不是在做原型了。

何时伸手 / 何时别伸手

情境去哪
「状态机 / 数据形状 / API 手感，纸上说不清」prototype → LOGIC 分支
「这页面该长什么样，想看几种方案」prototype → UI 分支
「造好的东西坏了，想知道为什么」diagnosing-bugs（prototype 管「造什么」，不管「为什么坏」）
「想法还模糊，需求没聊清」grill-with-docs
「要读一手文档 / 第三方资料」research（读出 Markdown；prototype 跑出代码）
「不知道走哪条流程」ask-matt

第一刀：选分支

问题关于逻辑 / 状态 / 数据形状（想按按钮看状态变）
    → LOGIC.md：终端交互小程序
问题关于「该长什么样」（想并排看几种长相）
    → UI.md：同路由多变体 + 浮动切换栏
读不出 → 看周围代码（后端模块→LOGIC；页面/组件→UI）
还模糊且联系不上用户 → 按周围代码默认，假设写在原型顶部
选错分支 = 整个原型白做

六条共用规则

  1. Throwaway from day one，且标明：贴着使用位置放；命名让人一眼认出是原型；服从项目已有约定，不发明顶层结构
  2. One command to run：挂进已有任务运行器；没有就写在 README 顶部
  3. No persistence by default：状态在内存；持久化是被检验对象不是依赖；非用不可就建「PROTOTYPE — wipe me」临时库
  4. Skip the polish：无测试、错误处理从简、无抽象
  5. Surface the state：每动作 / 每切换，亮出全部相关状态
  6. Capture it when done：见下

LOGIC 分支骨架

  1. 先写下问题（README / 文件顶部，一段话）——答错问题的原型是纯浪费
  2. 用宿主项目的语言和工具链，不引新运行时
  3. 逻辑收进可搬走的纯模块（无 I/O、无终端代码、单向依赖：TUI→逻辑）： 四种形状按问题选 —— pure reducer (state, action) => state / 显式 state machine / 一组纯函数 / 有清晰方法面的类
  4. 最小 TUI：每拍清屏整帧重绘（不滚屏）；帧 = ① 当前状态（一行一字段，粗体字段名、暗色次要值）② 底部快捷键；原生 ANSI，不引样式库
  5. 一条命令挂进任务运行器
  6. 交给用户开——「等等，这不应该可能发生」就是想法里的 bug，即原型目的
  7. 收档：逻辑模块拎进真实代码；TUI 壳随原型去一次性分支

反面模式：加测试 · 接真库 · 泛化「以后万一」 · 逻辑和 TUI 糊一起 · TUI 壳进生产

UI 分支骨架

  1. 默认 3 个变体，封顶 5（再多就成噪音）；一句话写下计划
  2. 变体必须结构不同（布局 / 信息层级 / 主操作入口），换色换文案 = 墙纸，不是原型；服从项目组件库；导出 VariantA/B/C
  3. 同路由接线：读 ?variant= 渲染对应组件 + 挂 PrototypeSwitcher； 子形状 A 保留切换器之上全部已有数据获取
  4. 浮动栏（底部居中，三件）：← 循环上一下 · 变体标签（如「B — Sidebar layout」）· → 循环下一个； 点箭头走框架路由更新 URL（可分享、刷新稳定）；←/→ 键盘可切（输入框聚焦时不拦）； 视觉上与页面区分；生产构建里藏掉（NODE_ENV 开关）
  5. 交出 URL 和 variant 键——「我要 B 的页头配 C 的侧边栏」就是真正的设计
  6. 收档：A → 赢家折进已有页面；B → 赢家提升为正式路由；输家 + 切换器从 main 删掉，去一次性分支

子形状：A = 挂在已有页面（默认；真空路由里每个变体都好看，空路由藏设计问题）； B = 新开一次性路由（最后手段，路径带 prototype 字样；用 B 前先确认真的没家）。

反面模式：只换颜色文案 · 变体间共享 Layout · 接真实写操作（要改就指 stub） · 原型代码直接提升进生产（折入时正经重写）

收尾（规则 6）：三样东西各就各位

验证过的决策 ──折进──► 真实代码（main 只留这个）
答案（结论 + 解决的问题）──写进──► Issue / commit / ADR
原型本体 ──提交──► 一次性分支（off main，never merged）
                    实现用的 Issue 上留指向该分支的指针
烂在 main 里的原型 = 过期负债；收在分支上的原型 = 一手材料

上下游

微调入口