How to Force Claude Code to Ship 100-Performance Lighthouse Code

The Technique — Performance Guardrails for AI Coding

Stop shipping bloated, slow code from Claude Code. The "AI Performance Guardrails" system creates a complete performance verification loop that forces Claude Code to validate every code change against three critical measures:

1. Synthetic Tests: Lighthouse with 100% performance score required
2. Real User Data: Google Analytics Core Web Vitals (must not regress)
3. Search Health: Google Search Console rankings and crawl errors

If any check fails, Claude Code automatically refactors its own code until it passes all three. This isn't just another linting tool—it's a feedback loop that teaches Claude Code what "good performance" means for your specific project.

Why It Works — The Self-Healing Loop

The magic happens in the CLAUDE.md file that Claude Code automatically loads. When you run npm run check-speed, the system:

• Runs Lighthouse CI against your current code
• Compares results against your baseline (.perf-baseline.json)
• If Lighthouse scores drop below 100, Claude Code gets the exact failure details
• Claude Code then refactors the problematic code
• The loop repeats until all checks pass

For teams with Google Analytics and Search Console configured, the system captures real user metrics as a baseline that Claude Code cannot regress below:

node scripts/check-analytics.js baseline

This captures Core Web Vitals (LCP, CLS, INP), top slowest pages, search queries, CTR, and any crawl/indexing errors.

How To Apply It — One-Command Setup

Option 1: Lighthouse Only (Start Here)

Drop these files into any project:

# Core files
curl -O https://raw.githubusercontent.com/dansinger93/AI-Coding-with-Speed-Guardrails/main/CLAUDE.md
curl -O https://raw.githubusercontent.com/dansinger93/AI-Coding-with-Speed-Guardrails/main/lighthouserc.js

mkdir -p scripts
curl -o scripts/check-speed.js https://raw.githubusercontent.com/dansinger93/AI-Coding-with-Speed-Guardrails/main/scripts/check-speed.js

# Install Lighthouse CI
npm install -D @lhci/cli

# Add to package.json
{
  "scripts": {
    "check-speed": "node scripts/check-speed.js"
  }
}

Restart Claude Code. Now every time you ask for code changes, Claude will reference the CLAUDE.md file that enforces Lighthouse checks.

Option 2: Full 3-Phase System (GA + GSC)

If you already have Google Cloud credentials:

curl -o setup.sh https://raw.githubusercontent.com/dansinger93/AI-Coding-with-Speed-Guardrails/main/setup.sh
bash setup.sh

The script will:

1. Ask for your GA Property ID and GSC Site URL
2. Prompt for your Google Cloud service account JSON file path
3. Install MCP servers (analytics-mcp, mcp-server-gsc)
4. Wire everything into Claude Code settings
5. Run a smoke test
6. Add the same package.json script

Restart Claude Code to load the new MCP servers. The full loop is now active.

What You Get — The Performance Guarantee

Every code change Claude Code suggests will be validated to achieve:

┌─────────────┬──────────────┬─────────────┬────────┐
│ Performance│ Accessibility│ Best        │ SEO    │
│ 100        │ 100          │ Practices   │ 100    │
│            │              │ 100         │        │
└─────────────┴──────────────┴─────────────┴────────┘

Plus: Real user metrics don't regress (GA Core Web Vitals, GSC rankings).

Graceful Degradation Strategy

The system is designed to work incrementally:

• Day 1: Just Lighthouse—still gives you 100% performance scores
• Week 2: Add Google Analytics for real user data
• Month 1: Add Search Console for SEO validation

If GA/GSC aren't configured, Phase 1 skips silently. Lighthouse still runs.

The CLAUDE.md Magic

The key file is CLAUDE.md, which Claude Code automatically reads. It contains instructions like:

# Performance Requirements

Before suggesting any code changes, you MUST:
1. Run `npm run check-speed` to validate against Lighthouse
2. Ensure all scores are 100
3. If scores drop, analyze the Lighthouse report and refactor
4. Repeat until all checks pass

Real user metrics from GA and GSC must not regress below baseline.

This turns Claude Code from a code generator into a performance-aware development partner.