Lesson 0008 · Engineering · 人和 AI 都能启动（model-invoked）· 流程课

prototype：用一次性代码回答一个设计问题

你在写一个状态机：订单可以从「待支付」走到「已支付」，但「超时取消」和「部分退款」同时发生时， 纸上怎么画都觉得对，心里就是没底。或者：设置页到底用侧边栏还是标签页，脑子里三张草图打了一下午的架。 这种问题在对话里争不出结果——它需要一个能跑起来的答案。prototype 干的就是这件事： 写一段一次性代码（throwaway code：从第一天起就打算扔掉的代码）， 它的唯一职责是回答这一个设计问题。问题决定代码的形状：问「这个状态模型感觉对吗」， 就造一个可以在终端里用手推着走的小程序；问「这页面该长什么样」，就在同一条路由上 并排摆几个截然不同的界面版本，用浏览器底部的一条浮动栏来回切换。 学完这节课，你能说清楚：怎么选分支、两条分支各自的骨架长什么样、 收尾时原型本体和答案分别落到哪里、行为不对时该改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个已发布 skill 分成三层：配置层、编排层、纪律层。prototype 不在这三层的任何一条 主流程骨架上——ask-matt 把它放在 Standalone（随时伸手用的独立工具）一节： 「a small, throwaway program that answers one design question」，并且明说 「reach for it any time a design question is hard to settle on paper」 （任何时候，只要一个设计问题在纸上定不下来，都可以伸手用它）。 但它同时又是主流程里的一个正式岔路：主流程第 2 步问 「所有问题都能在对话里定下来吗」，如果某个问题需要一个能跑的答案 （状态、业务逻辑、必须亲眼看到的 UI），就从主流程岔出去做 prototype， 两头都用 handoff 摆渡——出去时 handoff 一次、开新会话做原型， 回来时把学到的东西 handoff 回原线程，并在原来的想法线程里引用它。

它是 model-invoked 的（人和 AI 都能启动）：frontmatter 里没有 disable-model-invocation，agents/openai.yaml 里也没有 allow_implicit_invocation: false。docs 页的说法是 「Type /prototype, or the agent reaches for it automatically when a task fits」—— 你可以显式打 /prototype，AI 在对话里闻到「这个问题纸上定不下来」的味道时也会自己伸手。

主流程（ask-matt 的 step 2 岔路）：

  /grill-with-docs 面试中冒出一个需要「能跑的答案」的问题
        │
        │ /handoff ──► 新会话
        ▼
   ┌─────────────┐   答案 + 原型本体
   │ /prototype  │ ────────────────┐
   └─────────────┘                 │
        ▲                          │ /handoff 回原线程
        └──────────────────────────┘
        然后继续主流程：to-spec / to-tickets / implement

Standalone 用法：不挂任何流程，任何时候单独 /prototype。

地图：0001 · 岔路原文：ask-matt/SKILL.md 的 main flow 第 2 步和 Standalone 一节 · 摆渡船：0006 handoff · 启动方式判定：prototype/agents/openai.yaml（没有禁止隐式调用）

2. 它是什么、什么时候用、什么时候别用

2.1 一句话定性：一次性代码，只回答一个问题

SKILL.md 开篇第一句就是定义：「A prototype is throwaway code that answers a question. The question decides the shape.」（原型是回答问题的一次性代码；问题决定它的形状。） 三个词都不能省：一次性——从第一天起就打算扔，不带测试、不带错误处理、不带抽象； 回答问题——它不是产品的雏形，也不是 MVP（最小可行产品），它的产出是一个答案，不是一套功能； 问题决定形状——先想清楚问的是什么，再决定造什么，顺序反了就白做。

2.2 什么时候伸手

frontmatter 的 description 给出触发条件：当你想 sanity-check（快速验证） 一个状态模型或一段逻辑感觉对不对，或者想探索一个 UI 该长什么样。展开成具体场景：

权威原文：skills/engineering/prototype/SKILL.md · 给人看的叙事版：docs/engineering/prototype.md （aihero.dev/skills-prototype）

3. 第一刀：选对分支

SKILL.md 的「Pick a branch」一节只有两条路，由问题本身决定：

• 「这个逻辑 / 状态模型感觉对吗？」 → 走 LOGIC.md： 造一个很小的交互式终端程序，把状态机推进那些在纸上很难推演的情况里。
• 「这东西该长什么样？」 → 走 UI.md： 在同一条路由上生成几个截然不同的 UI 变体，用 URL 的 search param （问号后面的查询参数，如 ?variant=B）和一条浮在底部的工具栏切换。

