AI‑Powered Change Contracts: Traceable PRD & Prototype Iterations Without Full Rewrites

Problem

During multi‑iteration development, product managers often deliver a new PRD that looks like a brand‑new project. Reviewers cannot see what changed relative to the previous version, and the HTML prototype is frequently regenerated entirely for visual reasons, overwriting pages that should remain unchanged. This makes it hard for AI‑assisted coding pipelines to determine the correct boundaries.

Root cause

The real issue is the absence of a change contract and explicit constraints. Without a baseline PRD and a clear list of what is added, kept, must‑change, or forbidden, the AI agent must guess, leading to accidental modifications of frozen pages or unnecessary full‑site regeneration.

Core goals of prd-iterate

Make the current version’s changes visible using the four categories Add / Keep / Must‑Change / Forbidden .

Inform downstream teams that the prototype may only be modified incrementally; a full regeneration is prohibited.

Design: lock three things from the start

Baseline required – If no previous PRD exists, start from zero with prd-three-layer-template. When the baseline is missing, list “to be supplied” instead of fabricating prior content.

Top‑level change map – The PRD must contain a module with four blocks, each tied to a concrete page or module name. Vague statements such as “optimize experience” are rejected.

Prototype handling – If an old prototype exists, copy it first and then modify only the pages listed under Add or Must‑Change. Pages not listed remain untouched, and the visual style must stay consistent; a full‑site regeneration is prohibited.

Decision tree for classifying a change

Baseline has no such capability/page?
 ├─ Yes → Add
 └─ No (baseline exists)
        ├─ Not touched this round → Keep
        ├─ Frozen / explicitly marked as non‑editable → Forbidden
        └─ Needs behavior / copy / flow / layout change → Must‑Change

Before filling the map, ask three questions:

Is this an expansion of scope (baseline missing) or a modification of existing behavior?

Is the target page listed in the Forbidden or frozen list?

Should acceptance test verify only the delta or require a full regression?

Conflict resolution: Forbidden > Must‑Change

This version "Must‑Change: xxx" conflicts with "Forbidden: xxx".
Default: honor Forbidden, do not implement the Must‑Change.
If business needs it, obtain explicit approval, move the item out of Forbidden, and record the decision.
Choose: A – Keep Forbidden / B – Approve change and update Forbidden list

No approval → the change is not included in the PRD and the HTML for that page stays unchanged.

Case study: registration flow v1 → v2

v1 consists of two steps (phone number, password) and a success page, without an invitation code. Reviewers froze the primary color, font, and step‑1 layout.

New requirements (two items):

Add invitation‑code validation to step 2.

Change the success page copy to “Welcome joined”.

Resulting change map (excerpt):

Add : Invitation‑code validation (baseline missing) → register-step2.html Must‑Change : Step 2 now includes invitation code; success page text changes.

Keep : Step 1, overall flow, primary color, font.

Forbidden : Design tokens; step 1 layout (no change required this round).

Acceptance criteria focus on the delta only:

Step 2 shows an invitation‑code input.

Success page title is “Welcome joined”.

Step 1 and design tokens remain unchanged relative to v1.

Prototype changes: copy the old HTML directory to …/v2/, edit only the files listed under Add or Must‑Change, and optionally tag the modifications with a “current version” badge for review.

Another conflict example

A stakeholder requests a “trendier” color scheme for the login page, but the Forbidden list already freezes the primary color and login‑page palette. According to the rule, this is a conflict; the default action is to keep the color unchanged. If the business insists, an explicit approval must be recorded, moving the item out of the Forbidden list.

When not to use prd-iterate

Brand‑new feature with no previous PRD – use prd-three-layer-template to write from scratch.

Only need an engineering change description or impact scope – adopt a Change Spec workflow.

Only need the OpenSpec four‑file set – follow the OpenSpec pipeline.

Existing code base, need minimal diff implementation – implement incrementally; avoid recreating the prototype.

Usage workflow

Prepare the following inputs:

Previous PRD (required).

Current round new requirements (required, preferably broken into individual items).

Previous clickable HTML prototype (strongly recommended; if present, modifications must be incremental).

Output directory and target version, e.g. …/feature/v2/.

Issue the command to the agent, for example:

请用 prd-iterate：基于 @v1/PRD.md，本轮需求是……
旧原型在 @v1/mockups/，输出到 …/v2/

Expected output structure:

v2/
  change-map.md    ← four‑block change map
  PRD.md           ← iterated PRD with map embedded at the top
  mockups/         ← copied prototype with incremental edits

Hard rules:

Forbidden overrides Must‑Change; conflicts require explicit human approval.

Empty or vague maps are invalid.

Lessons learned:

Classification must be precise; generic statements like “optimize experience” cannot be placed in any block.

Changing design tokens without approval breaks the contract.