tracer-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. 完成后记录。 在提出问题的工作流中记录经验证的决策：构建流程中记录在实现代码 / 规范里；对于 /tracer-wayfinder，则记录在发起该原型的决策工单中。将原型本身作为主要来源保存在 main 之外的一次性分支上，并在发起问题的 issue 或工单中留下上下文指引。也要在那里记录结论和它所解决的问题。绝不要仅仅因为 Wayfinder 原型回答了规划问题，就把它转成生产代码。