---
name: prototype
description: 用于通过一次性原型回答设计问题（prototype）。当需要快速验证状态模型或业务逻辑是否合理，或者探索 UI 界面应该是什么样时使用。
---

# 原型

原型是**为了回答一个问题而写的一次性代码**。问题决定原型的形式。

## 选择分支

根据用户的描述和周边代码判断要回答的是哪类问题；用户在场时直接询问：

- **“这个逻辑或状态模型是否合理？”** → [LOGIC.md](LOGIC.md)。制作一个可分享的单文件 HTML（包含随时可用的操作按钮和按标签页组织的引导场景），用来推演那些难以在纸面上想清楚的状态变化，非开发者也能上手操作。
- **“这个界面应该是什么样子？”** → [UI.md](UI.md)。在同一个路由上生成几个差异明显的 UI 变体，通过 URL 查询参数和底部浮动切换条切换。

两个分支产出的产物截然不同，选错分支会让整个原型白做。问题确实模糊且用户不在场时，根据周边代码选择（后端模块选逻辑原型；页面或组件选 UI 原型），并在原型顶部写明这个假设。

## 两者共用的规则

1. **从一开始就是一次性的，并且明确标注。** 把原型代码放在它将来要实际使用的位置附近（对应模块或页面旁边），让上下文一目了然；但命名要让随意的阅读者一眼看出这是原型，而不是生产代码。一次性 UI 路由遵循项目现有的路由约定，不另建顶层结构。
2. **启动零门槛。** UI 原型通过项目任务运行器中的一条命令启动，例如 `pnpm <名称>`、`python <路径>`、`bun <路径>` 等。逻辑演示是一个双击就能打开的单文件 HTML。无论哪种，启动时都不需要额外思考。
3. **默认不持久化。** 状态保存在内存中。持久化是原型要*验证*的对象，而不是它应该依赖的东西。问题明确涉及数据库时，使用临时数据库或本地文件，并在名称中写明清晰的“原型，可清空”字样。
4. **不做打磨。** 不写测试，错误处理只做到能让原型*运行*起来，不做抽象。目的是快速学到东西。
5. **展示状态。** 每次操作之后（逻辑原型）或每次切换变体时（UI 原型），打印或渲染完整的相关状态，让用户看到发生了什么变化。
6. **结束时保存成果。** 把验证过的决定整合进正式代码，然后把原型本身作为**一手资料**（primary source）保存：提交到一个脱离主干的一次性分支，并在实现 issue 中留下指向该分支的上下文指针。结论（裁决本身以及它所解决的问题）也要保存在 issue 或提交信息中。主干只保留经过验证的决定。