prototype git:20261008.3911d61A

Immutable. This exact content never changes and is served at /api/v1/blob/046d1b93ad3d3829.

---
name: prototype
description: 构建原型 Demo 来回答设计问题。当用户想要检验状态模型或逻辑是否合理，或探索 UI 应该是什么样时使用。
---

# 原型

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

## 选择分支

从用户提示、周边代码判断要回答哪个问题，用户在线时可以直接问：

- **“这个逻辑 / 状态模型感觉对吗？”** → [LOGIC.md](LOGIC.md)。一个可分享的 HTML 文件，带自由操作按钮和分标签页的引导式演练，让非开发者也能推着状态机走过纸面上难推理的案例。
- **“它应该看起来怎么样？”** → [UI.md](UI.md)。同一路由上多个截然不同的 UI 变体，通过 URL search param 切换，带底部浮动栏。

问题含糊且联系不到用户时，选更贴合周边代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部写明这一假设。

## 两个分支共用的规则

1. **标明一次性。** 原型放在它所原型化的模块或页面旁边，命名让随手阅读的人看出它是原型而非生产代码。
2. **一步启动。** UI 原型用项目 task runner 里的一条命令启动（`pnpm <name>`、`python <path>`、`bun <path>` 等）；逻辑演示是双击即可打开的单个 HTML 文件。
3. **默认不持久化。** 状态放内存。问题明确涉及数据库时，用临时数据库或本地文件，命名为 “PROTOTYPE — wipe me”。
4. **跳过打磨。** 不写测试，错误处理只到能跑为止，不抽象。
5. **展示状态。** 每次 action 后（逻辑）或每次切换变体时（UI），渲染全部相关状态，让用户看见变化。
6. **完成后记录。** 验证过的决策纳入真实代码；原型本身提交到一次性分支（不进主分支），在实现 issue 上链接该分支；答案（结论及它解决的问题）写进 issue 或 commit。主分支只保留验证过的决策。