怎么判断当前问题属于哪条？按 SKILL.md 的顺序：从你的 prompt 里读； 读不出来就看周围的代码（一个后端模块 → 多半走 LOGIC；一个页面或组件 → 多半走 UI）； 还拿不准而你在场——直接问你。为什么这一步不能糊弄： 原文说「getting this wrong wastes the whole prototype」——选错分支，整个原型白做， 因为两条分支产出的东西完全不同（一个是终端程序，一个是路由上的几个界面）。 如果你真的联系不上、问题又真的模糊，默认规则是：看周围代码更像哪边就走哪边， 并且把这个假设写在原型顶部，让你回来第一眼就能看到。

4. 两条分支共用的六条规则

不管走哪条分支，SKILL.md 的「Rules that apply to both」一节都适用。 这六条是 prototype 的骨架，逐条拆开看：

5. LOGIC 分支：能用手推着走的状态模型

LOGIC.md 的适用信号是：问题关于业务逻辑、状态迁移、数据形状—— 「在纸上看挺合理，但只有真的推几个 case 才知道感觉对不对」的那种东西。 它的原文例子：「我不确定这个状态机能不能处理 X 然后 Y 的边界情况」、 「这个数据模型到底能不能表达……这种情况」、「我想在动手写之前先摸摸这个 API 的手感」。 共同点：你想按按钮、看状态变。

5.1 七步流程

5.2 逻辑模块的四种形状，按问题选

第 3 步「把逻辑隔离进可搬走的模块」是整个 LOGIC 分支最值钱的设计决策。 LOGIC.md 给了四种候选形状，选最贴合问题的那种，而不是最好接 TUI 的那种：

不管选哪种，都保持纯：不做 I/O、不碰终端、不用 console.log 当控制流。 依赖方向是单向的：TUI import 逻辑模块并调用它，反方向什么都不流。 回报在第 7 步兑现：问题答完，验证过的 reducer / 状态机 / 函数集可以原样拎进真实模块—— 原型死了，器官捐献给了产品。

5.3 TUI 的画面结构

每一拍（tick）清屏后重绘的整帧画面，按顺序只有两部分：

┌──────────────────────────────────────┐
│ 1. 当前状态                            │
│    友好打印、方便比对（一行一个字段，     │
│    或格式化 JSON）                      │
│    字段名/小节标题用粗体，次要信息用暗色   │
│    （时间戳、ID、派生值）                │
├──────────────────────────────────────┤
│ 2. 键盘快捷键（列在底部）               │
│    [a] add user  [d] delete user      │
│    [t] tick clock  [q] quit           │
│    键名加粗、说明暗色（或反过来，读着顺就行）│
└──────────────────────────────────────┘

