Performance & Core Web Vitals Agent

    Audits page speed, Core Web Vitals (LCP, CLS, INP), bundle size, and optimization opportunities — then applies fixes to bring you within budget.

    Free & openInstall in 30 seconds

    What This Agent Does

    Audits and optimizes any web page for performance against a defined performance budget covering Core Web Vitals (LCP, CLS, INP, FCP, TTFB), JavaScript bundle size, and total page weight. Checks static generation, image optimization, font loading, JavaScript tree-shaking, third-party script impact, and CSS efficiency.

    Includes regression prevention rules for adding new components and pages, ensuring that new dependencies are justified, client-side rendering is minimized, and build output is monitored for size outliers.

    References & Sources

    What You Get

    • Performance budget with Pass/Warning/Fail thresholds for LCP (<2.0s), CLS (<0.05), INP (<150ms), FCP (<1.5s), TTFB (<600ms), bundle size (<150KB gzipped), page weight (<500KB)
    • Optimization rules by category: static generation (SSG), images, fonts, JavaScript, third-party scripts, CSS
    • Bundle analysis with per-chunk size breakdown
    • Regression prevention checklist for new components, pages, and dependencies
    • Performance audit scorecard with prioritized optimization recommendations

    Install

    Choose your preferred installation method. Both put the agent rule in the right place for Claude Code to discover automatically.

    Copy the rule below and save it as .claude/rules/performance-core-web-vitals.md in your project root.

    .claude/rules/performance-core-web-vitals.md
    # Performance & Core Web Vitals Agent Rules

When asked to audit performance, optimize page speed, or monitor Core Web Vitals, follow these rules. This agent ensures the site stays fast as content and components are added.

## Performance Budget

| Metric | Target | Warning | Fail |
|---|---|---|---|
| **LCP** (Largest Contentful Paint) | < 2.0s | 2.0-2.5s | > 2.5s |
| **CLS** (Cumulative Layout Shift) | < 0.05 | 0.05-0.1 | > 0.1 |
| **INP** (Interaction to Next Paint) | < 150ms | 150-200ms | > 200ms |
| **FCP** (First Contentful Paint) | < 1.5s | 1.5-2.0s | > 2.0s |
| **TTFB** (Time to First Byte) | < 600ms | 600-800ms | > 800ms |
| **Total bundle size** (JS) | < 150KB (gzipped) | 150-200KB | > 200KB |
| **Page weight** (total transfer) | < 500KB | 500KB-1MB | > 1MB |

## How to Run a Performance Audit

1. Identify the target page(s) or template type
2. Check if the page uses SSG (preferred) or SSR
3. Audit the component tree for performance issues
4. Check image handling (format, sizing, lazy loading)
5. Audit third-party scripts and their impact
6. Check font loading strategy
7. Output a performance scorecard

## Optimization Rules by Category

### Static Generation (SSG)
- All content pages (blog, glossary, landing pages, verticals) MUST use SSG
- Use `generateStaticParams` (or equivalent) for dynamic routes
- Incremental Static Regeneration (ISR) only when content updates require it -- prefer full static for infrequently changing content
- Never use server-side rendering (SSR) for content pages

### Images
- **Format:** Use your framework's image optimization component (e.g., Next.js `<Image>`, Astro `<Picture>`) for automatic format optimization (WebP/AVIF)
- **Sizing:** Always provide `width` and `height` props to prevent CLS
- **Lazy loading:** All images below the fold use `loading="lazy"`
- **Priority:** Hero images and LCP candidates use priority loading
- **No unoptimized images:** Never bypass optimization unless the image is an SVG
- **Max file size:** Individual images < 200KB after optimization

### Fonts
- **System fonts preferred** -- if custom fonts are used, load them via your framework's font optimization (e.g., `next/font`)
- **Font display:** Always use `display: 'swap'` to prevent FOIT (Flash of Invisible Text)
- **Subset:** Only load required character sets (latin for English content)
- **Preload:** Only the primary font weight/style. Load additional weights lazily.
- **No external font CDNs** -- they add extra DNS lookup + connection time

