검토되지 않은 사이트 변경 없이 Claude Code로 PageSpeed SEO 감사를 실행하는 방법

Claude Code는 PageSpeed 결과를 저장소의 템플릿, 컴포넌트, 자산 파이프라인에 연결할 때 유용합니다. 하지만 증거 수집과 코드 변경은 분리해야 합니다. 이 프로젝트 로컬 스킬은 감사는 읽기 전용으로 유지하고, 사람의 명시적인 승인 후에만 작은 테스트 가능한 diff로 이동합니다.

이 글을 Claude Code에 보내 워크플로 설치하기

Read [THIS ARTICLE URL] and install its project-local PageSpeed audit workflow.

Inspect CLAUDE.md, CLAUDE.local.md, .claude rules, and project conventions first.
Explain destinations before writing. Create only:
.claude/skills/pagespeed-evidence/SKILL.md
.claude/skills/pagespeed-evidence/scripts/pagespeed_evidence.py
.claude/rules/page-speed-audits.md

Copy complete code blocks from the article. Do not change application code,
package files, lock files, CI, infrastructure, or deployment configuration.
Do not call PageSpeed Insights or inspect public URLs. Run Python syntax check,
report paths, and explain PAGESPEED_API_KEY setup without requesting its value.
Stop after installation and verification.

CLAUDE.md와.claude는 지속 프로젝트 지침이지만 보안 강제 수단은 아닙니다. 특정 도구 작업을 기술적으로 막아야 한다면 Claude Code 권한이나 PreToolUse hook을 별도로 사용합니다.

완료 계약과 저장소 경계

증거는reports/pagespeed/에만 쓰고 Git에서 반드시 무시합니다.

mkdir -p reports/pagespeed
printf 'reports/pagespeed/
' >> .gitignore
git check-ignore -v reports/pagespeed/example/report.md

.claude/rules/page-speed-audits.md 정책

# PageSpeed audit policy

- PageSpeed work starts as read-only evidence collection. Write audit output only under reports/pagespeed/, which must stay ignored by Git.
- Read PAGESPEED_API_KEY only from an approved local environment or secret mechanism. Never print it, add it to a command transcript, write it to a report, or commit it.
- Do not edit application source, content, build files, CI, infrastructure, deployment configuration, or a CMS while collecting or interpreting an audit.
- After an audit, create an implementation brief that names evidence, candidate files, risk, tests, acceptance criteria, and rollback condition. Wait for explicit approval before making a diff.
- Never deploy. After an approved implementation, show the Git diff and run only agreed local validation commands.

증거 스킬 만들기

스킬은 위 정책을 먼저 읽고 로컬 환경에서만PAGESPEED_API_KEY를 읽습니다. 공개 PageSpeed Insights와 공개 sitemap에만 GET을 보내며reports/pagespeed/에만 raw JSON, report.md, summary.json을 씁니다. mobile과desktop을 모두 측정하고 Lighthouse는 실험실 데이터로, loadingExperience와originLoadingExperience는 반환될 때만 서로 다른 CrUX 범위로 표시합니다.

python3 .claude/skills/pagespeed-evidence/scripts/pagespeed_evidence.py \
--url "https://www.example.com/" \
--out reports/pagespeed/homepage-baseline

403은 API 설정이나 키 제한을, 빈 필드 데이터는 API가 적격 CrUX를 반환하지 않았음을 뜻합니다. 보고서 산출물은git status --short에 나타나면 안 됩니다.

증거에서 검토 가능한 구현 브리프로

감사 직후의 요청도 읽기 전용입니다. 보고서 행 또는 raw 응답을 인용하고, 후보 템플릿, 컴포넌트, 자산 도구, 설정 파일과 이유를 밝히며, 가장 작은 안전한 변경, 기대 효과, 위험, 로컬 검증, 운영 수용 기준, 롤백 조건을 작성하게 합니다. 파일 편집, 포매터, 의존성 변경, 테스트 작성, 배포는 금지합니다.

코드 소유자가 한 항목을 승인한 뒤에만 지정된 경로를 변경합니다. Claude Code는 수용 및 롤백 기준을 다시 말하고git diff를 보여 주며 합의된 로컬 검증만 실행해야 합니다. 단위 테스트 통과가 Core Web Vitals 개선을 증명하지는 않으므로 같은 범위로 미리보기나 승인된 릴리스 후 재측정합니다.

검증 체크리스트

• [ ] 스킬은.claude/skills/pagespeed-evidence/SKILL.md에 있다.
• [ ] 저장소에 정책과 Git 무시reports/pagespeed/가 있다.
• [ ] API 키는 승인된 로컬 비밀 환경에만 있다.
• [ ] URL마다 모바일/데스크톱, raw JSON, 최종 URL, 실패 기록이 있다.
• [ ] Lighthouse와 페이지/오리진 CrUX가 분리되어 있다.
• [ ] Claude Code는 소스 편집 전 구현 브리프를 작성한다.
• [ ] 승인된 변경에는 작은 diff, 테스트, 수용 및 롤백 조건이 있고 배포하지 않는다.

FAQ

CLAUDE.md만으로 파일 변경을 막을 수 있나요?

아닙니다. 유용한 지속 지침이지만 강제 수단은 아닙니다. 금지해야 하는 작업에는 팀의 권한과 hook을 사용하고, 정책으로 사람과 에이전트 모두에게 작업 모델을 명확히 합니다.

Author: Julian Mercer, Auspia Technical SEO Practitioner. Julian은 SEO 발견부터 검토된 웹사이트 변경까지 명확한 증거 흐름을 남기는 기술 워크플로를 작성합니다.