---
name: prototype
description: 构建一个可抛弃的原型来回答设计问题。当用户想验证状态模型或逻辑是否合理，或探索 UI 应该长什么样时使用。
---

# 原型（Prototype）

原型是**回答某个问题的一次性代码**。问题决定了它的形态。

## 选择分支

判断要回答的是哪个问题——从用户的提示、周围的代码判断，或者如果用户在场就直接问：

- **"这套逻辑 / 状态模型感觉对吗？"** → [LOGIC.md](LOGIC.md)。构建一个可分享的 HTML 文件——自由试玩按钮加上带标签页的引导式演练——把状态机推过那些在纸面上难以推理的用例，而且非开发者也能上手操作。
- **"它应该长什么样？"** → [UI.md](UI.md)。在单一路由上生成几个截然不同的 UI 变体，通过 URL 查询参数和一个底部悬浮栏切换。

两个分支产出截然不同的产物——选错了分支，整个原型就白做了。如果问题确实模棱两可、用户又联系不上，就默认选择更贴合周围代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部注明这个假设。

## 两者都适用的规则

1. **从第一天起就是一次性的，并且要明确标注。** 把原型代码放在靠近实际使用位置的地方（在它为之原型化的模块或页面旁边），这样上下文一目了然——但命名要让随便一看的人就知道这是原型，不是生产代码。对于一次性 UI 路由，遵循项目已有的路由约定；不要发明新的顶层结构。
2. **运行零门槛。** UI 原型用项目任务运行器里的一条命令启动——`pnpm <name>`、`python <path>`、`bun <path>` 等。逻辑演示是一个用户双击即可打开的 HTML 文件。无论哪种，启动它都不需要任何思考。
3. **默认不持久化。** 状态只存在于内存中。持久化恰恰是原型要*检验*的东西，而不是它应该依赖的东西。如果问题明确涉及数据库，就用一个命名清晰的"PROTOTYPE — 用完即删"的临时数据库或本地文件。
4. **跳过打磨。** 不写测试，不做超出"可运行"所需的错误处理，不搞抽象。重点是快速学到东西。
5. **把状态摆在明面上。** 每次操作之后（逻辑）或每次切换变体时（UI），打印或渲染完整的相关状态，让用户能看到什么变了。
6. **完成后留存。** 把任何验证过的决策折进真实代码，然后把原型本身作为**一手来源**留存：提交到一个一次性分支（放在 main 之外），并在实现 issue 上留下指向该分支的上下文指引。答案也要留存——结论和它所解决的问题——写进 issue 或一次提交里。main 分支只保留验证过的决策。