prototype

原型

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

选择分支

根据用户的提示词、周边代码，或在用户在场时直接询问，确定正在回答的是哪个问题：

• “这个逻辑 / 状态模型是否合理？” → LOGIC.md。构建一个可分享的单个 HTML 文件（包含自由操作按钮和分页式引导演示），让非开发者也能操作，推动状态机经过那些难以在纸上推演的情况。
• “这应该是什么样子？” → UI.md。在单个路由上生成多个截然不同的 UI 变体，可通过 URL 搜索参数和浮动底部栏切换。

两个分支产出的成果截然不同，选错会浪费整个原型。如果问题确实有歧义且无法联系到用户，则默认选择与周边代码更匹配的分支（后端模块对应逻辑分支；页面或组件对应 UI 分支），并在原型顶部说明该假设。

两条分支共同遵循的规则

1. 从第一天起即为一次性代码，并明确标注。 将原型代码放在实际使用位置附近（紧挨着它所原型化的模块或页面），以便上下文一目了然，但命名上要让普通读者一眼看出这是原型而非正式代码。对于一次性 UI 路由，遵循项目已有的路由约定；不要自创新的顶层结构。
2. 运行极其简单。 UI 原型应可通过项目任务运行器中的一条命令启动：pnpm <name>、python <path>、bun <path> 等。逻辑演示则是一个用户双击即可打开的 HTML 文件。无论哪种方式，启动都无需任何思考。
3. 默认不做持久化。 状态保存在内存中。持久化是原型要 检验 的对象，而不是它应当依赖的东西。如果问题明确涉及数据库，则使用测试用的临时数据库或本地文件，并以清晰的“PROTOTYPE，可随时清除”之类的名称命名。
4. 省去打磨。 不写测试，除使原型 可运行 所必需的之外不做错误处理，不做抽象。目的是快速学到东西。
5. 展示状态。 每次操作之后（逻辑分支）或每次切换变体时（UI 分支），打印或渲染所有相关的完整状态，让用户能看到发生了什么变化。
6. 完成后将其存档。 将已验证的决策融入正式代码，然后将原型本身作为主要来源保存：提交到一个一次性分支上，脱离主分支，并在实现 issue 上留下指向该分支的上下文链接。同时将结论（判定结果及其所解决的问题）记录在 issue 或提交中。主分支仅保留已验证的决策。