drvoss Prototype
A prototype is disposable code that answers a question faster than debate. Keep it close to the real area, make it easy to run, and optimize for learning rather than polish.
When to Use
- The user says "prototype this", "try a few designs", or "let me play with it"
- A state model or workflow is hard to reason about on paper
- You need several UI directions before picking one
- The fastest way to answer the question is to build a small runnable artifact
When NOT to Use
| Instead of prototype | Use |
|---|---|
| You are building production-ready functionality | spec-driven-development |
| The main problem is root-cause analysis of broken code | diagnose |
| You already know the design and need safe cleanup | refactor-clean |
Prerequisites
- A concrete question the prototype should answer
- A place near the target code where throwaway work can live temporarily
- One obvious command the user can run locally
Workflow
1. Choose the branch
Decide which question you are answering:
- Logic / state question — build a tiny runnable terminal or script-based prototype that pushes the state machine through the tricky cases
- UI question — build several clearly different visual variants that can be switched from one route, page, or entry point
If the question is ambiguous and the user is unavailable, match the surrounding code and state the assumption clearly at the top.
2. Mark it as throwaway from day one
Put the prototype near the feature it informs, but name it so nobody confuses it with production code. Follow the project's existing routing or directory conventions instead of inventing a brand-new top-level structure.
3. Make it runnable with one command
Use the project's existing runtime:
npm run prototype:checkoutpython src\feature\prototype.pygo run .\cmd\prototype
The user should not need a multi-step setup just to learn from the prototype.
4. Strip everything non-essential
Default rules:
- no persistence unless persistence itself is the question
- no tests unless the prototype is proving a test technique
- no extra abstractions
- only enough error handling to keep it runnable
5. Surface the state
After each action or branch change, print or render the relevant state so the user can see what changed and why.
6. Capture the answer, then delete or absorb
The lasting artifact is the decision, not the prototype. When the question is answered:
- capture the takeaway in an issue, ADR, commit note, or nearby
NOTES.md - either delete the prototype or fold the validated idea into real code
Examples
Logic prototype
Create a tiny checkout state-machine runner that lets the user toggle events like
apply-coupon, expire-session, and submit-order, then prints the full state after
each step.
UI prototype
Build three layout variants for the same page and expose a simple variant switcher so the user can compare them quickly without branching the whole app.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "Let's make the prototype production-ready just in case" | That turns learning code into premature product code. |
| "We should hide the ugly internal state" | The whole point is to make the decision surface obvious. |
| "We'll remember what we learned later" | If the answer is not captured, the same question returns next session. |
Red Flags
- The prototype grows tests, persistence, and abstractions unrelated to the question
- Nobody can tell how to run it in one command
- The artifact stays in the repo after the decision is made, with no cleanup plan
- The prototype answers multiple unrelated questions at once
Verification
- The prototype names the question it is answering
- One command runs it locally
- The relevant state or variant is visible after each interaction
- The resulting decision is captured somewhere durable before the prototype is kept or removed
Tips
- Prototype the smallest slice that can disprove a bad design quickly
- Put a short "throwaway prototype" note in the file header or surrounding docs
- Follow with
refactor-cleanif a successful prototype is later absorbed into production code