prototypekit

prototypekit

有些决策无法通过阅读来敲定。这个 reducer 能处理部分退款吗？这个库的速度足以应付我们的负载吗？这个设置页面实际应该是什么样子？prototypekit 会编写代码，唯一的目的就是回答其中一个问题；然后丢弃代码，只保留答案。

这种反转就是这项技能的全部要义。原型不是正式产品的草稿，不是起步代码，也不是演示。它是一种工具，而工具用完就该收起来。下面的一切，都是为了让代码可以丢弃，让答案得以留存。

适用场景

“为此做个原型”“对这个做个技术验证”“探索一下 X，代码不用保留”“这个状态模型能不能撑住”“遇到 时能否正常运行”“速度够不够快”“这两个能否互操作”“这个 API 的实际行为是否符合文档暗示”“在应用中试做三个可用版本”“/prototypekit”。如果提供了屏幕截图，或某个界面的图片选项，且已安装 uikit，则使用 mockup；否则用现有的任意图像工具绘制图片。

有四件事，它明确不做：

• 不是构建步骤。 构建技能会在意图已敲定后，将其转化为经过测试和构建关卡的生产代码。prototypekit 则在意图尚未敲定、因为没人见过它实际运行时启动；它会故意编写不符合任何生产标准的代码，也不设置任何关卡。
• 不是研究步骤。 研究通过一手资料得出答案，从不构建。prototypekit 通过构建来回答，不引用资料。二者相辅相成：当研究发现某项主张无法通过来源敲定时，就由这里来回答。
• 不是 UI 构建工具。 UI 技能会遵循项目的设计系统，构建最终交付的界面。prototypekit 的模拟界面是用来比较、挑选和删除的；它们会故意打破一致性，因为三个都遵循规范的变体，只是同一个想法的三种呈现。
• 不是演示生成器。 请求最常伪装成的就是这种形式。参见没有问题，就没有原型。

没有问题，就没有原型

动笔之前，分别用一句话说明要回答的问题和它能促成的决策。如果两者都写不出来，现在就还不该做原型。

如果请求归结为“给我做个演示”“给客户做个概念验证”或“随便试试”，那就是换了个委婉说法的生产工作。只拒绝一次，说明原因和正确路径：这需要的是计划和正式构建，而不是一次性的原型。

如果用户再次确认，请求就会转变，而不是技能转变。 用户已经做出了决定；争论两次不是你的职责。明确说明这是生产工作，然后按生产工作的方式来做：不添加标记、不添加排除条目、不丢弃，并且让代码留在磁盘上。到这一步，prototypekit 就不再主导了。绝不能把演示做成带标记、会被丢弃的原型，因为那样会把一个可以拿给客户看的东西交给别人，然后又把它删掉。

六项规则

两种模式均须遵守。

1. 从第一天起就是一次性原型，并做好标记。 将原型放在你正在试验的代码旁边，这样项目的导入、别名和配置都能直接使用。每个文件命名为 *.prototype.*，每个目录命名为 *.prototype/。这个标记不是装饰：排除规则会匹配它；未标记的原型只需一次 git add -A 就可能进入 main。
2. 运行要简单。 通过项目自己的任务运行器用一条命令启动，或直接双击一个文件。根据仓库中的内容（package.json、Makefile、justfile、pyproject.toml、go.mod、Cargo.toml）识别任务运行器，不要想当然；并且告知用户要运行的命令，绝不要自行启动开发服务器。
3. 不持久化。 状态保存在内存中。通常需要探究的正是持久化问题，而不是依赖持久化。当问题确实涉及数据库时，使用一个不易被误认的临时数据库，例如 PROTOTYPE_wipe_me。
4. 跳过打磨。 不要编写测试，不要做抽象，也不要添加超出运行所需的错误处理。prototypekit 绝不运行完成门禁；没有任何内容需要门禁检查。
5. 展示状态。 每个操作（逻辑）或变体切换（UI）都要展示完整的相关状态。看不见的原型毫无帮助。
6. 问题得到解答就停止，不要等到觉得原型已经完成。范围框就是判断依据。

流程

1. 明确问题并画出范围框

写明问题及其所要促成的决策，遵循没有问题，就没有原型。

然后画出范围框：明确哪些情况包含在内，哪些情况明确不包含在内。这是规则 6 背后的机制，因为偏离范围的过程是渐进的，而且看起来很有成效。一个可用的技术验证会让人想再加一种情况，然后添加错误处理，接着抽出一个组件，结果这个一次性原型悄悄变成了一个没人决定要构建的应用。范围框之外的情况意味着需要做出新的决策：明确说出来并取得同意，不要顺手把它纳入范围。

