用 prototype 技能驱动 Agent 构建一次性原型从状态模型验证到 UI 变体切换的完整指南【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读本文围绕 skills13/skills 仓库中的 prototype 工程技能展开讲解如何让 AI Agent 以一次性代码回答一个设计问题的方式快速验证状态模型 / 业务逻辑手感或产出多种可切换的 UI 布局变体。读完你将掌握两条分支逻辑原型与 UI 原型的选择依据、六条通用纪律、逻辑单文件 Demo 与?variant变体切换的具体实现流程以及原型作为一手证据归档到分支的收尾方法。核心思想原型是回答一个问题的临时代码在 prototype/SKILL.md 的开篇定义中技能给出了一句总纲A prototype isthrowaway code that answers a question. The question decides the shape.原型是为回答问题而写的一次性代码问题决定形态。这句话有两层含义问题先行在写任何代码之前必须先明确要回答什么问题——是这个状态模型 / 逻辑手感对吗还是这个界面应该长什么样。回答错问题的原型无论做得多么精美都是纯粹的浪费。一次性是写作约束而非销毁承诺如 docs/engineering/prototype.md 所强调的throwaway 约束的是代码的写法——不加测试、不做超出能跑起来所需的错误处理、不建抽象、不引入持久化因为这些都不会帮助你在最短时间内学会那一件你真正想学的事。真正存活下来的是两样东西结论折叠进真实代码和原型本身作为证据停在主线之外的分支上。原型通常以/prototype方式被用户显式触发也会被模型在任务匹配时自动拾取见 skills/engineering/README.md 中 Model-invoked 分组。仓库将其定位为随时可用的独立技能你为回答一个设计问题而切入回答完再切出同时它也是其他技能机制的一部分——例如 wayfinder 的地图由决策票据构成而prototype正是四种票据类型之一用于界面应该如何呈现 / 行为应该如何运转这类靠讨论无法解决的阻塞问题。先选分支逻辑还是 UI原型的第一步不是写代码而是识别问题属于哪条分支。技能提供了明确的判定标准问题形态产物去向这个逻辑 / 状态模型手感对吗单个可分享的 HTML 文件自由点击按钮 标签页引导式走查LOGIC.md这个界面应该长什么样同一条路由上的若干结构迥异的 UI 变体靠 URL 查询参数和悬浮底栏切换UI.md两条分支产出的是完全不同的工件选错分支会浪费整个原型。判定手段有三个阅读用户的提示词、观察周边代码或者如果用户在场直接询问。当问题确实模糊且用户不可达时技能给出的默认策略是选择与周边代码更匹配的分支——后端模块对应逻辑原型页面或组件对应 UI 原型并在原型顶部明确标注这一假设。反过来说如果问的是应该长什么样却走了逻辑分支或者问的是状态模型却做了 UI都属于错配应立刻切换到另一条分支。两条分支都适用的六条纪律无论走哪条分支prototype/SKILL.md 的 Rules that apply to both 一节列出了六条硬性规则它们定义了原型与半成品生产代码的边界从第一天起就视为一次性并明确标注。原型代码放在它将实际使用的位置附近紧挨着它要验证的模块或页面让上下文一目了然但命名要能让随便一看的读者认出这是原型而非生产代码。若原型涉及临时 UI 路由则必须遵循项目既有的路由约定不要发明新的顶层结构。零门槛运行。UI 原型从项目任务运行器中的一条命令启动pnpm name、python path、bun path等逻辑 Demo 则是用户双击即可打开的单个 HTML 文件。启动方式不得需要任何思考。默认无持久化。状态只活在内存里。持久化恰恰是原型要检验的对象而不是它应当依赖的设施。只有问题明确涉及数据库时才去连一个 scratch 数据库或用本地文件且文件必须带有醒目的 PROTOTYPE, wipe me 命名。跳过打磨。不写测试、不做超出可运行所需的错误处理、不建抽象。目的是快速学到东西。把状态暴露出来。逻辑原型在每次动作之后、UI 原型在每次变体切换之后都要打印或渲染出完整的相关状态让用户看到到底发生了什么变化。完成时妥善留存。把经过验证的决策折叠进真实代码然后把原型本身作为一手证据primary source归档提交到主线之外的一次性分支并在实现票据上留下指向该分支的上下文指针。结论裁决 它所解决的问题也要记录在票据或一次提交里。主线只保留验证过的决策。分支一逻辑原型——单文件可分享 Demo当问题落在业务逻辑、状态转换、数据结构上时LOGIC.md答案是一个自包含的单 HTML 文件。它无需安装任何东西可以交给非开发者设计师、产品经理、领域专家亲手驱动状态模型让他们用自己的语言感受模型而不是读代码。适用场景我不确定这个状态机能否处理 X 之后发生 Y 的边界情况。这个数据模型真的能让我表达……这种情况吗我想在真正写 API 之前先感受一下它应该长什么样。任何想按按钮、看状态变化的场景。反之若问题只是应该长什么样这就不是正确的分支应转向 UI.md。五步流程第 1 步陈述问题。写任何代码之前先用一段话写清楚要验证什么状态模型、回答什么问题。这段话要放在 Demo 顶部的可见引导区而不只是注释——因为一个回答错问题的逻辑原型是纯粹的浪费把问题显式写出来无论用户此刻在旁观看还是稍后回来AFK都能被复核。第 2 步把逻辑隔离成可移植的纯模块。真正的逻辑回答问题的那个核心放进单个script块写成将来能整体搬到真实代码库的小型纯模块。页面是临时的一次性外壳而这个模块不是。模块形态取决于问题纯 reducer(state, action) state适合动作是离散事件、状态是单一值的情况状态机显式的状态与转移适合当前哪些动作合法本身就是问题一部分的情况作用于普通数据类型的一组纯函数适合没有隐含当前状态、只有转换的情况带清晰方法面的类或模块适合逻辑确实持有持续的内部状态的情况。选形态的标准是哪种最贴合问题本身而不是哪种最好接到页面上。模块必须保持纯净不引用 DOM、不碰document、内部不放按钮处理器——页面单向调用它反向不行。这正是原型在自身生命周期之外仍有价值的原因问题回答完毕后验证过的 reducer / 状态机 / 函数集可以原样搬进真实模块。第 3 步构建可分享的 HTML 文件。单文件、纯 HTML/CSS/JS无框架、无打包器、无服务端全部内联双击即开、可以邮件转发任何人打开就能运行。文案面向非开发者所有标签使用领域语言而非代码语言——按钮和状态读起来像业务本身而不是 reducer 的内部名称。页面按清晰层级自上而下布局标题 一句话说明这个 Demo 让你探索什么即第 1 步的问题当前状态完整相关状态渲染为可读面板带标签的字段而不是裸 JSON dump每次点击后重新渲染让变化可见必要时额外标注刚刚发生了什么变化帮助非开发者跟上自由点击按钮每个动作一个按钮、始终可用让任何人能以任意顺序戳模型每次点击派发对应动作并重渲染状态引导式走查一组场景每个场景一个标签页标签页内先是一段简短、用平实语言写的场景描述它构造了什么情境、该观察什么下面排列该场景按顺序要按的按钮。每一步都是真实按钮点击执行该动作并进入下一步开始走查时重置到已知初始状态保证场景每次都以相同方式运行。场景的选择要刻意覆盖那些在纸上难以推理的刁钻情况happy path、一个棘手的边界情况、一次应当非法的尝试。视觉上美观但克制干净的排版、充裕的留白、一个强调色即可不要动画、不要花活——任何与状态和按钮抢注意力的东西都不要。第 4 步交付。把文件发给对方或替他们打开。他们会时不时点走查、点自由按钮。最有价值的时刻是当对方说出等等这不该是可能的或咦我以为 X 会不一样——这些是想法本身的 bug而这正是整个原型存在的意义。如果对方想要新动作或新场景就加上去原型是可以演化的。第 5 步留存答案与原型。问题得到回答后先记录答案再按 SKILL.md 描述的方式归档原型。逻辑分支的具体映射是验证过的 reducer / 状态机 / 函数集搬进真实模块决策被吸收HTML 外壳随一次性分支一起留存——因为它本身就是自包含的单文件在那个分支上依然可以零成本地重新运行。逻辑原型的反模式不要加测试。需要测试的原型就不再是原型了。不要接真实数据库。除非问题就是关于持久化的否则一律使用内存状态。不要泛化。不做万一以后要支持 X 呢——原型只回答一个问题。不要把逻辑和页面搅在一起。纯模块一旦引用 DOM、document或按钮处理器就不可搬移了让页面始终只是纯模块之上的薄壳。不要引入框架、打包器或服务端。接收者双击即开的单文件才是可分享React 应用或 dev server 都违背了分享性。不要把 HTML 外壳发布到生产环境。页面是为人工点击而优化的真正值得保留的是它背后的逻辑模块。分支二UI 原型——同路由上的变体切换当问题是这页面长什么样时UI.md技能要求在同一条路由上生成若干结构迥异的 UI 变体用户在浏览器里通过悬浮底栏切换选定一个或从各变体里各取所爱其余全部丢弃。适用场景这个页面应该长什么样我想在敲定之前先看几个仪表盘方案。给设置页试几种不同布局。任何用户原本会花一整天在脑子里纠结三张模糊线框图的时刻。两种子形态强烈优先子形态 AUI 原型在被整个应用包围时更容易被评判——真实页头、真实侧栏、真实数据、真实密度。孤立的临时路由是真空每个变体在孤立状态下看起来都不错。因此只要存在一个可托管变体的现有页面就默认走子形态 A只有原型真的无处安放时才退到子形态 B。子形态 A对现有页面的调整首选。路由已经存在变体渲染在同一路由上由?variantURL 查询参数控制。现有的数据获取、参数、鉴权全部保留只切换渲染子树。即便原型针对的是还没有页面、但天然应住在某个页面里的东西仪表盘新分区、设置页新卡片、既有流程的新步骤依然算子形态 A——把变体挂进宿主页面即可。子形态 B新页面最后手段。仅当要原型化的东西确实没有可寄居的现有页面时使用例如全新的顶层界面或无法嵌入任何合理位置的流程。创建一个临时路由遵循项目既有的路由约定不要发明新的顶层结构命名要明显是原型例如路径或文件名里带prototype字样。同样使用?variant模式。在敲定子形态 B 之前先自检真的没有现成页面能嵌入吗空路由会隐藏掉有数据页面才能暴露出的设计问题。两种子形态的悬浮底栏完全一致。六步流程第 1 步陈述问题并确定 N。默认3 个变体上限 5 个——超过 5 个就不再是迥异而是噪音。在原型位置或文件顶部注释里用一行写下计划Three variants of the settings page, switchable via?variant, on the existing/settingsroute.无论用户在场要反驳与否这一行都成立。第 2 步生成真正迥异的变体。逐个起草变体每个都要满足页面目的与可用数据项目的组件库 / 样式体系TailwindCSS、shadcn、MUI、纯 CSS随项目而定清晰的导出组件名例如VariantA、VariantB、VariantC。变体必须在结构上不同——不同的布局、不同的信息层级、不同的主操作primary affordance而不是只换颜色。三个微调过的卡片网格不是 UI 原型只是壁纸。若两个草稿过于相似重做其中一个并明确给出不要使用卡片网格的指令。第 3 步把它们接起来。在路由上创建一个切换器组件UI.md 给出了伪代码需按项目框架适配// pseudo-code, adapt to the projects framework const variant searchParams.get(variant) ?? A; return ( {variant A VariantA {...data} /} {variant B VariantB {...data} /} {variant C VariantC {...data} /} PrototypeSwitcher variants{[A,B,C]} current{variant} / / );子形态 A现有页面下所有既有数据获取保留在切换器之上只有渲染子树随变体变化子形态 B新页面下临时路由挂在/prototype/name下挂载同一切换器。第 4 步构建悬浮切换器。一个固定在屏幕底部中央的小横条包含三件套左箭头循环切到上一个变体可回绕变体标签显示当前变体 key若变体导出名称则一并显示例如B (Sidebar layout)右箭头循环切到下一个变体可回绕。行为要求点击箭头更新 URL 查询参数使用框架自带的路由器如 Next 的router.replace、React Router 的navigate等使变体可分享、刷新后保持键盘←/→方向键同样可循环当焦点在input、textarea或[contenteditable]内时不得拦截方向键视觉上与页面明显区分如高对比度胶囊 轻微阴影让人一眼看出它不属于被评估的设计生产构建中隐藏以process.env.NODE_ENV ! production或等价检查兜底防止误合并的原型把底栏带给真实用户。切换器应放在单个共享组件里让两种子形态复用位置落在项目共享 UI 所在处。第 5 步交付。把 URL及?variant各键交给用户。他们随时会来回翻看最有价值的反馈通常是我想要 B 的页头配 C 的侧栏——那才是他们真正想要的设计。第 6 步记录答案并清理。某个变体胜出后记录答案哪个变体、为什么再按 SKILL.md 的方式归档原型。把胜者折叠进真实代码其余放到一次性分支而不是主线子形态 A把胜者并入现有页面败者变体和切换器从主线移除子形态 B把胜者提升为正式路由临时路由和切换器从主线移除。完整的变体集合是一手证据所以要进一次性分支而不是回收站——变体组件和切换器留在主线会很快腐烂并误导后来的读者。UI 原型的反模式只换颜色或文案的变体。那是微调不是原型。真正的变体在结构上不一致。变体间共享过多代码。共享一个Header没问题共享一个Layout就失去了意义——每个变体都应自由推翻布局。变体接真实变更操作。只读原型完全够用若变体需要变更数据指向一个 stub——问题是它该长什么样而不是后端能不能跑。把原型直接提升为生产代码。变体代码是在原型约束下写出来的无测试、极简错误处理折叠进正式代码时应当重写。收尾答案进主线原型进分支prototype/SKILL.md 与 docs/engineering/prototype.md 反复强调一个区别于传统认知的收尾方式原型不删除但也不进主线。一个完成的原型留下两样东西去向不同答案裁决 它所解决的问题被持久记录提交信息、ADR、实现票据均可——这就是主线保留的部分折叠进真实代码原型是答案所依据的、可运行的证据不删除但它也不属于主线——主线没有需要维护它的理由而且它会迅速腐烂。因此它被提交到主线之外的prototype/name一次性分支永不合并并在实现票据上留下指向该分支的上下文指针。主线保持干净探索过程对下一个接手者保持可发现、可重跑。常见疑问源自 docs/engineering/prototype.md等等原型不是应该删掉吗曾经是的构建、留答案、扔代码。对这一做法最尖锐的反对从来不在于速度而在于下一个会话接手的人手上有什么可用的东西。一段原型的手写摘要会丢掉让它有说服力的东西。因此原型现在被当作一手证据落在主线外的prototype/name分支上实现票据指向它。改变的是代码存放位置而不是纪律——它依然永不并入主线。它以前构建终端应用现在去哪了逻辑分支现在产出单文件 HTML 而非终端应用。终端应用只能由克隆了仓库且装有运行时的人驱动这恰恰把原型最需要征求意见的人排除在外设计师、产品经理、知道状态模型含义的领域专家。一个双击即开、能邮件转发的自包含文件任何人都能驱动。底层的纯逻辑模块没有变它依然是搬进真实代码的部分。Agent 在我本该 implement 的时候让我 /prototype。这是已知问题本质是命名问题。prototype是个宽泛且有吸引力的词流程不敏感的 Agent 在票据存在后很容易把它读成显然的下一步于是在设计已充分讨论定的场合仍按名字推荐它。如果你已经知道要构建什么下一步是/implement见 implement。只有某个具体设计问题真正悬而未决、且讨论无法解决时才动用原型。我是不是应该在构建任何生产功能之前先对整个应用做原型比如给潜在客户演示那是穿了本技能外衣的另一种工件。这里的原型只服务于一个问题的范围整个应用是什么不是一个问题。全应用原型没有自然的停止点会凭惯性变成生产应用清理永远不会发生按原型规则写出的代码无测试、无错误处理最终出现在用户面前。需要销售演示就把它当作演示专门构建并明确声明其中没有任何生产代码需要解决设计问题就把它裁剪到那个问题本身。怎么在独立会话里运行它原型住在自己的目录里会产生大量你不希望进入提出问题的那个线程的上下文所以应在别处运行、只带回答案。handoff 是双向的桥梁。这不就是最快烧 token 的方式吗如果你原型化了靠讨论就能回答的问题或让一个原型横跨整个功能确实会。真正该比较的不是token 对零而是token 对比构建了错误状态模型并在它有了生产调用方之后才发现。保持问题窄、运行短开销就是成比例的。它在什么情况下算工作正常docs/engineering/prototype.md 的 Its working if 一节给出了可验收的信号你能用一句话说出原型存在是为了回答什么问题而且它写在 Demo 顶部不只是在你脑子里不读代码的人也能驱动逻辑 Demo打开文件、在走查标签页里按按钮用自己的话描述所见有人说等等这不该是可能的或咦我以为 X 是这样——那是想法的 bug正是全部意义所在UI 变体在布局和信息层级上不一致而非只在颜色和文案上不一致且你收到的反馈是我要 B 的页头配 C 的侧栏在一次会话内就有答案。一天后还在构建说明问题太大拆开它结束时主线只含决策、不含任何原型实现票据指向仍持有原型的分支。它在技能生态中的位置按 skills/engineering/README.md 的分组prototype属于Model-invoked模型可自动拾取的工程技能。它最大的消费方是 wayfinderwayfinder 地图由决策票据组成而prototype是票据的四种类型之一——当阻塞问题是这该怎么呈现 / 这该怎么运转且任何讨论都无法解决时使用。原型票据以答案作为解决标志原型本身作为资产从地图上被链接。上下游邻居可追问的问题由 grill-me 与 grill-with-docs 处理追问不清的才来到这里得到的单行答案再回流进访谈下游验证过的状态模型或 UI 方向成为 to-spec 的确定输入它可以直接内联原型产出的决策密集片段而不是用散文转述。其余情况由 ask-matt 在整个技能集上为你路由。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考