prototype

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prototype

A prototype is throwaway code that answers a question. The question decides the shape.

原型是用于回答某个问题的一次性代码。原型的形态由问题决定。

Pick a branch

选择分支

Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:

"Does this logic / state model feel right?" → LOGIC.md. Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
"What should this look like?" → UI.md. Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.

The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.

根据用户提示、上下文代码判断需要回答的问题；如果用户在线，也可以直接询问：

“这组 logic / state model 是否合理？” → LOGIC.md。构建一个可共享的单文件 HTML（自由探索按钮和带标签页的引导式演示），让 state machine 覆盖那些很难在纸面上推理的场景，并且非开发者也能轻松操作。
“UI 应该是什么样子？” → UI.md。在单一 route 上生成几种截然不同的 UI 方案，可通过 URL search param 和悬浮底部栏切换。

这两个分支产出的 artifact 差异很大，因此分支判断错误会让整个 prototype 付诸东流。如果问题确实存在歧义且联系不上用户，则默认选择更符合上下文代码的分支（backend module → logic；page 或 component → UI），并在 prototype 顶部说明这一假设。

Rules that apply to both

两个分支都适用的规则

Throwaway from day one, and clearly marked as such. Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
Trivial to run. A UI prototype starts from one command in the project's task runner:
```
pnpm <name>
```
,
```
python <path>
```
,
```
bun <path>
```
, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
No persistence by default. State lives in memory. Persistence is the thing the prototype is checking, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.
Skip the polish. No tests, no error handling beyond what makes the prototype runnable, no abstractions. The point is to learn something fast.
Surface the state. After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
Capture it when done. Fold any validated decision into the real code, then capture the prototype itself as a primary source: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too (the verdict and the question it settled) in the issue or a commit. The main branch keeps only the validated decision.

从第一天起就是一次性代码，并且必须清楚标明。 将 prototype 代码放在其实际使用位置附近（紧邻所针对的 module 或 page），让上下文一目了然；但命名时需让普通读者看出这是 prototype，而非 production。对于一次性 UI route，应遵循项目已有的 routing convention，不要另造新的顶层结构。
易于运行。 UI prototype 通过项目 task runner 的一条命令启动：
```
pnpm <name>
```
、
```
python <path>
```
、
```
bun <path>
```
等。logic demo 则是一个可由用户双击打开的单文件 HTML。无论采用哪种方式，都无需思考即可启动。
默认不持久化。 State 保存在内存中。Persistence 是 prototype 正在验证的内容，而不是它所依赖的基础。如果问题明确涉及 database，则使用 scratch DB 或 local file，并将文件清楚命名为“PROTOTYPE, wipe me”。
跳过打磨。 不写 tests，不做超出“让 prototype 能够运行”所需的 error handling，也不创建 abstractions。目标是快速获得结论。
清晰呈现 state。 每次操作后（logic）或每次切换方案时（UI），打印或渲染所有相关 state 的完整内容，让用户看到具体变化。
完成后归档。 将验证过的决策整合到真实代码中，然后把 prototype 本身作为 primary source 留存：提交到一次性 branch，不合并到 main，并在 implementation issue 上留下指向该 branch 的上下文指针。同时，在 issue 或 commit 中记录答案（最终结论及其解决的问题）。main branch 只保留经过验证的决策。