prototypekit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseprototypekit
PrototypeKit
Some decisions can't be settled by reading. Does this reducer survive partial refunds? Is this library fast enough for our load? What should this settings page actually look like? prototypekit writes code whose only job is to answer one of those, then throws the code away and keeps the answer.
That inversion is the whole skill. The prototype is not a draft of the real thing, not a head start, and not a demo. It is an instrument, and instruments get put away. Everything below exists to keep the code disposable and the answer durable.
有些决策无法仅通过查阅资料来解决:这个reducer能否处理部分退款场景?这个库在我们的负载下速度足够快吗?这个设置页面实际应该是什么样的?PrototypeKit编写代码的唯一目的就是回答这类问题,之后就会丢弃代码,只保留答案。
这种倒置正是本工具的核心价值。原型不是成品的草稿,不是开发的起点,也不是演示。它是一种工具,用完就该被收纳。以下所有规则都是为了确保代码可随时丢弃,同时让答案能够留存。
When this fires
触发场景
"Prototype this", "spike this", "throwaway explore X", "does this state model hold up", "will this survive <hard case>", "is this fast enough", "do these two interop", "does this API do what its docs imply", "show me a few options for this screen", "mock up three versions", "/prototypekit".
Four things it deliberately is not:
- Not the build step. A build skill turns a settled intent into production code behind a test-and-build gate. prototypekit runs when the intent isn't settled because nobody has seen it work, writes code that fails every production standard on purpose, and gates on nothing.
- Not the research step. Research answers from primary sources and never builds. prototypekit answers by building and cites nothing. They're complements: when research hits a claim its sources won't settle, that claim comes here.
- Not the UI builder. A UI skill builds the screen that ships, conforming to the project's design system. prototypekit's mocks exist to be compared, chosen between, and deleted, and they deliberately break conformity, because three variants that all conform are three variants of one idea.
- Not a demo generator. This is the shape the request most often arrives disguised as. See No question, no prototype.
当用户提出以下需求时触发:“Prototype this”、“spike this”、“throwaway explore X”、“这个状态模型是否可行”、“这个设计能否应对<极端场景>”、“这个速度足够快吗”、“这两者能互操作吗”、“这个API是否如其文档所述那样工作”、“给我展示这个页面的几种方案”、“制作三个版本的原型”、“/prototypekit”。
它明确不是以下四类工具:
- 不是构建工具:构建工具将已确定的需求转化为符合测试和构建标准的生产代码。PrototypeKit在需求未明确时运行——因为没人见过需求落地后的效果,它生成的代码刻意不符合任何生产标准,也无需通过任何验证关卡。
- 不是研究工具:研究工具通过原始资料获取答案,从不进行构建。PrototypeKit通过构建来获取答案,不引用任何资料。二者互为补充:当研究遇到现有资料无法解答的问题时,就该交给PrototypeKit处理。
- 不是UI构建工具:UI构建工具生成可上线的页面,严格遵循项目的设计系统。PrototypeKit的原型仅用于对比、选择和删除,并且会刻意打破设计规范,因为三个都符合规范的变体本质上是同一思路的重复。
- 不是演示生成器:这是需求最常伪装成的形式。详见无问题,不原型。
No question, no prototype
无问题,不原型
Before writing a line, state the question and the decision it unblocks, one sentence each. If you can't write both, there is nothing to prototype yet.
An ask that resolves to "build me a demo", "make a proof of concept for the client", or "just try something" is production work under a softer name. Bounce it once, naming the reason and the route: it wants a plan and a real build, not a throwaway.
If the user reaffirms, the ask converts, not the skill. They've made a decision; arguing twice is not your job. Say plainly that this is production work, then do it as production work: no marker, no exclude entry, no disposal, and it stays on disk. prototypekit stops driving at that point. What you must never do is build a demo as a marked, disposed prototype, because that hands someone a thing to show a client and then deletes it.
在编写任何代码之前,先用一句话分别说明要解决的问题和该问题能推动的决策。如果无法同时写出这两点,说明目前还没有原型可做。
如果需求最终归结为“给我做个演示”、“给客户做个概念验证”或“随便试试”,本质上就是换了个温和说法的生产任务。拒绝一次,说明原因和正确路径:这类需求需要的是规划和正式构建,而非一次性原型。
**如果用户坚持,那么需求会转换,而非工具转换。**他们已经做出了决策,无需再争论。明确告知这是生产任务,然后按照生产任务的标准执行:不标记原型、不添加排除规则、不丢弃代码,代码会保留在磁盘上。此时PrototypeKit不再发挥作用。绝对不能将演示以标记为可丢弃原型的形式构建,因为这会导致给客户展示的内容被删除。
The six rules
六条规则
Both modes obey these.
- Throwaway from day one, and marked. Live next to what you're prototyping so the project's imports, aliases, and config just work. Name every file and every directory
*.prototype.*. The marker is not cosmetic: it is what the exclude entry matches, and an unmarked prototype is one*.prototype/away fromgit add -A.main - Trivial to run. One command from the project's own task runner, or a file you double-click. Discover the runner from the repo (,
package.json,Makefile,justfile,pyproject.toml,go.mod) rather than assuming one, and name the command for the user to run; never start a dev server yourself.Cargo.toml - No persistence. State lives in memory. Persistence is usually the thing being questioned, not something to lean on. When the question genuinely involves a database, use a scratch one named so nobody mistakes it, such as .
PROTOTYPE_wipe_me - Skip the polish. No tests, no abstractions, no error handling beyond what makes it run. prototypekit never runs a done-gate; there is nothing to gate.
- Surface the state. Every action (logic) or variant switch (ui) shows the full relevant state. An invisible prototype answers nothing.
- Stop when the question is answered, not when the prototype feels finished. The scope box is the check.
两种模式都需遵守以下规则:
- 从第一天起就标记为可丢弃:将原型放在待验证代码的旁边,确保项目的导入、别名和配置能直接生效。所有文件命名为,所有目录命名为
*.prototype.*。标记并非装饰:它是排除规则匹配的目标,未标记的原型可能会被*.prototype/误提交到git add -A分支。main - 运行方式极简:只需一条项目自身任务运行器的命令,或者双击文件即可运行。从仓库中识别运行器(如、
package.json、Makefile、justfile、pyproject.toml、go.mod),而非默认假设某一种,并且告知用户运行命令,不要自行启动开发服务器。Cargo.toml - 无持久化存储:状态仅存于内存中。持久化通常是待验证的对象,而非可依赖的基础。当问题确实涉及数据库时,使用临时数据库,命名需明确表明其临时属性,例如。
PROTOTYPE_wipe_me - 跳过打磨步骤:不写测试、不做抽象、除了让代码运行之外不做任何错误处理。PrototypeKit从不设置完成验证关卡,因为没有需要验证的内容。
- 状态可视化:每一个操作(逻辑)或变体切换(UI)都要展示完整的相关状态。不可见的原型无法回答任何问题。
- 问题解决即停止,而非等原型“完成”。范围边界就是停止的依据。
Procedure
操作流程
1. State the question and draw the scope box
1. 明确问题并划定范围边界
Write the question and the decision it unblocks, per No question, no prototype.
Then draw the scope box: the cases that are in, and the cases explicitly out. This is the mechanism behind rule 6, and it exists because the drift is gradual and feels productive. A spike that works invites one more case, then error handling, then a component extraction, and the throwaway quietly becomes an app nobody chose to build. A case outside the box is a new decision: say so out loud and get agreement, don't absorb it.
The box goes in the prototype file's own header comment, so it's in front of you every time you reopen the file, which is exactly where the drift happens. Put any assumption you had to make beside it: a stated wrong assumption is correctable, a silent one isn't.
按照无问题,不原型的要求,写出要解决的问题和能推动的决策。
然后划定范围边界:明确哪些场景是包含在内的,哪些是明确排除在外的。这是规则6的执行机制,因为范围会逐渐扩大,看似有效实则偏离目标。一个有效的Spike会让人想添加更多场景,然后是错误处理,接着是组件抽取,最终一次性原型会悄悄变成一个无人规划的应用。边界外的场景属于新决策:需明确告知并获得同意,不能自行纳入。
范围边界要写在原型文件的头部注释中,这样每次打开文件时都能看到,正好可以阻止范围偏离。同时写下所有不得不做出的假设:明确的错误假设可以修正,而隐藏的假设则无法察觉。
2. Route the branch
2. 选择分支模式
- A state model, a reducer, a flow, a backend module, a feasibility question → the logic mode.
- A page, a screen, a component → the UI mode.
Ambiguous and the user isn't reachable? Default by what surrounds the code and state the assumption in the header.
3. Mark it, exclude it, then write it
3. 标记、排除,然后编写代码
Before the first file exists, register the marker patterns in the repo's private exclude, not the tracked . A tracked ignore edit is itself an uncommitted change that commit and review tooling will pick up, so the skill would leave a diff behind while claiming it left nothing; the private exclude is local-only and leaves tracked files untouched.
.gitignoresh
git rev-parse --git-path info/exclude # resolve the real path; never hardcode .git/info/excludeAsk git for that path rather than assuming it, because in a linked worktree is a file, not a directory, so the literal path doesn't exist. Append and only if they aren't already listed. Both patterns ship, because the file glob won't match a directory on its own.
.git*.prototype.**.prototype/Say you did it in the same line you say where the prototype is going, so the user knows the guard is in place before any code lands.
在创建第一个文件之前,将标记模式注册到仓库的私有排除规则中,而非已追踪的。修改已追踪的忽略文件本身就是未提交的变更,会被提交和审查工具检测到,导致工具声称未留下任何痕迹却产生了差异;私有排除规则是本地仅有的,不会影响已追踪文件。
.gitignoresh
git rev-parse --git-path info/exclude # 解析真实路径;切勿硬编码.git/info/exclude通过git获取路径,而非直接假设,因为在链接工作树中是一个文件,而非目录,直接写路径可能不存在。仅当和未被列出时才添加这两个模式。两个模式都要添加,因为文件通配符无法匹配目录。
.git*.prototype.**.prototype/在告知用户原型存放位置的同时,说明已添加排除规则,让用户在代码落地前就知道防护措施已到位。
4. The logic mode
4. 逻辑模式
First axis: does the code already exist?
- It exists. Import the real module and run it through the project's own runner, rendering however the project can: a throwaway dev route, a CLI harness, a script. This is what living in the working tree bought you, and it's the only shape that tests the actual code. Never re-type logic you already have; import it. If you can't import it, the prototype is testing your typing.
- You're inventing it. One self-contained file. For a web project that's HTML with no build step and no server, so you double-click to open it, and it stays shareable as a single attachment to someone who doesn't have the repo. For anything else, that language's simplest runnable single file.
Second axis: who reads the output?
- A human clicking. Build the interactive shape: free-play controls that can fire every transition, plus guided walkthroughs that push the model through the specific hard cases the question is about, the ones nobody can reason about on paper. Render the full state after every action. A non-developer must be able to drive it, because "does this feel right" is frequently a question only a non-developer can answer.
- A number or a log, as in is this fast enough, do these two interop, does this API do what its docs imply. Write a script that prints the measurement and the conditions it was taken under. A number with no conditions attached isn't evidence.
Same gate, same scope box, same disposal across all four combinations; only the render target changes.
第一维度:代码是否已存在?
- 已存在:导入真实模块并通过项目自身的运行器运行,使用项目支持的方式渲染:一次性开发路由、CLI工具、脚本。这正是将原型放在工作树中的意义所在,也是唯一能测试真实代码的方式。切勿重写已有的逻辑;直接导入。如果无法导入,说明原型在测试你的代码编写能力。
- 需新建:使用独立的单个文件。对于Web项目,使用无需构建步骤和服务器的HTML文件,双击即可打开,并且可以作为单个附件分享给没有仓库权限的人。对于其他项目,使用对应语言最简单的可运行单个文件。
第二维度:谁来查看输出?
- 人工点击操作:构建交互式形式:自由操作控件可触发所有转换,加上引导式演练可将模型推送到问题涉及的特定极端场景(这些场景无法仅凭纸面推理)。每次操作后都要渲染完整状态。非开发人员必须能够操作,因为“这感觉是否合理”这类问题通常只有非开发人员才能回答。
- 数字或日志,例如“速度足够快吗”、“这两者能互操作吗”、“这个API是否如其文档所述那样工作”。编写脚本输出测量结果以及测量条件。没有条件的数字不能作为证据。
四种组合都遵循相同的验证关卡、范围边界和丢弃规则;仅渲染目标不同。
5. The UI mode
5. UI模式
Three structurally different variations on a single route, switched by a URL search param with a small floating switcher. One route means one dev-server start covers all of them and each variant has a link you can send someone.
Divergence is the deliverable, and it's the part that actually fails. Every variant must differ on a structural axis (layout, information hierarchy, or interaction model) and must name the axis it takes. Differing on color, spacing, or corner radius is a recolor, not a variant. Three variants of one idea is a failed prototype: you've spent the effort and still have nothing to choose between. Ship fewer than three only when three genuinely distinct axes can't be named, and then say so rather than padding the set.
Follow whatever routing and naming the project already uses, and never invent a new top-level structure to hold a mock.
When a UI skill is installed, borrow its anti-slop catalog and accessibility floor, but override its design-system precedence for this job only, and say so out loud. That precedence exists to enforce conformity, and conformity is the opposite of what a variant set is for. When no such skill is installed, which is the common case, the structural-axis test above stands on its own and is enough.
A winning variant is evidence, not a starting point. Building it for real is a fresh job against the real files, at full conformity, from scratch.
同一路由下的三种结构不同的变体,通过URL搜索参数和一个小型浮动切换器进行切换。单个路由意味着启动一次开发服务器即可覆盖所有变体,并且每个变体都有可分享的链接。
差异是核心交付物,也是最容易出错的部分。每个变体必须在结构维度(布局、信息层级或交互模型)上有所不同,并明确说明所基于的维度。仅在颜色、间距或圆角上有差异只是重新配色,而非变体。三个同一思路的变体是失败的原型:付出了努力却仍无法做出选择。仅当确实无法找到三个不同的结构维度时,才可以少于三个变体,并需明确说明,而非凑数。
遵循项目已有的路由和命名规则,切勿为了存放原型而新建顶层结构。
如果已安装UI工具,可以借用其防冗余目录和可访问性基础,但仅在本次任务中覆盖其设计系统优先级,并明确告知。设计系统优先级的存在是为了确保一致性,而一致性与变体集的目标相悖。如果未安装此类工具(常见情况),上述结构维度测试已足够。
胜出的变体是证据,而非起点。正式构建时需从零开始,在真实文件中按照完整规范重新实现。
6. Write the verdict
6. 编写结论
Four lines, wherever it lands:
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>Write Built straight from the scope box, so it names the cases driven and transitions covered. That specificity is what makes the answer durable without keeping the code, and it's what someone needs six weeks later when the decision gets relitigated.
Land it in whatever asked the question:
- A plan document. Strike the open question and add a row to its settled-decisions section, citing the prototype. Don't leave an answered question sitting under "Open questions"; that misrepresents the plan's state to everything downstream that reads it. This is prototypekit's one edit to a tracked file, it's deliberate, and it only ever touches a file the user named.
- An issue. Leave a comment.
- Neither. Report in the chat.
When the prototype answered a different question than the one asked, report and stop. The verdict says the asked question is still open and reports the finding beside it. Chasing the new question mid-run is the exact drift the scope box exists to catch, wearing a justification, and the user may not want it chased at all. One carve-out: when the finding invalidates the premise of the asked question (the state model can't exist, so "does it hold up" is moot), that is the answer, and it's reported as one.
四行内容,放在合适的位置:
问题:<我们需要了解的内容>
构建:<所制作的内容,以及测试过的场景>
结果:<实际发生的情况>
答案:<该决策现在已确定,可推动后续流程>构建部分直接来自范围边界,明确说明测试过的场景和覆盖的转换。这种具体性使得无需保留代码也能让答案留存,并且当六周后决策被重新讨论时,相关人员能了解当时的情况。
将结论放在提出问题的地方:
- 计划文档:划掉未解决的问题,并在已解决决策部分添加一行,引用原型。不要让已解决的问题留在“未解决问题”下;这会误导所有查看计划的下游人员。这是PrototypeKit唯一对已追踪文件的编辑,是刻意为之的,并且仅修改用户指定的文件。
- Issue:留下评论。
- 以上都不是:在聊天中汇报。
如果原型回答的问题与最初提出的问题不同,需汇报并停止。结论要说明原问题仍未解决,并附上发现的结果。在执行过程中追逐新问题正是范围边界要阻止的偏离行为,用户可能根本不想解决新问题。例外情况:当发现的结果推翻了原问题的前提(例如状态模型根本无法存在,那么“它是否可行”就没有意义了),这就是答案,需作为结论汇报。
7. Park, then dispose
7. 存档,然后丢弃
Offer the park first, as one ask, with the literal command. It is off by default, because the premise of this skill is that the answer matters and the code doesn't:
sh
git checkout -b prototype-<slug> && git add -f <files> && git commit -m "prototype: <question>" && git checkout -Then delete, confirmed per file. List every file you created this session and confirm each one individually. This is not ceremony: an excluded file is untracked, so git cannot recover it, which makes the delete final in a way most deletes aren't. Never touch a file you didn't create in this session.
Remove the exclude entry only when every prototype file is gone. Any file the user keeps gets reported by absolute path with its exclude line left in place, which is what keeps the leftover local-only and findable instead of quietly commit-able.
先提供存档选项,作为一个请求,给出具体命令。默认不存档,因为本工具的前提是答案重要,而代码不重要:
sh
git checkout -b prototype-<slug> && git add -f <files> && git commit -m "prototype: <question>" && git checkout -然后逐个确认删除文件。列出本次会话创建的所有文件,逐个确认删除。这不是形式主义:被排除的文件是未追踪的,git无法恢复,因此删除是不可逆的。切勿删除本次会话未创建的文件。
仅当所有原型文件都已删除时,才移除排除规则。如果用户保留了某个文件,需报告其绝对路径,并保留排除规则,这样残留文件会保持本地仅有的状态,可被找到,而非被悄悄提交。
8. Hand off
8. 交接
Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.
What changed. Report the files created, which were deleted and which the user chose to keep, whether the exclude entry was removed or retained, and whether the park happened.
Where it landed. Give the verdict's destination by path (the plan file and the row it added, the issue, or the chat), and the absolute path of anything still on disk.
Next. Crown one move:
- The answer settles a plan decision → fold it forward with a planning or grilling skill, otherwise edit the plan directly.
- A UI variant won → build it for real with a UI skill, otherwise implement it from scratch at full conformity. The mock is never promoted, so there is no copy of the prototype with the marker filed off.
- The answer settled a hard-to-reverse trade-off → record it as an ADR with a domain/decision skill, otherwise write the ADR by hand.
Name a sibling skill only when it's actually installed, and always give the plain fallback.
本节采用操作说明风格:每句一个指令,主动语态,现在时态,无比喻。
变更内容:报告创建的文件、已删除和用户选择保留的文件、排除规则是否被移除或保留,以及是否进行了存档。
结论位置:说明结论的存放路径(计划文件及添加的行、Issue或聊天),以及仍在磁盘上的文件的绝对路径。
下一步:明确一个行动:
- 答案解决了计划中的决策 → 使用规划或审查工具推进,否则直接编辑计划。
- UI变体胜出 → 使用UI工具正式构建,否则从零开始按照完整规范实现。原型绝不会被升级,因此不存在移除标记后的原型副本。
- 答案解决了难以逆转的权衡问题 → 使用领域/决策工具记录为ADR,否则手动编写ADR。
仅当相关工具已安装时才提及,否则给出通用 fallback 方案。
Notes
注意事项
- Never unattended. The deliverable is a human judgment, so a prototype run with nobody watching produces a deleted file and an answer nobody read. Keep it out of autonomous pipelines; per-file delete confirmation makes that structural rather than advisory.
- Never promoted. Folding a validated decision into the real code is a fresh build against the real files, with its own input and its own gate, never a rename of the prototype.
- Touches no tracked file except the one plan or issue the user named as the verdict's destination. The exclude entry is local-only by design.
- Does not commit (except the explicitly offered park), does not push, does not open a PR, does not file an issue, does not start a server.
- Not a scratch-file manager. It disposes of what it created this session, and nothing else.
- Tools. withholds web search and fetch, the mirror of how a research skill withholds the shell. prototypekit answers by building and cites nothing; if a question turns out to be settleable from documentation, that's a research job, and the missing tools make the boundary hold on hosts that honor the field.
allowed-tools - No filesystem or shell (e.g. a browser-based agent)? Print the prototype as fenced blocks with the paths they'd go to, skip the exclude and disposal steps entirely, and give the verdict inline. The disposal problem solves itself when nothing was written.
- 切勿无人值守运行:交付物是人工判断,无人监控的原型运行只会产生被删除的文件和无人查看的答案。不要将其加入自动化流水线;逐个文件确认删除的机制从结构上阻止了这种情况,而非仅作为建议。
- 绝不升级原型:将已验证的决策融入真实代码是针对真实文件的全新构建过程,有自己的输入和验证关卡,绝非重命名原型。
- 除用户指定的计划或Issue文件外,不修改任何已追踪文件。排除规则设计为本地仅有的。
- 不提交代码(除了明确提供的存档选项)、不推送、不创建PR、不提交Issue、不启动服务器。
- 不是临时文件管理器:仅丢弃本次会话创建的内容,不处理其他文件。
- 工具限制:禁用网页搜索和获取功能,与研究工具禁用shell的方式相反。PrototypeKit通过构建获取答案,不引用任何资料;如果问题最终可以通过文档解决,那属于研究任务,工具限制确保了边界清晰。
allowed-tools - 无文件系统或shell权限(例如基于浏览器的Agent)?将原型以代码块形式打印,并注明存放路径,跳过排除和丢弃步骤,直接在结论中给出答案。当没有写入任何内容时,丢弃问题会自行解决。