样式直接用终端原生的 ANSI 转义码（\x1b[1m 粗体、\x1b[2m 暗色、 \x1b[0m 复位），项目里没有现成的样式库就不要为原型引一个。 行为循环四步：初始化一个内存里的状态对象并渲染第一帧 → 每次读一个按键（或一行输入）、 派发给处理函数改状态 → 每个动作之后整帧重绘（替换，不是追加）→ 循环直到退出。 整帧必须一屏放得下。

5.4 LOGIC 分支的反面模式

• 别加测试——需要测试的原型已经不是原型了（原文：「A prototype that needs tests is no longer a prototype」）。
• 别接真实数据库——除非问题本身就是关于持久化的，否则用内存存储。
• 别泛化——不想「以后万一要支持 X 呢」。原型只回答一个问题。
• 别把逻辑和 TUI 糊在一起——reducer / 状态机里出现 console.log、prompt、终端转义码，它就搬不走了。壳要薄，核要纯。
• 别把 TUI 壳带进生产——壳是为「在终端里用手开」优化的；值得留下的是壳后面的逻辑模块。

6. UI 分支：同一路由上的几个激进版本

UI.md 的适用信号是：问题是「该长什么样」。做法：在同一条路由上生成 几个截然不同（radically different）的 UI 变体，用一条浮在屏幕底部的工具栏切换， 你在浏览器里来回翻，挑一个（或者从每个里偷一点），剩下的扔掉。 原文对时机的判断很到位：任何时候，你如果不这么做、就得花一整天在脑子里比较三个模糊的假想稿—— 那就该做这个原型。

6.1 两种子形状：强烈优先 A

为什么强烈优先 A？UI.md 的理由：UI 原型要贴着真实的应用才好判断——真实的页头、侧边栏、 真实的数据、真实的密度。孤零零的一次性路由是一个真空环境：每个变体在真空里看着都挺好， 空路由会把设计问题藏起来，而有内容的路由会把它们暴露出来。

6.2 六步流程

6.3 浮动切换器的行为细则

• 点箭头要更新 URL 的 search param（用框架的路由：Next 用 router.replace，React Router 用 navigate），这样变体可分享、刷新后不变。
• 键盘 ← 和 → 也能切换；但当焦点在 <input>、<textarea> 或 [contenteditable] 里时不要拦截方向键——用户正在打字。
• 视觉上要和页面明显区分（高对比度的胶囊形、带一点阴影），让人一眼看出它不是被评估的设计的一部分。
• 生产构建里要藏掉：用 process.env.NODE_ENV !== 'production' 之类的开关拦住，防止某次误合并把这条栏发给真实用户。

6.4 UI 分支的反面模式

• 变体只在颜色或文案上有差别——那叫微调，不叫原型。真正的变体在结构上有分歧。
• 变体之间共享太多代码——共享一个 <Header> 可以；共享一个 <Layout> 就没意义了。每个变体要有推翻整个布局的自由。
• 把变体接上真实的写操作——只读原型就够。某个变体非要改数据，就指向一个 stub（假实现）；问题是「该长什么样」，不是「后端能不能用」。
• 把原型直接提升进生产——变体代码是在原型约束下写的（没测试、错误处理从简）。折进真实代码时正经重写一遍。

7. 收尾纪律：原型是一手材料，不进 main

六条共用规则里的第 6 条（Capture it when done）值得单独一节，因为它是这个 skill 和其它「随便写写试试」之间最大的差别：原型做完不是删掉，是收档。 docs 页把收档的产出拆成两样东西：

收档全景：

   原型答完了问题
        │
        ├─► 验证过的决策 ──折进──► 真实代码（main 只留这个）
        │     · LOGIC：逻辑模块拎进真实模块（正经重写/移植）
        │     · UI：赢家变体折进已有页面或提升为正式路由
        │
        ├─► 答案（结论 + 问题）──写进──► Issue / commit / ADR
        │
        └─► 原型本体 ──提交到──► 一次性分支（off main，never merged）
                                   实现用的 Issue 上留指针

出处：SKILL.md 规则 6 · docs/engineering/prototype.md 的「Keep the prototype as a primary source」一节 · 分支各自的映射：LOGIC.md 第 7 步、 UI.md 第 6 步

8. 谁在上游、谁在下游

                 想法线程（主流程）
              /grill-with-docs 面试中
              冒出一个「纸上定不下来」的问题
                        │
              /handoff ─┼─► 新会话 ─► /prototype
                        │                 │
                        │            答案 + 一次性分支
                        │                 │
                        ◄── /handoff ─────┘
                        │
                        ▼
        ┌───────────────┼────────────────────┐
        ▼               ▼                    ▼
    /to-spec      /domain-modeling      直接回主流程
  把验证过的状态    若决策不可逆，         （甚至 /implement）
  模型或 UI 方向    记一条 ADR
  当已确定的输入写进 spec

9. 会留下什么、用完接什么、想微调改哪里

9.1 副作用清单

9.2 用完之后，下一步去哪

1. 从主流程岔出来的 → /handoff 把答案带回原线程 → 继续主流程（多半进 /to-spec，把验证过的结论当已确定的输入）。
2. 决策不可逆 → 走 domain-modeling 记一条 ADR，把「为什么是这个状态机 / 这个方向」钉下来。
3. standalone 单独用的 → 答案收进 Issue 或 commit，原型收进一次性分支，然后回到你手头的工作。
4. 答完问题发现想法本身有裂缝 → 回 /grill-with-docs 重新磨——原型暴露了想法里的 bug，这是胜利，不是返工。

9.3 行为不对时，去改哪个文件的哪一段

10. 检索练习

先别往回翻，凭记忆答。选项长度刻意对齐，不会从版式泄题。规则编号和措辞以本课和 SKILL.md / LOGIC.md / UI.md 原文为准。

11. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/prototype/SKILL.md —— 一句话定义、选分支、六条共用规则、收档纪律。首选 primary source。
• …/LOGIC.md —— 逻辑分支：四种逻辑形状、TUI 画面结构、七步流程、反面模式。
• …/UI.md —— UI 分支：两种子形状、变体纪律、浮动切换器细则、收尾映射。
• docs/engineering/prototype.md —— 给人看的叙事版：throwaway 的哲学、「primary source」论证、和 diagnosing-bugs 的分工 （aihero.dev/skills-prototype）。
• 路由上下文： ask-matt/SKILL.md —— 主流程 step 2 的岔路和 Standalone 名单。

速查页（本课同步）： reference/prototype.html

导航： 上一课 0007 research （另一条 standalone 岔路：一个交 Markdown，一个交能跑的代码）。 总览仍回 0001 系统地图； 摆渡船见 0006 handoff； 下游接 0009 to-spec。

建议下一课（0009 to-spec）： 原型把「感觉对吗」变成了「验证过」——下一课看 to-spec 怎么把这种已确定的结论 （连同面试记录、研究文件）写成一份能拆成 Issue 的 spec。 交接点：spec 的 Implementation Decisions 一节写的就是这类已敲定的决策， 而原型分支的指针就是它们的证据附件。