prototype

原型

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

选择分支

确定要回答哪个问题——可以从用户的提示、周围的代码中判断，也可以在用户在线时询问：

• “这套逻辑／状态模型感觉对吗？” → LOGIC.md。构建一个小型交互式终端应用，让状态机经历那些难以仅凭纸面推演的情况。
• “它应该是什么样子？” → UI.md。针对同一个路由生成几种截然不同的 UI 变体，通过 URL 查询参数和底部浮动栏切换。

这两个分支会生成截然不同的产物——选错会让整个原型付诸东流。如果问题确实含糊不清，而且无法联系到用户，就默认选择更符合周围代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部说明这一假设。

两种分支都适用的规则

1. 从一开始就视为一次性代码，并明确标注。 将原型代码放在靠近实际使用位置的地方（紧邻要为其制作原型的模块或页面），让上下文一目了然——但要给它命名，让随手一读的人知道它是原型，而非生产代码。对于一次性 UI 路由，遵循项目现有的路由约定；不要另造顶层结构。
2. 一条命令即可运行。 使用项目现有任务运行器支持的任意方式——pnpm <name>、python <path>、bun <path> 等。用户无需费心就能启动它。
3. 默认不持久化。 状态保存在内存中。原型要验证的是持久化，而不是依赖持久化。如果问题明确涉及数据库，就使用临时数据库，或使用名称清晰标注为“PROTOTYPE - wipe me”的本地文件。
4. 省略精修。 不写测试，不做超出原型可运行所需的错误处理，也不做抽象。目的是快速学到东西，然后删除原型。
5. 呈现状态。 每次操作后（逻辑原型）或每次切换变体时（UI 原型），打印或渲染完整的相关状态，让用户看清发生了什么变化。
6. 完成后删除或吸收。 原型回答了问题后，要么删除它，要么把经过验证的决策纳入正式代码——不要让它在代码库里逐渐腐烂。

完成后

原型中唯一值得保留的是答案。将答案连同它要回答的问题一起记录在某个持久位置（提交消息、ADR、议题，或原型旁边的 NOTES.md）。如果用户在线，这条记录可以通过简短对话完成；如果用户不在线，就留下占位内容，让他们（或下一次处理的你）在删除原型前补上结论。