Prototype First, Production Later

Agents make it easy to turn a design idea into a working interface quickly. That speed is useful. It lets designers test structure, interaction, copy, and information hierarchy before the team has committed to a direction.

The danger is that a prototype can look more finished than it is. It may skip edge cases, accessibility, data behavior, localization, performance, error states, analytics, permissions, and design-system constraints. A polished prototype can create false confidence.

The solution is not to stop prototyping. The solution is to label the work clearly and create a promotion path from prototype to production. Designers should be able to explore aggressively without creating a confusing pile of half-production code.

A prototype contract tells the agent what kind of artifact it is building. Is it a throwaway exploration, a clickable demo, a code spike, a stakeholder walkthrough, or a production candidate?

Without this contract, the agent may optimize for the wrong thing. A prototype should maximize learning. Production code should maximize maintainability, correctness, accessibility, and integration. Those goals overlap, but they are not the same.

The contract should say where the work lives, what data can be fake, which production files are off limits, what states must be represented, and what evidence the team needs after the prototype is built.

A design team wants to test a new onboarding flow for a project-management product. The flow has role selection, team invitation, template choice, and first dashboard setup. The team does not know whether users should choose a role first or start by importing a project.

The first agent run should not touch production onboarding files. It should create a prototype route, use representative data, and make the flow easy to inspect. The learning goal is not to prove that every API integration works. The learning goal is to see whether the order of decisions makes sense.

After review, the team promotes only approved patterns: the role-selection step, the template preview behavior, and the mobile task order. The invite-copy experiment is discarded. The fake analytics panel is archived as a future idea. The production build starts from the approved decisions, not from blind copy-paste of prototype code.

Prototypes need a physical boundary in the project. If exploration files sit beside production files with similar names, the next agent may treat them as product architecture. That is how temporary assumptions become permanent debt.

Use a prototype route, a separate examples directory, or a clearly marked app section. Keep the brief, learning goals, review notes, screenshots, and promotion plan near the prototype. Future agents should be able to see what was learned and what should not be shipped.

my-product/
├── DESIGN.md
├── AGENTS.md
├── src/
│   ├── app/
│   │   ├── onboarding/
│   │   └── prototypes/
│   │       └── onboarding-v2/
│   │           ├── page.tsx
│   │           ├── sample-data.ts
│   │           └── prototype-notes.md
│   └── components/
├── agent-workflows/
│   └── onboarding-prototype/
│       ├── brief.md
│       ├── learning-goals.md
│       ├── review-notes.md
│       └── promotion-plan.md
└── scripts/
    └── capture-onboarding-prototype.js

A prototype without learning goals becomes a style exercise. The agent can make it look convincing, but the team will not know what decision the prototype was meant to answer.

Good learning goals are narrow. They name the decision, the audience, and the evidence. For the onboarding case study, the team might need to learn whether role-first onboarding reduces confusion, whether template preview helps users choose faster, and whether the mobile order keeps the first useful action above the fold.

• Decision: what product or design choice should the prototype help make?
• Audience: who needs to react to it: users, founder, PM, engineer, sales team, or design lead?
• Evidence: what screenshot, recording, walkthrough, or task result will prove whether it worked?
• Boundary: what should the agent intentionally ignore for now?

A prototype prompt should explicitly say what is fake, what must be real, and what should not be changed. This is the difference between exploration and accidental production work.

Build a prototype, not production code.

Goal:
Test a new onboarding flow for role selection, team invite, template choice, and first dashboard setup.

Learning questions:
- Does role-first onboarding make the next step clearer?
- Does template preview reduce uncertainty?
- Does mobile keep the first useful action above the fold?

Rules:
- Put the work under src/app/prototypes/onboarding-v2/.
- Do not modify production onboarding routes.
- Use existing visual tokens and components where reasonable.
- Fake data is allowed, but label it clearly.
- Include loading, empty, and error placeholders where they affect the flow.
- Capture desktop and mobile screenshots after building.

Output:
- prototype route
- screenshots
- learning notes
- promotion plan for production work

Prototype code becomes unsafe when the team forgets which assumptions were fake. The agent may use static sample data, skip permissions, hard-code copy, omit analytics, ignore data loading, or build local components that look like shared system components.

Unsafe does not mean useless. A prototype can be excellent evidence and still be a bad production base. The review should identify which patterns are worth preserving and which implementation details should be thrown away.

Before a prototype becomes production work, run a promotion review. This review decides what to keep, what to rebuild, what to discard, and what needs a human design decision.

The agent should not promote its own prototype automatically. Promotion is a design and engineering decision. The agent can prepare evidence: screenshots, component map, missing states, accessibility risks, data assumptions, and a rebuild plan.

A weak promotion decision treats the prototype as almost done because it looks polished. A strong promotion decision names the exact decisions that survived review.

A production candidate should pass a stricter standard than a prototype. It needs real states, correct routes, resilient data behavior, accessibility checks, analytics where needed, and visual QA.

Use the checklist as a gate. If the prototype fails the gate, that does not mean it failed as a prototype. It means it is still doing its original job: helping the team learn before production investment.

Review this prototype for production promotion.

Check:
1. Which product decisions are validated?
2. Which parts should be kept as design patterns?
3. Which parts should be rebuilt in product architecture?
4. Which shared components already exist?
5. Which states are missing?
6. Which accessibility checks are required?
7. Which data and permission assumptions are fake?
8. Which screenshots prove the production version works?
9. Which files should remain prototype-only?

Output:
- keep
- rebuild
- discard
- production risks
- human decisions
- next implementation plan

Use this workflow whenever an agent is asked to explore a new screen, flow, or interaction. It gives designers speed without erasing the boundary between learning and shipping.

1. Write the learning goal before prompting.
2. Choose the prototype type: sketch, interactive demo, code spike, or production candidate.
3. Put the work in a clearly marked prototype area.
4. Tell the agent what can be fake and what must be realistic.
5. Capture screenshots and notes after the prototype is built.
6. Review against the learning goal.
7. Decide keep, rebuild, discard, or research further.
8. Write a promotion plan before touching production files.
9. Rebuild approved patterns in product architecture.
10. Run visual QA, accessibility checks, and production tests.