范围框要写在原型文件自己的头部注释中，这样每次重新打开文件时都能看到；偏离范围的情况恰恰最容易在这里发生。将你不得不做出的任何假设也写在旁边：明确写出的错误假设可以纠正，未说出口的假设则不行。

2. 确定分支

• 状态模型、reducer、流程、后端模块、可行性问题 → 逻辑模式。
• 页面、屏幕、组件 → UI 模式。

如果情况模糊不清，且联系不到用户，就根据代码周边的内容选择默认模式，并在头部注明这一假设。

3. 标记、排除，然后编写

在创建第一个文件之前，先将标记模式添加到仓库的私有排除文件中，而不是纳入版本控制的 .gitignore。对纳入版本控制的忽略文件所做的修改本身就是一项未提交更改，会被提交和审查工具检测到；因此，这项技能声称不留下任何更改，却会留下差异。私有排除文件仅在本地生效，不会触碰纳入版本控制的文件。

git rev-parse --git-path info/exclude    # resolve the real path; never hardcode .git/info/exclude

向 Git 查询该文件的路径，不要想当然；因为在关联工作树中，.git 是一个文件而非目录，所以字面路径并不存在。仅当 *.prototype.* 和 *.prototype/ 尚未列出时，才追加它们。两种模式都要添加，因为文件匹配模式本身不会匹配目录。记录你追加了哪些行。 已存在的模式归添加它的人所有，清理时应保留。

在说明原型将放在哪里的同一句话中，告知用户你已完成此操作，让用户知道代码落地之前保护措施已经生效。

4. 逻辑模式

第一个维度：代码是否已经存在？

• 已经存在。 导入真实模块，并通过项目自己的运行器运行它，按项目支持的方式呈现：临时开发路由、CLI 测试框架或脚本。这正是身处工作树带来的好处，而且这是唯一能测试实际代码的方式。已有的逻辑绝不要重新手写；直接导入。如果无法导入，原型测试的就是你的打字能力。
• 你正在构思新逻辑。 使用一个独立文件。对于 Web 项目，文件应是无需构建步骤、无需服务器的 HTML，这样双击就能打开，也能作为单个附件分享给没有代码仓库的人。其他项目则使用该语言最简单的可运行单文件形式。

第二个维度：谁来读取输出？

• 由人来点击操作。 构建交互式界面：提供可以触发所有状态转换的自由操作控件，再加上引导式演练，让模型经历问题所涉及的特定难例——这些情况靠纸上推演没人能想明白。每次操作后都呈现完整状态。非开发者必须能够操作它，因为“感觉对不对”往往只有非开发者才能回答。
• 输出是一个数字或一段日志，例如：速度够不够快、这两个系统能否互操作、这个 API 是否如文档所说。编写一个打印测量结果的脚本，并注明测量时的条件。没有附带条件的数字不算证据。

四种组合都遵循相同的门槛、相同的范围边界和相同的处置方式；只有呈现目标不同。

5. UI 模式

在单一路由上提供三个结构迥异的变体，通过 URL 查询参数切换，并配一个小型悬浮切换器。一个路由意味着启动一次开发服务器就能覆盖所有变体，而且每个变体都有可以发给别人的链接。

差异化才是交付物，也正是最容易失败的部分。每个变体都必须在结构维度（布局、信息层级或交互模式）上有所不同，并明确说明它采用的维度。颜色、间距或圆角半径不同只是换了配色，不算变体。三个变体如果只是同一个想法的不同版本，那原型就失败了：你花了力气，却依然没有可供选择的方案。只有在确实无法指出三个不同维度时，才可以少于三个变体；此时应如实说明，而不是凑数。

遵循项目已有的路由和命名方式，绝不要为了存放模拟内容而另造顶层结构。

如果已安装 UI 技能，可以借鉴其中的反粗制滥造清单和无障碍底线，但**本任务中要覆盖其设计系统优先级规则，并明确说明这一点。**该优先级规则旨在强制统一，而统一与变体集的目的恰恰相反。如果没有安装这类技能（这是常见情况），只需遵循上述结构维度测试即可。

胜出方案是证据，而不是起点。 真正构建它是一个全新的任务：从真实文件着手，完全遵循规范，从头开始。

6. 写下结论

四行，放在哪里都行：

Question: <what we needed to know>
Built:    <what was made, and which cases it was driven through>
Showed:   <what actually happened>
Answer:   <the decision this unblocks, now settled>

直接根据范围框写 Built，说明驱动了哪些案例、涵盖了哪些状态转换。这样的具体描述能让答案在代码不再保留的情况下依然经得起时间考验，也能让六周后重新讨论这项决定的人了解情况。

把它写到提出问题的地方：

