A prototype isthrowaway code that answers a question. The question determines its shape.
Choosing the branch
Determine which question is being answered—from the user's prompt, the surrounding code, or by asking directly if the user is present:
- "Does this logic / state model feel right?" → LOGIC.md. Build a shareable HTML file—free-play buttons plus a tabbed guided walkthrough—to push the state machine through the cases that are hard to reason about on paper, and that non-developers can also operate.
- "What should it look like?" → UI.md. Generate several distinctly different UI variants on a single route, switched via a URL query parameter and a bottom floating bar.
The two branches produce very different artifacts—pick the wrong branch and the whole prototype is wasted. If the question is genuinely ambiguous and the user can't be reached, default to the branch that better fits the surrounding code (backend module → logic; page or component → UI), and note this assumption at the top of the prototype.
Rules that apply to both
- Disposable from day one, and clearly labeled as such. Put the prototype code close to where it will actually be used (next to the module or page it prototypes for), so the context is obvious—but name it so that a casual glance makes clear this is a prototype, not production code. For throwaway UI routes, follow the project's existing routing conventions; don't invent new top-level structures.
- Zero-friction to run. A UI prototype starts with one command in the project task runner—
pnpm <name>、python <path>、bun <path>, etc. A logic demo is an HTML file the user can double-click to open. Either way, starting it requires no thought. - No persistence by default. State exists only in memory. Persistence is exactly what the prototype is meant totest, not something it should depend on. If the question explicitly involves a database, use a clearly named "PROTOTYPE — delete when done" temporary database or local file.
- Skip polish. No tests, no error handling beyond what's needed to "run", no abstractions. The point is to learn something fast.
- Put the state out in the open. After every operation (logic) or every variant switch (UI), print or render the full relevant state so the user can see what changed.
- Preserve when done. Fold any validated decisions into the real code, then preserve the prototype itself as aprimary source: commit it to a throwaway branch (kept off main), and leave context pointers to that branch on the implementation issue. Preserve the answer too—the conclusion and the problem it solved—in the issue or a commit. main keeps only the validated decisions.