We merge a lot of agent UI now. Six months later someone asks “why does this form validate zip before city?” and the PR description just says “agent polish.” The diff is gone from working memory. The prompt that made the decision is gone too.
I started treating the prompt that shipped like a tiny ADR. Not a ceremony. One short file (or PR note) next to the change so the next human — or the next agent — can see what we asked for , not only what landed .
What goes in the tiny ADR
Keep it under ~15 lines. I use this shape:
## Prompt ADR — ShippingForm zip-before-city (2026-11-05)
**Goal:** Require zip before city on blur for US addresses. **Prompt (verbatim):** … **Files touched:** `ShippingForm.tsx` , `shippingValidation.ts` **Rejected alternatives:** city-first (matches old mock); shared schema with Checkout (too wide for this PR) **Follow-ups:** none / link issue
Enter fullscreen mode
Exit fullscreen mode
Verbatim matters.…