• 计划文档。 划掉这个未决问题，并在已定决策部分新增一行，引用原型。不要把已经回答的问题继续留在“未决问题”下；这会让所有后续读取计划的内容都误解计划的当前状态。这是 prototypekit 对受版本控制文件进行的唯一一次编辑，而且是有意为之，只会改动用户指定的文件。新定决策属于实质性编辑，因此如果计划中有一行 Grilled:，就在同一次编辑中删除该行并说明原因；计划需要重新审查。
• 议题。 留下评论。
• 两者都不是。 在聊天中报告。

如果原型回答的是与所问问题不同的问题，就报告并停止。 结论应说明所问问题仍未解决，并在旁边报告发现。运行中转而追查新问题，正是范围框要防止的偏移，只是披上了合理化的外衣；而且用户可能根本不希望追查新问题。唯一的例外是：当发现推翻了所问问题的前提（状态模型根本无法存在，因此“是否经得起检验”也就无从谈起）时，发现本身就是答案，应将其作为一个答案报告。

7. 暂存，然后清理

先提出是否暂存，作为一个单独的询问，并附上完整命令。默认不暂存，因为这项技能的前提是答案重要，而代码不重要：

git diff --cached --name-only    # record the staged set first
git checkout -b prototype-<slug> && git add -f <files> && git commit -m "prototype: <question>" -- <files> && git checkout -

-- 后的路径列表会将提交限制在原型文件内，因此用户此前已暂存的工作会继续保持暂存状态，不会被包含在暂存提交中。暂存后，再运行一次 git diff --cached --name-only，并确认结果与记录的文件列表一致。还原工作区会从工作树中移除已暂存的文件，因此下面删除时，这些文件已经不在了。

然后逐个确认后删除。 列出本次会话创建的每个文件，并逐一确认。这不是形式主义：被排除的文件是未跟踪文件，git 无法恢复它们，因此删除后就无法挽回，不像大多数删除操作。绝不触碰本次会话中不是由你创建的文件。

仅当所有原型文件都已删除时，才移除排除项，并且只移除你记录为追加内容的那些行。用户保留的任何文件都要用绝对路径报告，并保留其排除行，这样遗留文件就会保持为本地文件且易于查找，而不会悄无声息地变成可提交文件。

8. 交接

本节使用程序性语气：每句一条指令，主动语态，现在时，不用比喻。

变更内容。 报告创建了哪些文件、哪些文件已删除、哪些文件由用户选择保留、移除了哪些排除行、保留了哪些排除行、是否进行了暂存，以及是否移除了 Grilled: 行。

结论位置。 按路径指出结论的落点（计划文件及新增行、议题或聊天），并提供仍在磁盘上的任何文件的绝对路径。

下一步。 指定一项首选操作：

• 答案确定了一项计划决策 → 使用规划或审查技能继续推进；否则直接编辑计划。
• 某个 UI 变体胜出 → 使用 UI 技能正式实现；否则从头开始，并完全符合要求。绝不将原型直接升级为正式版本，因此不要复制一份去掉标记的原型。
• 答案确定了一项难以逆转的权衡 → 使用领域/决策技能将其记录为 ADR；否则手动编写 ADR。

只有在同类技能确实已安装时才提及；并始终提供纯手动的备用方案。

说明

• 绝不无人值守运行。 交付物是一项由人做出的判断，因此，在无人监督的情况下运行原型，只会删除一个文件，并产出没人阅读的答案。不要将其纳入自主工作流；逐文件删除确认让这一限制成为结构性约束，而非仅仅一项建议。
• 绝不直接推广。 将经过验证的决策纳入实际代码，意味着针对实际文件进行一次全新构建，并使用自己的输入和关卡，绝不能只是重命名原型。
• 不会触碰任何受跟踪文件，除非是用户指定作为判定结果目标的计划或 issue。排除项是有意设计为仅在本地生效。
• 不会提交（除非明确提供暂存选项），不会推送，不会创建 PR，不会提交 issue，也不会启动服务。
• 不是临时文件管理器。 它只会清理本次会话中创建的内容，不会处理其他内容。
• 工具。 allowed-tools 会屏蔽网络搜索和抓取，这与研究技能屏蔽 shell 的做法相对应。prototypekit 通过构建来给出答案，不引用任何来源；如果问题原本可以通过文档解决，那就是研究工作，而缺少相应工具可确保在遵守该字段的宿主环境中维持这一边界。
• 没有文件系统或 shell（例如基于浏览器的 Agent）？请用围栏代码块打印原型，并标明文件应保存到的路径；完全跳过排除和清理步骤，直接在正文中给出判定结果。由于没有写入任何内容，清理问题自然也就不存在。