A prototype isthrowaway code that answers a question. The question determines the shape.
Choose a branch
Determine which question is being answered—from the user's prompt, from the surrounding code, or by asking if the user is around:
- "Does this logic/state model feel right?" → LOGIC.md. Build a small interactive terminal app that pushes the state machine into cases that are hard to reason about on paper.
- "What should this look like?" → UI.md. Generate several distinct UI variations on a single route, toggled via a URL search parameter and a floating bottom bar.
The two branches produce very different artifacts—getting this 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 that apply to both
- Throwaway from day one, and clearly marked as such. Place the prototype code near where it will actually be used (next to the module or page it is prototyping) so the context is obvious—but name it so that a casual reader can see it is a prototype, not production code. For throwaway UI routes, follow whatever routing convention the project already uses; do not invent a new top-level structure.
- One command to run. Whatever the project's existing task runner supports—
pnpm <name>、python <path>、bun <path>, etc. The user must be able to start it without thinking. - No persistence by default. State lives in memory. Persistence is something the prototype _checks_, not something it should depend on. If the question explicitly involves a database, hit a temporary DB or a local file with a clear "prototype—erase me" name.
- Skip polish. No tests, no error handling beyond what is needed to make the prototype _runnable_, no abstraction. The point is to learn something quickly and then delete it.
- 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.
- Delete or absorb when done. Once the prototype has answered its question, either delete it or fold the validated decision into the real code—do not let it rot in the repository.
When done
The only thing worth keeping from a prototype is the _answer_. Capture it somewhere durable (a commit message, an ADR, an issue, or a NOTES.mdnext to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave a placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.