Core Web Vitals on a site an agent built
Fast code, slow pages. The three vitals thresholds, the specific mistakes an agent makes on each, and why a screenshot taken after everything settles cannot see layout shift.
An agent writes fast code and still ships slow pages. The reason is that performance is not a property of the source, it is a property of what the browser does with the source, and almost nothing an agent can observe from inside a session tells it about that. The gap shows up as a site that passes every check you ran and scores badly the first time someone measures it properly.
The three metrics, and the thresholds that count
Core Web Vitals is three numbers, and all three are judged at the 75th percentile of real visits rather than on your laptop. That percentile is the part people skip, and it changes what you should be optimising: a page that is fast for you and slow for a quarter of visitors fails.
| Metric | Good | What an agent typically gets wrong |
|---|---|---|
| Largest Contentful Paint | 2.5 seconds or less | A hero image with no priority and no dimensions |
| Cumulative Layout Shift | 0.1 or less | Unsized embeds and a font that swaps late |
| Interaction to Next Paint | 200 milliseconds or less | A whole page made interactive for one toggle |
LCP: it is almost always the hero image
On a marketing site the largest element above the fold is a photograph, which means LCP is an image-loading problem wearing a metrics costume. An agent building the page will reach for the framework's image component and get most of it right, and then miss the one attribute that matters: the hero needs to be marked as priority so it is not lazy-loaded like everything below it.
Two more that recur. An unlisted quality value on the image component returns an error from the optimiser and breaks the image with no build failure at all, which is a defect we have shipped. And a hero served at its native resolution on a phone costs a second of nothing, because the browser downloads pixels it then throws away. The image component reference covers both.
CLS: the font swap and the unsized embed
Layout shift is the metric an agent is least equipped to notice, because it is invisible in the final state. The page looks right once everything has settled, and the whole defect happened during the settling. Two causes account for nearly all of it on a marketing site: a web font that loads after first paint and reflows the headline, and anything embedded without declared dimensions, which means maps, videos and third-party widgets.
Both are fixable in one line each, and neither will be fixed unless someone measures, because an agent asked whether the page looks right will take a screenshot after everything has settled and truthfully answer yes.
INP: the interactivity nobody asked for
Interaction to Next Paint measures how long the page takes to respond when someone taps. On a content site it should be effortless, and the way it stops being effortless is a page that became interactive to support one small thing. A mobile menu, a tab strip, an accordion: each is a reasonable feature, and each can pull the whole route into client rendering if the component boundary is drawn carelessly.
This is the one where an agent needs a rule rather than a judgement call, because the component boundary looks arbitrary from inside the file. Ours is that interactivity is a leaf: the smallest possible component is the interactive one, and it never contains content. That single line in the project instructions has prevented more performance work than any optimisation we have done, which is the argument the CLAUDE.md piece makes in general.
Lab numbers are a hypothesis, field numbers are the verdict
A local audit runs one page, once, on your hardware, over your connection. It is useful for finding causes and useless for judging whether you have a problem. Lighthouse is explicit about being a lab tool, and PageSpeed Insights shows real-visit data alongside the lab run precisely so you can see them disagree.
The sequence that works is to find causes locally and judge improvement from field data a few weeks later. Expecting the field number to move the day you deploy is the most common way people conclude performance work does not help.
Measure in a browser that composites
One hard-won note. Not every environment an agent can see a page in renders it the way a browser does. We have had a heading pass every measurement we took and be visibly broken on screen, because the tooling reported computed values from a renderer that never composited the layer. If performance or layout is the question, verify in a real browser at a real viewport. Everything else is a hypothesis, which is the same lesson as verifying what the agent built.
Gate it, or it comes back
Performance regresses quietly, one component at a time, and an agent will reintroduce the same patterns six weeks later because nothing in the repository says not to. The fix is the same as every other recurring defect: write the rule down where it is read, and gate it where it is cheap to check. One line about interactive boundaries, one about hero images, and a check on the built output. The hooks piece covers the gate, the SEO checklist covers what else to verify when the site goes live, and if you would rather not run any of it yourself, that is what we are for.
