Prototype

Prototype

Prototype 是用来回答一个问题的 throwaway code。问题决定形状。

Pick a branch

先识别正在回答哪个问题：来自用户 prompt、周围代码，或在用户在线时直接询问：

• "Does this logic / state model feel right?" → LOGIC.md。构建一个很小的交互式 terminal app，推动 state machine 跑过纸面上难以推理的 cases。
• "What should this look like?" → UI.md。在单一路由上生成几种差异很大的 UI variations，并通过 URL search param 和浮动底栏切换。

这两个分支会产出非常不同的 artifacts；选错会浪费整个 prototype。如果问题确实模糊且用户不可达，默认选择更匹配周围代码的分支（backend module → logic；page 或 component → UI），并在 prototype 顶部说明假设。

Rules that apply to both

1. 从第一天就是 throwaway，并明确标记。 Prototype code 要靠近它实际会被使用的位置（放在被 prototype 的 module 或 page 旁边），这样上下文清楚；但命名要让随手读代码的人看出它是 prototype，不是 production。对 throwaway UI routes，遵守项目现有 routing convention；不要发明新的顶层结构。 2. 一个命令即可运行。 使用项目现有 task runner 支持的东西：pnpm <name>、python <path>、bun <path> 等。用户必须能不动脑地启动它。 3. 默认不持久化。 State 保存在内存中。Persistence 是 prototype 要_检查_的东西，不该成为依赖。如果问题明确涉及 database，就用 scratch DB 或带有清晰 “PROTOTYPE — wipe me” 名称的本地文件。 4. 跳过 polish。 不写 tests，不做超过“能跑起来”所需的 error handling，不做 abstractions。重点是快速学到东西，然后删掉。 5. 暴露 state。 每次 action（logic）或每次 variant switch（UI）后，打印或渲染完整相关 state，让用户看到发生了什么变化。 6. 完成后删除或吸收。 当 prototype 回答了问题，要么删掉它，要么把验证过的决策折进真实代码；不要让它在 repo 里腐烂。

When done

Prototype 里唯一值得保留的是_答案_。把它和所回答的问题一起记录到持久位置（commit message、ADR、issue，或 prototype 旁边的 NOTES.md）。如果用户在线，这个记录可以是一段快速对话；如果不在线，留下 placeholder，让他们（或下一轮的你）在删除 prototype 前补上结论。

Logic Prototype

一个很小的交互式 terminal app，让用户手动驱动 state model。用于问题围绕 business logic、state transitions 或 data shape 的场景，也就是纸面上看起来合理，但只有跑过真实 cases 才会感觉哪里不对的东西。

When this is the right shape

• "I'm not sure if this state machine handles the edge case where X then Y."
• "Does this data model actually let me represent the case where..."
• "I want to feel out what the API should look like before writing it."
• 任何用户想按按钮并观察 state 变化的情况。

如果问题是 “what should this look like”，这是错误分支。使用 UI.md。

Process

1. State the question

写代码前，先写下你正在 prototype 哪个 state model、回答什么问题。一段即可，放在 prototype 的 README，或文件顶部 comment。回答错问题的 logic prototype 纯属浪费；把问题显式写出来，这样无论用户现在旁观，还是之后 AFK 回来看，都能检查。

2. Pick the language

使用 host project 使用的语言。如果项目没有明显 runtime（例如 docs repo），询问用户。

匹配项目现有 tooling conventions；不要为了 prototype 增加新的 package manager 或 runtime。

3. Isolate the logic in a portable module

把真正的 logic，也就是回答问题的那部分，放在一个小而纯粹的 interface 后面，让它之后可以被拿出来放进真实 codebase。包在外面的 TUI 是 throwaway；logic module 不应该是。

合适形状取决于问题：

• Pure reducer — (state, action) => state。适合 actions 是离散 events、state 是单个值的场景。
• State machine — 显式 states 和 transitions。适合 “现在到底哪些 actions 合法” 本身就是问题的一部分。
• 一组作用于 plain data type 的 pure functions。适合没有隐式 current state，只有 transformations 的场景。
• Class 或带清晰 method surface 的 module，当 logic 确实拥有持续的 internal state。

选择最适合问题的形状，而不是最容易接到 TUI 上的形状。保持 pure：不要 I/O，不要 terminal code，不要用 console.log 做 control flow。TUI import 它并调用它；不要反向依赖。

