Loop-Closed Core Web Vitals Repair with chrome-devtools-mcp

Tier: Core · Workflow area: Performance & debugging

This playbook runs that loop on Core Web Vitals — LCP, INP, CLS — for a page you own, and establishes "no trace, no claim" as the team's performance discipline.

When to use

• •
  Search Console, CrUX, or your RUM dashboard flags a page failing Core Web Vitals thresholds (LCP > 2.5s, INP > 200ms, CLS > 0.1).
• •
  A redesign or dependency bump shipped and lab metrics regressed, but nobody knows which change did it.
• •
  You are about to accept an AI-suggested performance fix and want the evidence protocol that makes accepting it safe.
• •
  Performance work keeps stalling in debate — this loop replaces opinion with before/after traces.

Skip it for API-bound slowness (fix the backend first) or for a page you cannot run locally or on a preview URL the agent can reach.

Prerequisites

• •
  An MCP-capable agent (Claude Code, Cursor, Copilot agent mode) with chrome-devtools-mcp configured and able to launch or attach to Chrome.
• •
  The target page runnable at a stable URL — local dev server in production mode or a preview deploy. Dev-mode builds (unminified, no compression) produce misleading traces; trace production-ish builds.
• •
  A fixed lab condition you write down and reuse: CPU throttle (e.g., 4x), network throttle (e.g., Fast 4G), viewport, cold vs warm cache. Comparisons across different conditions are noise.
• •
  Your RUM or CrUX numbers at hand, so lab work targets the metric that is actually failing in the field.

The workflow

1. 1.

   Record the baseline trace under the fixed condition. Direct the agent explicitly:

   Copy

   Using chrome-devtools-mcp: emulate 4x CPU throttling and Fast 4G,
   navigate to http://localhost:3000/plans with a cold cache, and record
   a performance trace of the load. Report LCP, CLS, and TBT, the LCP
   element and its phase breakdown (TTFB / load delay / load time /
   render delay), and the top 3 insights from the trace.
   

   Save the reported numbers as the baseline. Run the trace twice; if the two runs disagree wildly, stabilize the environment before proceeding.

2. 2.

   Make the agent diagnose from the trace, not from vibes. The trace tells you where the metric's time actually went — demand that structure:

   • •
     LCP: which element, and which phase dominates. Render-delay-dominated LCP points at blocking scripts/CSS or client-side rendering; load-delay points at discovery (missing preload, image behind JS); load-time points at asset weight.
   • •
     CLS: which elements shifted and when — the trace names the culprits (late-loading fonts, unsized images/embeds, injected banners).
   • •
     INP/TBT: the longest tasks and what is on their stacks (see pb-36 for deep re-render forensics).

   Reject any diagnosis the agent cannot tie to a trace event. "Consider code-splitting" is only admissible if the trace shows script evaluation blocking the LCP phase it names.

3. 3.

   Apply one fix at a time, smallest first. Have the agent rank fixes by expected impact on the failing metric and by risk, then implement the top one — a fetchpriority="high" and preload on the LCP image, explicit dimensions on the shifting embed, deferring the analytics bundle. One change per loop iteration; batched fixes make the re-trace unattributable.

4. 4.

   Re-trace under the identical condition and compare. Same throttle, same cache state, same URL. The metric either moved past the threshold, moved insufficiently, or regressed something else (watch the other two vitals in the same report — LCP fixes that lazy-load aggressively have a habit of paying for it in CLS). Keep the fix only with the receipts; revert or iterate otherwise. Repeat the loop until the failing metric clears its threshold with margin.

5. 5.

   Lock the win in. Land the changes with before/after numbers in the PR description, add a Lighthouse CI (or equivalent) budget assertion at the achieved level so the next regression fails a check instead of a user, and confirm in RUM/CrUX over the following weeks that field data followed the lab win.

Tool variants

• Claude Code + chrome-devtools-mcp: the reference setup — the agent drives recording, reads insights, edits code, and re-traces in one session.
• Cursor / Copilot agent mode with the same MCP server: equivalent loop; keep the fixed-condition preamble in the repo's rules file so every session traces identically.
• DevTools Performance panel + AI assistance, no MCP: record manually, use the panel's insight explanations, paste the summary to an assistant for ranking. The loop is the same; you are the transport.
• Lighthouse / PageSpeed Insights: good for the initial "which metric, which page" and for CI budgets; the trace loop is where diagnosis and proof happen.

Verification

• •
  Baseline and final traces exist under the documented identical condition, and the failing metric crossed its threshold between them.
• •
  Every landed change maps to a named trace event or insight it addressed.
• •
  All three vitals are reported in the final trace — the fix did not trade LCP for CLS or INP.
• •
  A CI performance budget now guards the achieved numbers.
• •
  Field data (CrUX/RUM) confirms the direction within its collection window.

Pitfalls

• Accepting untraced suggestions. Models emit generic performance advice fluently — much of it irrelevant to your actual bottleneck. The trace is what makes the agent's output engineering instead of content.
• Comparing across conditions. Different throttle, cache state, or extension noise between runs fabricates wins and losses. Fix the condition, write it down, reuse it.
• Optimizing the lab number the field doesn't feel. If CrUX fails INP on mid-tier Android, a desktop no-throttle LCP win is decoration. Match lab conditions to the failing field segment.
• Batching fixes. Three changes and one re-trace tells you nothing about which mattered — and which quietly regressed something.
• Dev-mode traces. Unminified React with dev warnings produces phantom long tasks. Trace production builds.
• Declaring victory at threshold. 2.49s LCP passes today and fails after the next marketing pixel. Clear thresholds with margin and let the budget hold the line.

Restricted-environment variant

The loop runs entirely against local or preview environments — the MCP server drives a local Chrome; no page content needs to leave the machine except what the model sees in trace summaries.

• In-tenant agent endpoints: same loop with Bedrock/Azure-backed agents where client policy requires it.
• No-MCP fallback: record traces manually in DevTools, export the JSON, and share only the summarized metrics and insight names with an in-tenant assistant for ranking — the trace file itself can stay local.
• Fully offline: DevTools' built-in insights plus this playbook's diagnosis table cover the common cases without any model.

Success criteria

• •
  The target page passes all three Core Web Vitals in lab under the documented condition, with margin, and field data converges to passing.
• •
  The PR trail shows trace-pair evidence for every performance change — reviewers have started asking "where's the re-trace?" unprompted.
• •
  A budget check fails builds that would regress the recovered metrics.
• •
  The fixed-condition recipe and this loop are documented in the repo, and the next vitals regression is repaired by someone else using them.