Show It, Don't Describe It

One screenshot outruns three paragraphs of description. Step 2 of the cycle is unglamorous collecting work — you gather the things that show the agent what good looks like, before it writes a single line.

Your PRD says what to build and for whom. It does not say what the result should look like, which existing file the new code should resemble, or what the API returns when the last seat is already taken. References answer those. Whatever you leave out, the agent fills in — plausibly, which is worse than badly, because plausible is what you will not catch in the diff.

A screenshot answers questions you did not know to ask

Describing a screen in words means naming every decision: where the title sits, how much air surrounds the form, whether the button is full width, what order the fields go in, what happens at phone width. You will forget four of them. A picture carries all of them at once.

The second reason is better than the first. Anthropic’s Claude Code guide lists what counts as a check the agent can read by itself — a test suite, a build exit code, a linter, a script that diffs output against a fixture, and a browser screenshot compared with a design. The image that starts the work can also end it. You are not only describing the target; you are handing over the ruler.

• Put it in the repo, then name the path. refs/signup-desktop.png beats an image dropped into a chat window: the file is still there after you clear the session, and still there for the next person.
• Annotate it. Three arrows and three words — “this spacing”, “keep”, “delete this” — kill more ambiguity than a page of prose.
• Include the states nobody screenshots. Empty list, error message, form mid-submit. Those are the screens your users hit and the ones an agent invents.
• Say what to copy and what to ignore. An agent cannot tell which parts of a picture are the point. “Match the layout and field order, ignore the colours — ours are in src/styles/tokens.css” is one sentence that saves you a session of undoing.

The best reference is already in your repo

The strongest reference you own is a file in your own project that already does something similar. “Follow the pattern in src/components/EventCard.tsx” outperforms any style guide you could write, because that file is real, it compiles, it passes your tests, and it carries every convention you never wrote down.

This is also the official advice on project memory: Anthropic’s Claude Code guide says to keep anything readable from the code out of your instruction file, and to link long API docs instead of pasting them. Point, do not transcribe. Simon Willison’s pattern catalogue for agentic engineering lists a chapter called “hoard things you know how to do”; the title alone is the lesson.

Name the file, and name what about it to copy: the structure, the naming, the way it handles a loading state. Then accept the cost of the trick — point at your worst file and you get more files like your worst file. The agent has no taste. It has your repo.

For an API, link the page and paste the response

Two different jobs. The docs page tells the agent the contract. A real response tells it the truth.

Paste one success response and one error response, trimmed to a dozen lines each, with secrets and personal data replaced. A sample settles what prose argues about for several turns: the exact field spelling (userId or user_id), the date format, whether a missing value arrives as null or does not arrive at all, how errors are shaped, whether the list is paginated. Then add the sentence that saves the session: if the sample and the docs disagree, trust the sample.

Data samples work the same way. Twenty rows of the real shape, not a thousand — and put the ugly ones in on purpose. Kazakh names and words run long, and a fixed-width layout truncates them; nobody notices until a real person signs up. One very long name, one empty phone field, one address outside the Latin alphabet. The agent handles what it can see.

Do not paste the documentation site

Here is the trap, and it catches helpful people. You copy the whole API reference, all four guides and the migration notes into the prompt so that nothing is missing. You have just made the agent worse at the job.

Go back to the context window: attention is a finite budget and every token spends some of it. That is Anthropic’s own framing, and their fix is exactly this module — keep lightweight pointers like paths, URLs and queries, and load the detail at runtime instead of stuffing it in up front. Chroma’s Context Rot study, across 18 models in July 2025, adds the sharp edge: one plausible distractor already degrades the answer, and more distractors degrade it further. Docs for endpoints you will never call are a pile of plausible distractors. There is a bill, too — the whole conversation is re-sent on every request, so pasted docs are not paid for once, they are paid for on every turn after.

Reference the page, not the site. If you cannot name the specific page, you do not yet know what you are asking for — and that is useful information about your plan. When a session starts feeling forgetful, run /context and look at what is filling the window.

Describe a visual style in words an agent can check

With no design reference you get the default look, the one every model reaches for. Anthropic ran into this while designing a harness for long-running app builds: the evaluator grades generated apps on design quality, originality, craft and functionality, and weights the first two higher on purpose to fight generic output. If the people building these systems have to push against it deliberately, your one-line prompt will not win by accident.

Words that do nothing: modern, clean, beautiful, professional, sleek. They are compliments, not instructions. Words that work are the ones an agent can check itself against:

• one accent colour, everything else greyscale
• 8px spacing unit, nothing in between
• two text sizes for body copy, one for headings
• no gradients, no drop shadows, no corner radius above 4px
• a dense table, not a grid of cards
• Kazakh and English strings both fit without truncation

Then name one real thing you are imitating, give its URL, and say which part you mean: the typography rhythm, not the colours. Finish with the exclusions — in practice the list of what not to do carries more weight than the list of what to do.

Build the seat-reservation form for the QAIRU Event Sign-up page.

REFERENCES — read these first, in this order:

1. Layout target: refs/signup-desktop.png and refs/signup-mobile.png.
   Match the field order and the spacing rhythm. Ignore the colours —
   ours are in src/styles/tokens.css.
2. Pattern to follow: src/components/EventCard.tsx. Same file structure,
   same prop naming, same handling of the loading and error states.
3. API: [one docs URL — the single page for the endpoint we call].
   Real responses are in refs/seats-200.json and refs/seats-409.json.
   If the docs and the sample files disagree, trust the sample files.
4. Data: refs/signups-sample.csv — 20 rows, including a very long Kazakh
   name and one empty phone field. The UI must survive all 20 rows.

DO NOT read the rest of the docs site. If you need one more page, tell me
which page and why, and I will paste the part that matters.

Plan first, no code yet. In the plan, state which reference answers each
decision, and list every question the references do NOT answer.

Steal that last instruction. When the agent tells you which questions your references fail to answer, it has written the shopping list for your next round of gathering.

Before any build prompt, you should be able to answer four questions: what should it look like, what should the code look like, what does the data really contain, and what must the agent not read. If an answer starts with “I will explain it in the prompt”, go find the file instead.