Lesson 7 · Agentic Loop Engineering

The Screenshot Loop

No assertion can express "looks like the design." Visual verification closes the loop for UI work — if you run it as a loop with evidence, not a one-shot glance.

⏱ ~8 min🎯 Verify what tests can't see📊 Trust tier: semi (model-judged)

1 · Why UI defeats the obvious verifiers

A landing page can pass every unit test, every type check, every linter rule — and still have the hero text overlapping the nav at 1280px. Visual correctness isn't expressible as a pre-written assertion, because the failure space is "anything a human would notice." That's why Lesson 1 starred it as a non-obvious verifier: the only ground truth is looking, so you make the agent look.

2 · The canonical loop

Anthropic's best-practices page gives the workflow almost as a single prompt:

"[paste a screenshot of the design] Implement this design. Take a screenshot of the result and compare it to the original. List the differences and fix them." — Claude Code best practices (visual iteration workflow)
Design (target)→ Implement→ Screenshot result→ List differences→ Fix↻

The load-bearing phrase is "list the differences." It converts a vibe judgment ("does it look right?") into an enumerable diff — concrete, checkable items like "heading is left-aligned, design shows centered" or "card shadow missing." An enumerated list is something the loop can drive to zero; "make it look better" is not. This is the same move as Lesson 2's rubric rules: decompose the judgment into binary, checkable assertions — just generated fresh each iteration instead of written in advance.

Mechanically, the agent needs eyes and hands: in Claude Code that's the browser tooling (the Chrome integration, or a browser-automation MCP like the Puppeteer setup in Anthropic's harness, which tested "as a human user would" (harnesses post)) — navigate, screenshot, read the screenshot back as an image. Expect two or three iterations: the first pass typically catches layout, the second catches spacing and color.

3 · Where it sits on the trust spectrum

Be honest about what kind of verifier this is. The screenshot is ground truth — pixels don't lie about what rendered. But the comparison is a model judgment, which puts the loop on the semi-trust, model-judged tier of the taxonomy — the same tier as LLM-as-judge, with the same disciplines from Lessons 2 and 6:

✓ It reliably catches

  • Missing or extra elements
  • Gross layout breaks, wrong alignment
  • Wrong colors, missing images/icons
  • "It didn't render at all" — the most common real failure

✗ Don't trust it alone for

  • Few-pixel spacing drift, near-identical shades
  • Hover/focus/animation states (screenshot one explicitly per state)
  • Responsive behavior (screenshot per breakpoint)
  • Pixel-perfect contractual fidelity — use a deterministic pixel-diff tool as the gate, screenshots as the feedback
Two rules make it a real verifier: ① demand the artifacts — the screenshot and the difference list are the evidence in the final message ("have Claude show evidence rather than asserting success: the test output… or a screenshot" — best practices). ② define done as a count — "iterate until the difference list is empty," not "until it looks good." A countable list closes loops; adjectives don't.

4 · Composing it

The screenshot loop slots into the gates you already know. As Gate 1, it's the single prompt above. For higher stakes, compose tiers: a deterministic pixel-diff (e.g. a Playwright visual snapshot test) as a Stop hook for regressions on screens that must not drift, with the model-judged screenshot loop doing the creative iteration that gets you there. Deterministic gate guards the floor; model-judged loop climbs toward the target — the same division of labor as demo 03's ledger hook.


5 · Check yourself

Loading…

💬 Try it on a real screen: open any web project you have, give me (or a Claude Code session with browser tools) a target design or even a competitor screenshot, and run the loop verbatim: "Implement this. Screenshot the result, compare to the original, list differences, fix them. Show me the final screenshot and the list." Bring the difference lists back here — how they shrink per iteration is the loop made visible.

Where to go next