Verified against Cursor · 2026-07-28
Keep a frontend/backend API contract change in sync across both sides in one Cursor Agent pass
A brief for a cross-stack change that states the contract change as the single source of truth both sides must match, with an explicit order of operations and a final cross-check step, so the backend and frontend don't drift out of sync the way they do when each side gets migrated in a separate, disconnected session.
The prompt
Ready to copy — highlighted parts are example details you can swap.
This change modifies an API contract used by both the backend and the frontend in this repository. Both sides must end up consistent with the new contract below — not just individually correct against their own prior assumptions.
CURRENT CONTRACT
GET /api/orders/:id returns { id, status: "pending" | "shipped" | "delivered", total: number }.
NEW CONTRACT
status becomes a nested object: { id, status: { value: "pending" | "shipped" | "delivered", updatedAt: string }, total: number }.
BACKEND FILES THAT DEFINE OR IMPLEMENT THIS CONTRACT
app/api/orders/[id]/route.ts, lib/orders/types.ts, lib/orders/repository.ts
FRONTEND FILES THAT CONSUME THIS CONTRACT
app/orders/[id]/page.tsx, components/OrderStatusBadge.tsx, hooks/useOrder.ts
TRANSITION STRATEGY
Clean cutover — this is an internal admin tool with no external API consumers, so both sides can change together with no versioning needed.
ORDER OF OPERATIONS
1. Update the backend's contract definition (types/schema) first, and every backend file that implements it, so it actually returns the new shape.
2. Update every frontend file that consumes the contract to match, using the same names and shapes just established on the backend — do not independently reinterpret the new contract from the frontend side, treat the backend's implementation as the literal source of truth.
3. Search for any file on either side that references the old contract's field names or shape that wasn't in the lists above — this is exactly the kind of usage the file lists above can miss, and finding it now is much cheaper than a runtime error later.
FINAL CROSS-CHECK
Before finishing, pick three request/response examples and trace them manually through both the backend's actual return statement and the frontend's actual usage of the response, confirming the field names and types genuinely match on both ends — not just that both sides individually compile.
If TRANSITION_STRATEGY requires the old and new contract shapes to coexist temporarily, state exactly how a consumer tells which version it's looking at, since an untagged transitional shape is a bug waiting for the next person who doesn't know both versions exist.Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
A contract change handled as two separate requests — "update the backend" in one session, "update the frontend to match" in another — creates a specific and common drift risk even when both sessions individually succeed: each side gets its own independent interpretation of what the new contract means, and small differences in that interpretation (is the new status field's updatedAt an ISO string or a Date, is it nested under status or a sibling field) compile cleanly on both sides in isolation and only surface as a mismatch when the two are actually connected at runtime, well after the change has been reviewed and merged. Stating the ORDER_OF_OPERATIONS explicitly — backend contract and implementation first, frontend matched against what the backend actually returns rather than against an independent reading of NEW_CONTRACT — removes that drift risk structurally: the frontend consumer is instructed to treat the backend's real implementation as its source of truth, not the prose description of the new contract, which matters because prose is exactly where the ISO-string-versus-Date kind of ambiguity lives and code is where it gets resolved concretely. The Stage 3 search for unlisted files matters because BACKEND_FILES and FRONTEND_FILES are supplied by the person writing the brief, and a contract used by more call sites than the author remembered — a background job also reading order status, an admin export also formatting it — is exactly the kind of usage that a file list assembled from memory tends to miss, while a codebase-wide search for the old field names catches it mechanically regardless of whether anyone remembered it existed. The FINAL_CROSS_CHECK requiring manual tracing of concrete examples through both sides' actual code, rather than accepting "both sides compile" as sufficient, is the step that actually catches a contract mismatch, since TypeScript compiling cleanly on both ends only proves each side is internally consistent with its own type definitions — it says nothing about whether those two independently-declared type definitions actually agree with each other, which is precisely the gap a cross-stack contract change can fall into undetected.
Verified against
Cursor 2.2 · 2026-07-28
Changelog
- 2026-07-28 — Initial publish, verified against Cursor 2.2 Agent mode on a Next.js App Router full-stack contract change.
Need this built into your business?
If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
