Prototype

Prototype

A prototype is throwaway code that answers a question. The question decides the shape.

When to use

• "Does this logic / state model feel right?" → logic prototype
• "What should this look like?" → UI prototype
• Sanity-check a state machine or data model before committing; explore UI directions before picking one
• Triggers on "prototype", "throwaway", "mockup", "compare layouts", "validate the interaction", "sketch out", "try this quickly", "build a demo", "原型", "试做", "试这个方案", "搭个快速 demo"

Not for: production UI implementation (use frontend-design); production code (use implement).

Steps

1. Pick a branch

The two branches produce very different artifacts; getting this wrong wastes the whole prototype.

• Logic / state model → load references/logic.md. Single shareable HTML file with free-play buttons and tabbed guided walkthroughs a non-developer can drive.
• What it looks like → load references/ui.md. Several radically different UI variations on one route, switchable via ?variant= and a floating bar.

If the question is ambiguous and the user isn't reachable, default to whichever branch matches the surrounding code (backend module → logic; page/component → UI) and state the assumption up top.

2. Build it throwaway from day one

• Locate it close to where it will be used, but name it so a reader sees it's a prototype
• Trivial to run: one command in the task runner, or a single HTML file double-clicked
• No persistence by default — state in memory; no tests, no abstractions, no polish
• Surface the full relevant state after every action (logic) or variant switch (UI)

3. Capture the answer when done

Fold validated decisions into the real code. Capture the prototype itself as a primary source: commit to a throwaway branch (out of main), leave a context pointer on the implementation issue, and record the verdict + question settled. Main keeps only the validated decision.

Output: docs/design/prototype-findings.md — the question tested, the verdict, and the validated decision. The prototype code itself stays on a throwaway branch; only the finding is promoted to main as a durable record.

Verify

• Question being answered stated explicitly at the top of the prototype
• Correct branch chosen — not silently defaulted
• Runs from one command or one double-click, no setup required
• State visible after every action / variant switch
• Validated decision folded into real code; prototype on a throwaway branch

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — shared discipline (enforce simplicity, verify don't assume)
• ${CLAUDE_PLUGIN_ROOT}/references/design-principles.md — design discipline (hierarchy before decoration, design every state, recognize rather than recall).
• references/logic.md — single-shareable-HTML logic prototype: pure module, free-play + guided walkthroughs
• references/ui.md — toggleable UI variants: sub-shape A (existing page) vs B (throwaway route), floating switcher