prototype

原型（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. 完成后留存。 把任何验证过的决策折进真实代码，然后把原型本身作为一手来源留存：提交到一个一次性分支（放在 main 之外），并在实现 issue 上留下指向该分支的上下文指引。答案也要留存——结论和它所解决的问题——写进 issue 或一次提交里。main 分支只保留验证过的决策。