Prototype version history: why every change is a version

Every prototype change should be saved as a new numbered version instead of overwriting the previous one. A prototype version history lets you compare before and after, go back without redoing work, and know at any moment which version the code actually implements. At a minimum, each version needs a number, an author, a change note and the version it started from, plus two pointers: the version you want (active) and the version in production (implemented).

What goes wrong when prototypes are overwritten

When a prototype is edited in place, each change erases the one before it. That seems harmless until someone asks a question the file can no longer answer:

• “The old header was better. What did it look like?”
• “Which version did we agree on in Tuesday’s review?”
• “Did the developer build the one with the side panel, or the one before?”
• “What exactly changed since I last looked?”

With a coding agent, the problem gets worse, because changes arrive faster. An agent can produce ten iterations of a screen in an afternoon. Without versions, you are always looking at the latest one and guessing at the rest.

What each version should record

A useful version is more than a snapshot. It carries enough context to be understood on its own:

Field	Why it matters
Number (v1, v2, v3)	A short, stable name you can say in a meeting or write in a ticket
Author	Tells a human decision from an agent proposal
Date	Orders events when several people work on the same screen
Change note	Says what changed, so nobody has to diff two images by eye
Base version	The version this one started from, which is not always the previous number
Kind	A drawn prototype, or a capture of the real app

The base version is the field teams forget. If v5 was made from v3 because v4 was a dead end, a history that only says “v5 follows v4” is misleading.

Active and implemented: two pointers, not one

Most version tools track one “current” version. For a prototype that will become code, you need two:

• Active: the design you currently want.
• Implemented: the design that is coded and shipped.

When they are equal, the screen is done. When they differ, the gap is the to-do list, and it is precise: “Checkout · error is active at v6, implemented at v4.” Nobody has to reconstruct which review decided what.

The two pointers also make one dangerous moment visible. If someone makes a different version active on a screen that is already implemented, production does not change by itself. Someone has to decide whether the code should follow. Keeping prototypes and code aligned is its own topic, covered in keeping the prototype and the code in sync.

Writing change notes that help

A change note is read later, by someone who was not there. Write it for that person.

Weak notes:

• “Updates”
• “Fixed as requested”
• “v2”

Useful notes:

• “Moved the filters from the top bar into a left panel; table rows 48px to 40px.”
• “Error message now above the form instead of under the button.”
• “Recreated from the capture of the live app; no design change.”

A checklist for each note:

1. Name the elements that changed.
2. Give before and after values when they are numbers or colors.
3. Say what did not change when it could be assumed (“same data, same copy”).
4. Keep the reason in the ticket or the review, not in the note, unless it is one short clause.

When the agent writes the notes, ask for this format once and it will follow it. The same discipline applies to requests: a change request an AI agent gets right names the element, the change and what must stay.

Rolling back without losing history

Going back is where overwriting hurts most. With versions, there are two clean ways to do it:

• Make the old version active again. Nothing is lost: the newer versions stay in the list.
• Copy the old version into a new one. The history then reads v5, v6, v7 = copy of v5. Useful when a tool only moves forward.

What you should not do is delete the newer versions. Rejected ideas come back, often in a different context, and a version you deleted is a version you rebuild.

A simple rule for teams: nothing is ever overwritten, and choosing is a separate act from creating. Creating a version is cheap and can be done by anyone, including an agent. Choosing which version is active is a decision, and it belongs to a person.

Versions made by people and versions made by agents

Once humans and agents both add versions, authorship matters. A person who adjusted a padding by hand, or duplicated a screen to explore an idea, made a design decision. An agent that later rewrites the screen from its own earlier version would silently undo it.

Two rules prevent that:

1. The agent starts from the latest human version, and says so by recording it as its base version.
2. If it wants to replace a human version without starting from it, it asks first.

This is also why comparing options works better as parallel versions than as successive edits. Comparing design variants before writing code keeps several proposals side by side, and the ones you did not pick stay in the history.

How agentappbuilder keeps prototype versions

agentappbuilder is a canvas where Claude Code prototypes your screens as HTML frames, one frame per screen state. Each frame keeps every version, numbered v1, v2, v3 in order, and versions are never overwritten. The mechanics follow the principles above:

• A version the agent adds becomes active at once, with its change note. Variants wait for your choice instead.
• You choose the active version in the right panel of the canvas. The agent cannot choose it: if you ask it to go back, it adds a new version, for example a copy of v2 as v4.
• Compare shows two versions of the same state side by side, by default the active one and the one before it.
• The panel says “Implemented: vN” or “Not implemented yet”, and a small blue dot marks a state whose active version differs from its implemented one.
• If you make another version active on a frame that is already implemented, the agent asks you at its next request whether production should follow.
• Versions you make yourself, by duplicating a state or editing it on the canvas, are signed by you, and the agent starts from them.

The Version section of the concepts page defines each of these, and going back to an older version shows what to say to your agent.

The habit in one sentence

Never overwrite a prototype: add a version with a note, keep active and implemented apart, and let a person choose. It costs nothing when things go well, and it answers every “wait, which one?” when they do not.