Prototype

原型

原型就是回答某个问题的 throwaway（一次性）代码。问题决定了它的形态。

选择分支

确定要回答的是哪个问题——从用户的 prompt、周围的代码来判断，或者如果用户在场就直接问：

• 「这套逻辑 / state model 感觉对吗？」 → LOGIC.md。构建一个可分享的单个 HTML 文件——自由操作按钮加上带标签页的引导式走查——推动 state machine 走过那些在纸面上难以推演、且非开发人员也能驱动的用例。
• 「它应该长什么样？」 → UI.md。在单一路由上生成几种差异极大的 UI 变体，通过 URL search param（查询参数）和浮动底栏切换。

两个分支产出的 artifact（产物）截然不同——选错会浪费整个原型。如果问题确实含糊且联系不上用户，默认选择与周围代码更匹配的分支（后端模块 → logic；页面或组件 → UI），并在原型顶部注明这一假设。

两个分支都适用的规则

1. 从第一天起就是 throwaway，并明确标注。 把原型代码放在它实际使用位置的附近（在它为之仿真的模块或页面旁边），这样上下文一目了然——但要命名得让随意浏览的读者一眼看出这是原型，不是生产代码。对于 throwaway 的 UI 路由，遵循项目已有的路由约定；不要发明新的顶层结构。
2. 启动极其简单。 UI 原型只需在项目的 task runner（任务运行器）里执行一条命令——pnpm <name>、python <path>、bun <path> 等。logic 演示则是用户双击即可打开的单个 HTML 文件。无论哪种方式，启动它都不需要动脑筋。
3. 默认不持久化。 状态保存在内存中。持久化正是原型要_检验_的东西，而不是它应该依赖的东西。如果问题明确涉及数据库，就使用一个 scratch（临时）数据库，或一个名字明确写着「PROTOTYPE — wipe me（原型——用完即删）」的本地文件。
4. 跳过打磨。 不写测试，不做超出让原型_可运行_所需的错误处理，不引入抽象。重点是快速学到东西。
5. 呈现状态。 每次操作后（logic）或每次切换变体时（UI），打印或渲染完整的相关状态，让用户看到发生了什么变化。
6. 完成后归档。 把任何经过验证的决策融入真实代码，然后把原型本身作为 primary source（一手来源） 归档：把它提交到 main 之外的 throwaway 分支，并在实现 issue 上留下指向该分支的上下文指针。答案也要归档——结论以及它所解决的问题——记录在 issue 或某个 commit 中。main 分支只保留经过验证的决策。