prototype

name	prototype
description	构建一个一次性原型来回答设计问题。当用户想要快速验证某个状态模型或逻辑是否正确，或探索 UI 应该长什么样时使用。

原型

原型是回答问题的 disposable 代码。问题决定形态。

选择分支

确定正在回答哪个问题——从用户的提示、周围代码中推断，或用户在场时直接询问：

• "这个逻辑 / 状态模型对吗？" → LOGIC.md。构建一个微小的交互式终端应用，推动状态机经过那些在纸面上难以推理的用例。
• "这个应该长什么样？" → UI.md。在单个路由上生成几个截然不同的 UI 变体，通过 URL 查询参数和底部浮动栏切换。

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

通用规则

1. 从第一天起就是 disposable，并明确标注。 将原型代码放在离实际使用位置近的地方（紧邻它正在为哪个模块或页面做原型），这样上下文一目了然——但命名要让随便一个读者都能看出这是原型而非生产代码。对于 disposable UI 路由，遵循项目已有的路由约定，不要发明新的顶层结构。
2. 一条命令即可运行。 使用项目已有任务运行器支持的方式——pnpm <名称>、python <路径>、bun <路径> 等。用户必须能不加思考就启动它。
3. 默认无持久化。 状态存在于内存中。持久化是原型正在_检查_的东西，而非原型应该依赖的东西。如果问题明确涉及数据库，用一个临时库或本地文件，名称要清楚标注"PROTOTYPE — 可随时清除"。
4. 跳过打磨。 不写测试，不做超出让原型_可运行_范围的错误处理，不建抽象。目的是快速学习。
5. 展示状态。 每次操作后（logic）或每次变体切换时（UI），打印或渲染完整的相关状态，让用户能看到什么发生了变化。
6. 完成后捕获结论。 将验证通过的决策融入正式代码。然后将答案和结论持久化到变更目录：
   • 在 <Path>{roots.state}/<workflow>/changes/{change}/prototype/</Path> 下创建答案文件
   • 维护 prototype/index.md 索引表
   • 原型代码本身仍为一次性代码：提交到 throwaway 分支，保持脱离主分支。答案文件中记录该分支的引用指针
   • 具体持久化规范见下方「持久化约定」章节

持久化约定

产物位置

原型答案写入当前 change 目录下的 prototype/ 子目录：

<Path>{roots.state}/<workflow>/changes/{change}/prototype/<type>-<topic>.md</Path>

• <type> 为 logic 或 ui，对应原型分支类型
• <topic> 为 kebab-case 主题名，概括原型所回答的问题，如 auth-state-machine.md、settings-page-layout.md
• <workflow> 为当前 workflow 目录名（如 specdev）
• <change> 为当前活跃变更目录名（格式 <YYYY-MM-DD>-<topic>，从 <Path>{roots.state}/<workflow>/status.json</Path> 的 active 数组中获取）

答案文件内容

每个答案文件包含以下信息：

• 问题：原型所回答的具体问题
• 结论：验证后的结论——什么可行、什么不可行、为什么
• 验证内容（仅 logic 原型）：被验证的 reducer / 状态机 / 函数集的描述
• UI 评估记录（仅 UI 原型）：哪个变体胜出及原因、各变体的结构差异分析、从落选变体中提取的有价值元素
• 原型代码引用：throwaway 分支名称，指向原型代码所在的 git 分支

维护 prototype/index.md

在 prototype/ 目录下维护一个索引文件 <Path>{roots.state}/<workflow>/changes/{change}/prototype/index.md</Path>，仅包含一张表格：

类型	文件	问题概述	结论摘要
logic	auth-state-machine.md	认证状态机能否正确处理 token 过期 + 并发刷新	可行；需增加 TOKEN_EXPIRED 中间态
ui	settings-layout.md	设置页三种布局方案对比	B 方案（侧边栏布局）胜出；吸收 C 的面包屑导航

• 表格四列：类型（logic / ui）、文件（prototype/ 下的相对路径）、问题概述（一句话概括）、结论摘要（一句话概括结论）
• 每次新增答案文件后，向表格追加一行
• index.md 除表格外无需其它内容

去重与增量更新

在开始新原型之前：

1. 先读取 <Path>{roots.state}/<workflow>/changes/{change}/prototype/index.md</Path>，检查是否已有同名或高度相关的原型记录
2. 如已存在对应 .md 文件，先读取其完整内容
3. 如现有结论已覆盖当前问题，直接引用，无需重复原型
4. 如需更新（新发现补充、结论修正），在原文件基础上增删改，并同步更新 index.md 中对应行的概述
5. 如需回答全新问题，创建新文件并追加到 index.md 表格