### JavaScript
- **Tree-shake aggressively** -- import only what's used: `import { Button } from '@/components/ui/button'` not `import * from '@/components/ui'`
- **Dynamic imports** for heavy components below the fold: `const HeavyChart = dynamic(() => import('./HeavyChart'), { ssr: false })`
- **No client-side rendering for static content** -- if it doesn't need interactivity, it shouldn't be a client component
- **Minimize client-side directives** -- push them as deep into the component tree as possible

### Third-Party Scripts
- **Audit every third-party script** for performance impact
- **Analytics:** Load asynchronously, after page load. Never block rendering.
- **No scripts in `<head>`** unless absolutely required (measurement pixels)
- **Script loading strategy:** Use lazy-on-load strategy for non-critical scripts

### CSS
- **Utility-first CSS** (Tailwind or similar) with purge ensures unused CSS is removed in production
- **No CSS-in-JS runtime** (styled-components, emotion) -- utility classes only
- **Critical CSS** should be handled by your framework automatically -- don't override this
- **No `@import` for external CSS** -- increases render-blocking time

## Performance Audit Output Format

```
## Performance Audit -- [Page URL or Page Type]
**Date:** [Date] | **Tool:** [Lighthouse/PageSpeed/Manual] | **Device:** [Mobile/Desktop]

### Core Web Vitals
| Metric | Value | Target | Status |
|---|---|---|---|
| LCP | [value] | < 2.0s | [Pass/Warning/Fail] |
| CLS | [value] | < 0.05 | [Pass/Warning/Fail] |
| INP | [value] | < 150ms | [Pass/Warning/Fail] |
| FCP | [value] | < 1.5s | [Pass/Warning/Fail] |
| TTFB | [value] | < 600ms | [Pass/Warning/Fail] |

### Bundle Analysis
| Chunk | Size (gzipped) | Status |
|---|---|---|
| Main bundle | [size] | [Pass/Warning/Fail] |
| Page-specific | [size] | [Pass/Warning/Fail] |
| Third-party | [size] | [Pass/Warning/Fail] |
| Total | [size] | [Pass/Warning/Fail] |

### Issues Found
| Issue | Impact | Fix | Priority |
|---|---|---|---|
| [description] | [LCP/CLS/INP/bundle] | [specific fix] | [P0/P1/P2] |

### Top 3 Optimizations
1. [Optimization + expected impact]
2. [Optimization + expected impact]
3. [Optimization + expected impact]
```

## Regression Prevention

### Before Adding New Components
- Estimate bundle size impact (check import size with bundlephobia.com or similar)
- Determine if the component needs to be a client component
- Check if an existing component could be extended instead
- If adding a new dependency: justify why a custom implementation isn't better

### Before Adding New Pages
- Verify SSG is configured (not accidentally SSR)
- Check that images use your framework's optimized image component
- Verify no unnecessary client components in the page tree

### Build-Time Checks
- Build output shows page sizes -- check for outliers
- Any page > 150KB (first load JS) needs investigation
- Any new route that uses SSR instead of SSG needs justification

---

## Out of Scope

This agent focuses on web performance and Core Web Vitals. The following are not covered:

- Content changes for SEO purposes
- Visual design changes
- Hosting and infrastructure decisions (CDN, edge functions, etc.)
- Database or API optimization (N/A for static sites)
- Accessibility compliance (covered by Accessibility Agent)
- Google SEO compliance (covered by Google SEO Agent)

    Usage

    Once installed, open your project in Claude Code and ask:

    Run a performance audit on the homepage and fix any issues exceeding the performance budget

    Claude Code will follow the scoring rubric, check every dimension, and output a structured scorecard with pass/fail per check and prioritized fix recommendations.

    Works Great With

    Audit43 checks6 dim

    Google SEO Compliance Agent

    43 checks across 6 dimensions based on Google Search Central's official guidelines. Audits any page, scores it to 100, and fixes what it finds.

    Audit4 dim

    Accessibility Audit Agent

    WCAG 2.1 Level AA compliance audit across 4 categories — Perceivable, Operable, Understandable, Robust — with automatic fixes for issues found.

    Audit68 checks7 dim

    Content QA Audit Agent

    68 checks across 7 dimensions: Technical SEO, Linking, E-E-A-T, Anti-Slop, AI Extraction, Schema, and AI Access. Scores your page and fixes what fails.

    Need a Custom Agent?

    We build custom Claude Code agent rules tailored to your team's workflows, content standards, and tech stack.

    Get in touch