prototype

原型

原型是用于解答一个问题的实验性代码。问题决定原型的形式。只有用户提出或批准了范围明确的实验（包括在确定规格的过程中），才继续进行。持续迭代会直接演进实现，默认不需要原型。

共享项目文档及其规则见 project-documents.md。将未解决的提案与已达成一致的行为分别记录。视情况在功能的草案或规格文档以及工作状态中，记录问题、结论、证据和剩余的验收事项。在变更日志中记录已完成的一致事项，并注明原型代码仍需经过生产验证。

选择分支

根据用户的提示、周围的代码，或者在用户有空时询问，确定要解答哪个问题：

• “这个逻辑／状态模型感觉对吗？” → logic.md。构建一个可分享的单一 HTML 文件（包含自由操作按钮和带标签页的引导式演练），通过一些难以纸上推演的案例驱动状态机，并让非开发者也能操作。
• “这个界面应该是什么样？” → ui.md。在单一路由上生成多个截然不同的 UI 变体，通过 URL 查询参数和浮动底栏切换。

构建整个应用的请求不属于原型。询问实验应解答哪个单一问题，并将范围缩小；如果用户想要的是应用本身，就说明构建应用不是原型的任务，并停止。

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

两个分支通用的规则

1. 从一开始就是实验，并明确标注。 将实验与应用行为和生产交付隔离。必要时将其放在相关模块或页面附近，并明确命名为原型。对于实验性 UI 路由，遵循项目的路由约定。
2. 运行起来毫不费力。 UI 原型只需通过项目的任务运行器执行一条命令即可启动：pnpm <name>、python <path>、bun <path> 等。逻辑演示则是一个用户双击即可打开的 HTML 文件。无论哪种方式，启动时都不需要费心思。
3. 默认不持久化。 状态保存在内存中。持久化是原型要_验证_的内容，而不是原型应依赖的东西。如果问题明确涉及数据库，则使用临时数据库或本地文件，并为其取一个醒目的名称，例如“PROTOTYPE, wipe me”。
4. 跳过润色。 不写测试，不添加超出_确保原型可运行_所需的错误处理，也不做抽象。目的是快速获得认知。
5. 展示状态。 每次操作后（逻辑原型）或每次切换变体时（UI 原型），都打印或渲染完整的相关状态，让用户看清发生了什么变化。
6. 完成后记录。 将实验作为主要来源保留下来，并在相关工作记录中提供上下文指引。未选中的实验应保留在生产环境之外。经过验证且有用的代码无需强制重建即可集成，但前提是已获授权验收，并通过应用的生产检查，包括测试、错误处理，以及在需要判断时对外观和交互的验收。集成代码中应移除实验性控件和标签。实验成功本身并不能证明代码已具备生产就绪状态。