A prototype isthrowaway code that answers one question. The question determines the form.
Choose a branch
Identify which question is being answered—from the user's prompt, the surrounding code, or by asking directly when the user is online:
- "Does this logic/state model feel right?" → LOGIC.md. Build a small interactive terminal app that pushes the state machine through scenarios that are hard to reason about on paper.
- "What should this look like?" → UI.md. Generate several fundamentally different UI variants on a single route, toggled via a URL search parameter and a floating bottom bar.
The two branches produce very different artifacts—choosing the wrong one 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
- Disposable and clearly marked from day one. Place the prototype code near where it is actually used (next to the module or page it prototypes), so the context is obvious—but name it so a casual reader can tell it is a prototype, not production code. For throwaway UI routes, follow the project's existing routing conventions; do not invent a new top-level structure.
- Run with one command. Any way 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 the thing the prototype istesting, not something it should depend on. If the question explicitly involves a database, use a temporary database or a local file with a clear "PROTOTYPE—disposable" name.
- Skip polish. Write no tests, do no error handling beyond what is needed to make the prototyperunnable, and do no abstraction. The point is to learn something quickly and then delete it.
- Show state. After every operation (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 theanswer. Record it, along with the question it answered, somewhere durable: if the answer is a project rule/constraint that all subsequent implementation must follow long-term (such as "amount state is in cents" or "this aggregate is modeled with event sourcing"), propose writing it to RULES; if it is just a one-off conclusion for this design, record it in the commit message, task, or next to the prototype NOTES.md. If the user is online, recording it is a brief conversation; if not, leave a placeholder so they (or you, in the next round) can fill in the conclusion before deleting the prototype.