这让 prototype 在自身生命周期之后仍有价值。当问题被回答后，验证过的 reducer / machine / function set 可以被搬进真实 module；TUI shell 删除。

4. Build the smallest TUI that exposes the state

把它做成轻量 TUI：每个 tick 清屏（console.clear() / print("\033[2J\033[H") / 等价方式），并重新渲染整帧。用户应该始终看到一个稳定 view，而不是不断增长的 scrollback。

每一帧按顺序包含两部分：

1. Current state，pretty-printed 且 diff-friendly（每行一个 field，或 formatted JSON）。对 field names 或 section headers 使用 bold，对不太重要的 context（timestamps、IDs、derived values）使用 dim。原生 ANSI escape codes 就可以：\x1b[1m bold，\x1b[2m dim，\x1b[0m reset。除非项目已经有 styling library，否则不用引入。 2. Keyboard shortcuts，列在底部：[a] add user [d] delete user [t] tick clock [q] quit。可以让 key 加粗、description 变 dim，或反过来；只要读起来清楚。

Behaviour：

1. Initialise state — 一个 in-memory object/struct。启动时渲染第一帧。 2. 一次读取一个 keystroke（或一行），dispatch 到 handler 来 mutate state。 3. 每个 action 后重新渲染完整帧；不要 append，要 replace。 4. 循环直到 quit。

整帧应能放进一个屏幕。

5. Make it runnable in one command

把 script 加到项目现有 task runner（package.json scripts、Makefile、justfile、pyproject.toml）。用户应该运行 pnpm run <prototype-name> 或等价命令；永远不需要记路径。

如果 host project 没有 task runner，就把命令写在 prototype README 顶部。

6. Hand it over

给用户 run command。让他们自己驱动；真正有趣的时刻是他们说 “wait, that shouldn't be possible” 或 “huh, I assumed X would be different” 的时候。这些是想法里的 bug，也正是 prototype 的目的。如果他们想添加新 actions，就添加。Prototypes 会演进。

7. Capture the answer

Prototype 完成任务后，唯一值得保留的是问题的答案。如果用户在线，询问它教会了他们什么。如果不在线，在 prototype 旁边留下 NOTES.md，让答案可以在 prototype 被删除前补上（或由你在看过 session 后补上）。

Anti-patterns

• 不要加 tests。 需要 tests 的 prototype 已经不再是 prototype。
• 不要接真实 database。 除非问题专门关于 persistence，否则使用 in-memory store。
• 不要 generalise。 不要做 “what if we wanted to support X later”。Prototype 回答一个问题。
• 不要把 logic 和 TUI 混在一起。 如果 reducer / state machine 引用了 console.log、prompts 或 terminal escape codes，它就不再 portable。让 TUI 作为 pure module 外面的薄 shell。
• 不要把 TUI shell 发到 production。 Shell 是为手动 terminal 驱动优化的。它背后的 logic module 才是值得保留的部分。

UI Prototype

在单一路由上生成几种差异很大的 UI variations，并通过浮动底栏切换。用户在浏览器里来回切换 variants，选中一个（或从每个里面偷一部分），然后把其余部分丢掉。

如果问题是 logic/state，而不是东西应该长什么样，这是错误分支。使用 LOGIC.md。

When this is the right shape

• "What should this page look like?"
• "I want to see a few options for this dashboard before committing."
• "Try a different layout for the settings screen."
• 任何用户原本要花一天在脑子里比较三个模糊 mockups 的情况。

Two sub-shapes — strongly prefer sub-shape A

当 UI prototype 贴着应用其他部分运行时会更容易判断：真实 header、真实 sidebar、真实 data、真实 density。一个独立的 throwaway route 是真空环境；每个 variant 单看都还行。只要有合理的现有页面可以承载 variants，默认选择 sub-shape A。只有 prototype 确实没有附近归宿时，才使用 sub-shape B。

Sub-shape A — adjustment to an existing page (preferred)

路由已经存在。Variants 渲染在同一路由上，通过 ?variant= URL search param gate。现有 data fetching、params、auth 都保留；只替换 rendering。这是默认选择，除非有明确理由不用。

如果 prototype 的东西还没有页面，但自然会存在于某个页面内部（dashboard 新 section、settings screen 新 card、现有 flow 的新 step），仍然算 sub-shape A。把 variants mount 到 host page 内。

Sub-shape B — a new page (last resort)

只有被 prototype 的东西确实没有现有页面可放时才用，例如全新的顶层 surface，或无法合理嵌入任何地方的 flow。

按照项目现有 routing convention 创建一个 throwaway route；不要发明新的顶层结构。命名要明显是 prototype（例如在 path 或 filename 中包含 prototype）。同样使用 ?variant= pattern。

在决定 sub-shape B 前 sanity-check：真的没有现有页面可以嵌入吗？空路由会隐藏 populated page 才能暴露的 design problems。

两种 sub-shapes 都使用相同的浮动底栏。

Process

1. State the question and pick N

默认做 3 variants。超过 5 个就不再是 radically different，而是 noise；最多 5 个。

在 prototype 所在位置或文件顶部 comment 写一行计划：

"Three variants of the settings page, switchable via ?variant=, on the existing /settings route."

无论用户是否在旁边反馈，这都有效。

2. Generate radically different variants

起草每个 variant，并要求它们满足：

• 符合页面目的和可访问数据。
• 符合项目 component library / styling system（TailwindCSS、shadcn、MUI、plain CSS 等）。
• 有清晰 exported component name，例如 VariantA、VariantB、VariantC。

Variants 必须结构不同：不同 layout、不同 information hierarchy、不同 primary affordance，而不只是颜色不同。三个稍微调过的 card grids 不是 UI prototype，是 wallpaper。如果两个 drafts 太像，明确要求 “do not use a card grid” 后重做其中一个。

3. Wire them together

在路由上创建一个 switcher component：

// pseudo-code — adapt to the project's framework
const variant = searchParams.get('variant') ?? 'A';
return (
  <>
    {variant === 'A' && <VariantA {...data} />}
    {variant === 'B' && <VariantB {...data} />}
    {variant === 'C' && <VariantC {...data} />}
    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
  </>
);

对 sub-shape A（existing page）：保留 switcher 上方所有 existing data fetching；只有 rendered subtree 随 variant 改变。

对 sub-shape B（new page）：/prototype/<name> 下的 throwaway route mount 同一个 switcher。

4. Build the floating switcher

屏幕底部居中的 fixed-position 小 bar，包含三部分：

• Left arrow — 切到上一个 variant（循环）。
• Variant label — 显示当前 variant key；如果 variant export 了 name，也一起显示。例如 B — Sidebar layout。
• Right arrow — 切到下一个 variant（循环）。

Behaviour：

• 点击 arrow 更新 URL search param（使用 framework router：Next 用 router.replace，React Router 用 navigate 等），让 variant 可分享且 reload-stable。
• Keyboard：← 和 → arrow keys 也能切换。当 focus 在 <input>、<textarea> 或 [contenteditable] 内时不要拦截 arrow keys。
• 视觉上要和页面区分开（例如 high-contrast pill、subtle shadow），让它明显不是被评估设计的一部分。
• 在 production builds 中隐藏；用 process.env.NODE_ENV !== 'production' 或等价检查 gate，避免 stray prototype merge 把 bar 发给用户。

把 switcher 放进单个 shared component，让两种 sub-shapes 都能复用。放在项目 shared UI 所在位置。

5. Hand it over

给出 URL（以及 ?variant= keys）。用户会在方便时切换。最有价值的反馈通常是 "I want the header from B with the sidebar from C"，那才是他们真正想要的设计。

6. Capture the answer and clean up

一旦某个 variant 胜出，记录它是哪一个以及为什么（commit message、ADR、issue，或如果 AFK 运行且用户尚未回应，就放在 prototype 旁边的 NOTES.md）。然后：

• Sub-shape A — 删除失败 variants 和 switcher；把胜出的方案折进现有页面。
• Sub-shape B — 把胜出的 variant 提升为真实 route，删除 throwaway route 和 switcher。

不要把 variant components 或 switcher 留在 repo 中。它们很快会腐烂，并误导下一个读者。

Anti-patterns

• Variants 只在颜色或文案上不同。 那是 tweak，不是 prototype。真正的 variants 会在结构上互相不同意。
• Variants 之间共享太多代码。 共享 <Header> 可以；共享 <Layout> 会破坏目的。每个 variant 都应该可以扔掉 layout。
• 把 variants 接到真实 mutations。 Read-only prototypes 没问题。如果某个 variant 需要 mutate，指向 stub；问题是 “what should this look like”，不是 “does the backend work”。
• 直接把 prototype 提升到 production。 Variant code 是在 prototype constraints 下写的（无 tests、最少 error handling）。折进真实实现时要重新正确实现。