prototype

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 13 处。

Entry SHA-256: 714de632d116bb73f65cdb5a882db15b9369a6713b9a47c0fad827848f0bfbe3

2. Why This Skill Is Clever

一句话核心机制

先把尚未解决的设计问题路由到“逻辑可操作演示”或“多方案 UI 对照”之一，再用刻意低成本、可观察、不可误认成生产代码的原型换取答案，最后把答案并入 main、把原型留在旁支作为一手证据。

触发与边界

直接来源（Direct source）： frontmatter 将触发场景限定为两类：快速检验状态模型 / 逻辑是否合理，或探索 UI 应该是什么样子。正文把原型定义为 throwaway code that answers a question，因此它不适用于已经确定做法、只剩正式实现的任务，也不适用于无明确停止点的整套产品建设。

支撑上下文（Supporting context）： LOGIC.md 把逻辑分支细化为单文件、可由非开发者操作的状态演示；UI.md 把 UI 分支细化为同一路由上的结构性变体。仓库的人类文档还明确区分了 prototyping 与 diagnosing-bugs：前者探索该构建什么，后者解释已构建内容为何出错。

解读（Interpretation）： 这个 skill 的核心不是“快速写代码”，而是选择一个能最快制造有效反馈的实验装置。若问题能靠一句澄清解决，使用原型反而浪费；若问题已收敛，则应进入正式实现。

信息架构 / 执行顺序

1. 先写出问题。 原型必须服务于一个可回答的设计问题。
2. 选择实验分支。 状态 / 逻辑问题进入 LOGIC.md；外观 / 信息架构问题进入 UI.md。
3. 歧义时做有证据的默认。 用户离线时，根据周边代码选择分支，并在原型顶部公开假设。
4. 用共同规则约束成本。 从第一天标成一次性、启动简单、默认内存状态、跳过测试与抽象、持续呈现状态。
5. 让用户操作并形成结论。 工件的价值来自暴露“这不该发生”或“我原以为会不同”之类认知差异。
6. 分离答案与证据。 已验证决定进入真实代码和 main；原型进入不合并的旁支，并由 issue 上的上下文指针保持可追溯。

这条顺序把“做什么实验”“如何压低实验成本”“实验结束后留下什么”分成三个独立决策，避免原型靠惯性演变成生产代码。

最巧妙的设计点

1. “The question decides the shape.” — 用未知问题反向选择工件。
   直接来源： 状态 / 逻辑与 UI 外观被拆成两个产出完全不同的分支。
   解读： 先选框架再找问题常会产出漂亮但无效的 demo；这里把分支判断设为最早的高杠杆决策。

2. “getting this wrong wastes the whole prototype” — 明示分流错误的总成本。
   直接来源： 在用户不可达且问题含糊时，必须读取周边代码并公开假设。
   解读： 默认策略不是偷偷猜测，而是让猜测可见、可纠正；这让异步工作既能继续，又不会把假设伪装成事实。

3. “Throwaway from day one” — 把临时性设计成可见属性。
   直接来源： 代码靠近未来用途放置以保留上下文，但命名必须阻止读者误认成生产代码，并遵守已有路由约定。
   解读： 这是一个双重约束：既不能把原型藏进脱离语境的角落，也不能让它以“临时”之名污染架构。

4. “No persistence by default” — 把被验证的变量与运行依赖分开。
   直接来源： 状态默认只在内存；只有问题明确涉及数据库时才使用临时存储。
   解读： 原型应尽量减少无关变量。若要检验状态模型，却先引入真实数据库，反馈会同时混入部署、数据和权限问题。

5. “Surface the state” — 把不可见推理变成可观察反馈。
   直接来源： 逻辑操作后或 UI 变体切换时，都必须展示完整相关状态。
   支撑上下文： LOGIC.md 进一步要求可读状态面板、自由操作与按场景引导的演练；UI.md 要求可分享且重载稳定的变体参数。
   解读： 这个规则把原型从“演示作者想展示的 happy path”变成用户能主动施压的可检查系统。

6. “capture the prototype itself as a primary source” — 不合并原型，也不销毁证据。
   直接来源： 答案进入 issue / commit 和真实代码；原型提交到 main 之外的一次性分支，并从实现 issue 链接过去。
   解读： 它解决了常见二选一：合并会留下低质量负担，删除又会丢失促成决定的可运行证据。旁支充当决策档案，而 main 只承载结论。

防失败机制与 trade-off

原文明确的不变量：

• 必须先判断问题属于逻辑 / 状态还是 UI 外观；选错会让整个原型失效。
• 异步默认必须依据周边代码，并把假设写在原型顶部。
• 原型从命名和位置上都要明确区别于生产代码。
• 启动必须极其简单；状态默认在内存；不做与回答问题无关的测试、错误处理和抽象。
• 每次操作或变体切换都要呈现完整相关状态。
• 已验证决定进入真实代码；原型只保存在不合并的旁支，并由 issue 指针连接。

防失败价值： 这些规则分别防止答错问题、隐性猜测、原型冒充生产、基础设施吞噬实验时间、反馈不可观察，以及探索证据在清理时消失。

权衡与可移植性风险：

• Skip the polish 明确要求不写测试和最少错误处理；速度更快，但必须依赖命名、分支隔离和后续重写，任何直接晋升到生产的行为都风险很高。
• “靠近实际用途”有助于保留上下文，却可能让原型被误提交；只靠命名约定而没有 CI 检查时，纪律是主要防线。
• 单文件 HTML 与项目任务运行器是具体的交付偏好，迁移到移动端、硬件或严格沙箱环境时需要替换载体，但“非开发者可操作”这一目标应保留。
• 只保存在一次性分支会降低 main 的噪声，但长期可发现性依赖 issue 的上下文指针和分支保留策略。
• 逻辑 / UI 二分很清晰，却不能覆盖所有实验类型，例如性能、数据质量或协议兼容性；迁移时可扩展分支，但仍应保持“一类问题对应一种最小实验形态”。
• frontmatter 没有显式禁止模型调用；触发语义可能依赖具体 agent harness，迁移时应重新确认自动调用边界。

可迁移原则

1. 用一句可证伪的问题定义实验。 工件不是目标，答案才是目标。
2. 让实验形态匹配不确定性的类型。 状态问题需要可操作转换；视觉问题需要结构性对照。
3. 把默认假设公开。 无法同步澄清时可以前进，但必须让用户一眼看见猜测。
4. 主动移除与问题无关的生产约束。 少依赖、少持久化、少抽象，同时设硬边界防止直接上线。
5. 分开保存结论与证据。 主线承载验证后的决定，旁路保留可重现的探索过程。

今日实践题

如果团队对结账页既不确定“优惠状态机是否正确”，也不确定“错误信息应该如何布局”，你会如何把它拆成两个问题，并为每个问题选择一个最小、可操作、不会误入生产的原型？

Evidence note

• 直接来源（Direct source）： 本报告完整展示的 skills/engineering/prototype/SKILL.md，用于还原定义、分支决策、共同规则、停止条件与归档方式。
• 支撑上下文（Supporting context）： 同目录 LOGIC.md、UI.md 与 docs/engineering/prototype.md，只用于解释两种分支工件如何实现，以及本 skill 与相邻工作流的边界；它们不属于所选入口原文。
• 解读（Interpretation）： 关于实验装置、反馈可观察性、变量隔离、旁支作为决策档案及可移植性风险的判断，是基于上述证据的工程分析。