A Prototype isthrowaway code used to answer a question. The question determines the shape.
Choose a branch
First identify which question is being answered: from the user prompt, the surrounding code, or by asking directly when the user is online:
- "Does this logic / state model feel right?" → LOGIC.md. Build a single, shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that drives the state machine through cases that are hard to reason about on paper, and that non-developers can also drive.
- "What should this look like?" → UI.md. Generate several very different UI variations on a single route, and switch between them via a URL search param and a floating bottom bar.
These two branches produce very different artifacts; choosing wrong wastes the entire prototype. If the question is genuinely ambiguous and the user is unreachable, default to the branch that better matches the surrounding code (backend module → logic; page or component → UI), and state the assumption at the top of the prototype.
Rules common to both branches
- Throwaway from day one, and clearly marked. Prototype code should live near where it will actually be used (next to the module or page being prototyped) so the context is clear; but name it so that anyone casually reading the code can tell it is a prototype, not production. For throwaway UI routes, follow the project's existing routing convention; do not invent a new top-level structure.
- 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 a single HTML file the user can open by double-clicking. Either way, starting it requires no thought. - No persistence by default. State is kept in memory. Persistence is something the prototype is meant to _check_, not something it should depend on. If the question explicitly involves a database, use a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.
- Skip polish. Write no tests, do no error handling beyond what is needed to "get it running", and make no abstractions. The point is to learn something quickly.
- Expose state. After every action (logic) or every variant switch (UI), print or render the full relevant state so the user can see what changed.
- Capture when done. Fold the validated decision into the real code, then save the prototype itself as primary source : commit it to a throwaway branch other than main, and leave a context pointer to that branch on the implementation issue. Also capture the answer in the issue or commit, that is, the verdict and the problem it solved. The main branch keeps only the validated decision.