Claude Code 웹 성능 Lighthouse 최적화 스킬 — "라이트하우스 점수 올려줘" (web-performance)

스킬 파일 제공

구매하시면 SKILL.md, 측정 스크립트 scripts/measure.sh, 수정 패턴 references/playbook.md, 설치 안내 README 가 담긴 압축 파일을 받으실 수 있습니다. ~/.claude/skills/ 에 폴더째 두면 자동으로 인식됩니다.

web-performance.zip 다운로드

Claude Code 웹 성능 Lighthouse 최적화 스킬 —

PageSpeed 점수가 70 언저리에서 안 움직입니다. 리포트를 열면 항목이 수십 개이고, Claude 에게 "성능 좀 올려줘"라고 하면 이미지 lazy-load, 압축 미들웨어, preload 같은 일반론을 한꺼번에 적용합니다. 점수는 그대로이거나 오히려 떨어지고, 무엇이 효과였는지는 아무도 모릅니다.

왜 만들었나

한 사이트의 모바일 성능 점수가 70, LCP 가 17.3초였습니다. 원인을 찾아 보니 일반론이 말하는 곳과 달랐습니다. 첫 페인트를 9초 가까이 막던 것은 외부 CDN 의 폰트 CSS 한 줄이었고, 앱에 압축 미들웨어를 넣는 조치는 앞단 nginx 가 이미 gzip 을 하고 있어 실사용자에게 아무 효과가 없었습니다. 폰트를 preload 하자 오히려 490KB 가 크리티컬 패스에 끼어들었습니다.

그래서 순서를 고정했습니다. 먼저 실제로 측정하고, 점수 기여가 큰 원인 하나만 고치고, 다시 측정한다. 이 루프와 그때 밟은 함정들을 스킬로 묶었습니다.

무엇을 하나

headless Chrome 으로 실측 — measure.sh 가 Lighthouse 를 돌려 JSON·HTML 리포트와 콘솔 요약(4개 카테고리 점수, FCP·LCP·TBT·CLS·SI, LCP 요소, 개선 기회, 통과 못한 진단)을 남깁니다. GUI 창은 열지 않습니다.
점수 가중치 순으로 진단 — LCP 25%, TBT 30%, CLS 25% 처럼 어디를 고쳐야 점수가 오르는지부터 판독하고, 원인을 측정 JSON 근거로 특정합니다.
승인 후에만 수정 — 그 전까지는 측정, 진단, 우선순위 제시만 합니다. 수정은 한 번에 한 원인 군, 그리고 재측정으로 before/after 를 남깁니다.
점수 꼼수 금지 — LCP 요소를 숨기거나 콘텐츠를 지워 payload 를 줄이는 식은 하지 않습니다. 실제 사용자가 더 빨리 보는지가 기준입니다.
Lighthouse 13 대응 — 옛 audit 키(largest-contentful-paint-element)가 사라진 insight 모델에서도 LCP 요소와 절감 예상치를 읽습니다.

한 사이트에서 실제로 나온 수치

변경	결과
외부 CDN 폰트 CSS → self-host	FCP 약 10s → 1.6s, LCP 17.3s → 5.4s, Performance 70 → 75
폰트 preload 제거	Performance 100 도달
일러스트 PNG → 표시 크기 WebP	302KB → 8.5KB (97% 감소), 이미지 치수 경고 해소
앱단 gzip 미들웨어	불필요 — 앞단 nginx 가 이미 압축 중이었음

같은 페이지도 한 번 측정할 때마다 50~75 로 흔들렸습니다. 그래서 중요한 판단은 2~3회 측정 중앙값으로 합니다. SEO 가 100 에서 92 로 떨어진 적도 있는데, 원인은 봇 rate-limit 이 Lighthouse 의 robots.txt 요청을 잠깐 막은 것이었습니다. 이런 함정 8개가 스킬 문서에 정리돼 있습니다.

리포트는 이렇게 나옵니다

구매 후 전체 프롬프트 확인 가능

유료 프롬프트의 전문과 복사용 프롬프트는 구매자에게만 제공됩니다. 공개 본문에서는 구성, 활용 범위, 업데이트 내역만 확인할 수 있습니다.

구성

파일	역할
`web-performance/SKILL.md`	절차 — 수정 대상 지도, 측정, 판독, 지표별 수정, 승인 후 워크플로, 리포트 형식, 배포 주의, 실전 함정
`web-performance/references/playbook.md`	수정 코드 패턴 9절 — 압축 확인, 정적 파일 캐시, 캐시 버전 고정, LCP preload, 웹폰트 self-host, CSS 지연, 이미지 WebP, TBT, 접근성 (FastAPI·nginx 예시)
`web-performance/scripts/measure.sh`	headless Lighthouse 측정 래퍼 — 모바일/데스크탑, JSON·HTML·요약
`web-performance/agents/openai.yaml`	Codex 에서 쓸 때의 표시 정보
`web-performance/README.md`	설치, 요구 사항, 쓰는 법

설치

unzip web-performance.zip
mkdir -p ~/.claude/skills
cp -r web-performance ~/.claude/skills/
bash ~/.claude/skills/web-performance/scripts/measure.sh https://example.com/   # 측정만 먼저 해 보기

설치 뒤 Claude Code 에서 "이 페이지 라이트하우스 점수 올려줘", "LCP 고쳐줘"라고 하면 측정부터 시작합니다.

요구 사항

Claude Code (또는 Codex)
Google Chrome 또는 Chromium, Node.js(npx 로 Lighthouse 를 받아 실행). Linux·macOS 의 bash
코드 패턴 예시는 FastAPI·nginx·Jinja 기준입니다. 다른 스택은 같은 원리로 옮겨 적용합니다

이런 분께

PageSpeed 점수가 안 오르는데 무엇부터 고쳐야 할지 모르는 분
AI 에게 성능 개선을 맡겼다가 효과를 확인하지 못한 채 변경만 쌓인 분
한글 웹폰트를 쓰는 사이트에서 LCP 가 유독 느린 분