02. W3C Validator+Lighthouse 한글보고서.skills

HTML, CSS 문법검사 + 구글 LightHouse 평가 결과를 한글로 보고하는 스킬입니다.

1. LightHouse API키 발급

Lighthouse란?

구글이 개발한 오픈소스 웹 품질 측정 도구

1. 공식문서
2. API 키 발급받기

2. 스킬다운로드

web-check-ko는 웹페이지 하나를 네 가지 도구로 검사해 한국어 보고서를 만드는 스킬입니다.

네 가지 도구가 보는 곳이 서로 다릅니다.

2 – 공개 웹페이지 검사하기

공개 웹페이지는 인터넷 주소만 알면 누구나 열 수 있는 페이지입니다. 로그인해야 보이는 페이지는 검사기가 열지 못하므로 이 스킬로 검사할 수 없습니다.

검사를 시키는 방법은 두 가지입니다. 대화로 부르는 방법이 간단하고, 명령으로 직접 실행하는 방법은 옵션을 세밀하게 고를 수 있습니다.

2.1 – 대화로 검사 요청하기

Claude Code에 주소를 알려 주면 스킬이 스스로 실행됩니다. 명령을 외울 필요가 없어 가장 자주 쓰는 방법입니다.

1. Claude Code 입력창을 클릭합니다.
2. 아래 문장을 입력합니다. 주소 자리에는 검사할 실제 주소를 넣고 API키는 위에서 발급받은 키를 넣습니다.

https://example.com 검사해줘 [API키]

3. Enter 키를 누릅니다.

검사가 시작되고, 약 1~3분 뒤에 한국어 보고서가 나옵니다. 네 가지 검사가 각각 다른 서버에 요청을 보내기 때문에 시간이 걸립니다.

아래 표현으로도 같은 스킬이 실행됩니다. 외우지 않아도 되며, 검사하고 싶은 내용을 그대로 적으면 됩니다.

주소 하나만 입력해도 스킬이 실행됩니다. 무엇을 검사할지 정하지 않았다면 주소만 붙여 넣어도 네 가지 검사가 모두 돌아갑니다.

2.2 – 명령으로 직접 검사하기

검사 파일을 직접 실행하면 결과를 가공되지 않은 상태로 볼 수 있습니다. 옵션을 붙여 검사 범위를 바꿀 때도 이 방법을 씁니다.

1. Win+R을 누르고 powershell을 입력한 다음 Enter 키를 누릅니다.
2. 스킬 폴더로 이동하는 아래 명령을 입력하고 Enter 키를 누릅니다.

cd C:\Users\PC\.claude\skills\web-check-ko

3. 검사 명령을 입력하고 Enter 키를 누릅니다.

node scripts/check.mjs https://example.com/

화면에 중괄호로 시작하는 긴 글자가 쏟아집니다. 이것이 JSON이며, 프로그램끼리 값을 주고받을 때 쓰는 글자 형식입니다.

JSON은 사람이 읽으라고 만든 형식이 아닙니다. 그래서 이 결과를 그대로 읽지 않고, 다음 단계에서 파일로 저장한 뒤 Claude Code에 한국어 보고서를 만들어 달라고 요청합니다.

검사 결과는 화면의 표준 출력으로, 오류 메시지는 표준 오류로 따로 나갑니다. 그래서 출력을 파일에 담아도 JSON이 깨지지 않습니다.

2.3 – 결과를 파일로 저장해 열어 보기

--out 옵션은 검사 결과 JSON을 지정한 경로에 파일로 저장하는 옵션입니다.
화면에 흘러간 결과를 다시 보려면 파일로 남겨야 합니다.

1. PowerShell 창에 아래 명령을 입력합니다.

node scripts/check.mjs https://example.com/ --out "$HOME\Documents\웹검사결과\example.json"

2. Enter 키를 누릅니다.
3. 검사가 끝나면 Win+E를 눌러 파일 탐색기를 엽니다.
4. 문서 → 웹검사결과 폴더를 차례로 클릭합니다.

"example.json" 파일이 만들어졌습니다. 앞서 만든 폴더에 결과가 쌓이므로 여러 번 검사해도 서로 섞이지 않습니다.

이 파일을 Claude Code에 넘기면 한국어 보고서를 받을 수 있습니다.

1. Claude Code 입력창을 클릭합니다.
2. 아래 문장을 입력하고 Enter 키를 누릅니다.

C:\Users\PC\Documents\웹검사결과\example.json 이 결과로 한국어 보고서 만들어줘

영어로 된 오류 메시지가 한국어 설명으로 바뀌고, 줄 번호와 고치는 방법이 함께 적힌 보고서가 나옵니다.

3 – 상황에 맞게 옵션 바꾸기

옵션은 명령 뒤에 붙여 검사 방식을 바꾸는 값입니다. 붙이지 않으면 기본값으로 검사합니다.

이 스킬이 쓰는 옵션은 여덟 가지입니다.

3.1 – 데스크톱 기준으로 다시 재기

--strategy 옵션은 Lighthouse가 어떤 기기를 흉내 내어 점수를 잴지 정하는 옵션입니다. 값은 mobile과 desktop 두 가지입니다.

이 옵션을 붙이지 않으면 mobile 기준으로 잽니다. 휴대전화는 컴퓨터보다 처리 속도가 느려서 같은 페이지라도 점수가 더 낮게 나옵니다.

1. PowerShell 창에 아래 명령을 입력합니다.

node scripts/check.mjs https://example.com/ --strategy desktop

2. Enter 키를 누릅니다.

컴퓨터 화면 기준으로 다시 잰 점수가 나옵니다. 같은 페이지를 두 기준으로 재면 점수가 20점 넘게 벌어지기도 합니다.

점수를 남길 때는 어느 기준으로 쟀는지 함께 적습니다. 기준을 밝히지 않은 점수는 다른 사람이 다시 재도 같은 값이 나오지 않아 비교할 수 없습니다.

3.2 – 오래 걸리는 검사 건너뛰기

--skip 옵션은 네 가지 검사 가운데 특정 검사를 실행하지 않는 옵션입니다. 넣을 수 있는 값은 html, css, js, lighthouse 네 가지입니다.

Lighthouse는 실제로 페이지를 열어 재기 때문에 가장 오래 걸립니다. 문법만 빠르게 확인하려면 이 검사를 건너뜁니다.

1. PowerShell 창에 아래 명령을 입력합니다.

node scripts/check.mjs https://example.com/ --skip lighthouse

2. Enter 키를 누릅니다.

문법 검사만 실행되어 결과가 훨씬 빨리 나옵니다. 코드를 고치고 다시 확인할 때처럼 여러 번 반복해 검사하는 상황에 알맞습니다.

두 가지 이상을 건너뛰려면 옵션을 여러 번 적습니다.

node scripts/check.mjs https://example.com/ --skip lighthouse --skip css

3.3 – PageSpeed Insights 키 발급받아 쓰기

PageSpeed Insights API 키는 구글 검사 서버에 요청을 보낼 때 신원을 밝히는 문자열입니다. 키가 없어도 검사할 수 있지만, 여러 사람이 함께 쓰는 공용 사용량을 나눠 쓰게 됩니다.

공용 사용량이 다 떨어지면 HTTP 429라는 오류가 나옵니다. 이때 키를 발급받아 쓰면 본인 몫의 사용량으로 검사합니다.

1. 브라우저 주소창을 클릭합니다.
2. 아래 주소를 입력하고 Enter 키를 누릅니다.

https://developers.google.com/speed/docs/insights/v5/get-started

3. 페이지에서 [Get a Key](키 받기) 버튼을 클릭합니다.
4. 구글 계정으로 로그인합니다.
5. 화면에 나온 키 문자열을 마우스로 드래그해 선택합니다.
6. Ctrl+C를 눌러 복사합니다. 키는 영문자와 숫자가 섞인 39자 안팎의 문자열입니다. 이 키를 --psi-key 옵션 뒤에 붙여 검사합니다.

node scripts/check.mjs https://example.com/ --psi-key 여기에복사한키를붙여넣습니다

키는 다른 사람에게 보이지 않게 관리합니다. 키가 든 명령을 그대로 인터넷 게시판이나 채팅방에 올리면 다른 사람이 본인 사용량을 대신 쓰게 됩니다.

4 – 내 컴퓨터의 파일 검사하기

아직 인터넷에 올리지 않은 파일도 문법 검사를 받을 수 있습니다. 만드는 중인 페이지를 올리기 전에 미리 확인할 때 씁니다.

로컬 파일 검사에서는 Lighthouse가 실행되지 않습니다. Lighthouse는 인터넷 주소를 열어 재는 도구여서, 내 컴퓨터 안에만 있는 파일은 열 수 없습니다.

4.1 – 연습용 파일 만들기

검사가 오류를 어떻게 잡아내는지 보려면 일부러 틀린 파일을 하나 만들어 보는 편이 빠릅니다.

1. Win+E를 눌러 파일 탐색기를 엽니다.
2. 문서 → 웹검사결과 폴더를 차례로 클릭합니다.
3. 빈 곳에서 마우스 오른쪽 버튼을 클릭합니다.
4. [새로 만들기] → [텍스트 문서]를 클릭합니다.
5. 파일 이름 자리에 연습.html을 입력하고 Enter 키를 누릅니다.
6. 확장자를 바꾸겠냐고 물으면 [예] 버튼을 클릭합니다.
7. 만들어진 "연습.html" 파일을 더블클릭해 메모장으로 엽니다.
8. 아래 내용을 입력합니다.

<!DOCTYPE html> <html lang="ko"> <head> <title>연습 페이지</title> </head> <body> <p id="hello">첫 번째 문단 <p id="hello">두 번째 문단</p> <img src="cat.png"> </body> </html>

9. Ctrl+S를 눌러 저장합니다.

이 파일에는 오류가 일부러 세 군데 들어 있습니다. 첫 번째 <p> 태그를 닫지 않았고, id 값 hello가 두 번 쓰였으며, <img> 태그에 alt 속성이 없습니다.

id는 페이지 안에서 한 요소만 가리키는 이름이라 같은 값을 두 번 쓸 수 없습니다. alt는 이미지가 뜨지 않거나 화면을 읽어 주는 프로그램을 쓸 때 대신 읽히는 글이라 반드시 적어야 합니다.

메모장이 파일을 저장할 때 인코딩을 UTF-8로 잡는지 확인합니다. 저장 창 아래쪽 [인코딩] 목록에서 고를 수 있으며, 다른 값으로 저장하면 한글이 깨져 검사기가 다른 오류를 함께 보고합니다.

4.2 – 로컬 파일 검사 실행하기

--html-file 옵션은 내 컴퓨터에 있는 HTML 파일을 검사 대상으로 지정하는 옵션입니다. 인터넷 주소 대신 파일 경로를 넘깁니다.

1. PowerShell 창을 클릭합니다.
2. 아래 명령을 입력하고 Enter 키를 누릅니다.

node scripts/check.mjs --html-file "$HOME\Documents\웹검사결과\연습.html"

결과 JSON 안의 error_count 항목에 오류 개수가, errors 항목에 오류마다 줄 번호와 메시지가 담깁니다. 앞서 일부러 넣은 세 가지가 여기에 잡힙니다.

CSS 파일과 자바스크립트 파일도 함께 검사하려면 옵션을 나란히 붙입니다.node scripts/check.mjs --html-file index.html --css-file style.css --js-file app.js

node scripts/check.mjs --js-file app.js utils.js

자바스크립트 파일은 한 번에 여러 개를 넘길 수 있습니다. 파일 경로를 띄어쓰기로 이어 적습니다.

파일 경로를 직접 입력하지 않아도 됩니다. 파일 탐색기에서 파일을 마우스로 잡고 PowerShell 창 안으로 끌어다 놓으면 전체 경로가 자동으로 입력됩니다.

5 – 보고서 읽고 다음 할 일 정하기

보고서는 검사 결과를 한국어로 옮기고 고치는 방법까지 적은 문서입니다. 검사가 끝나면 Claude Code가 이 형식으로 정리해 줍니다.

보고서에는 일곱 부분이 들어갑니다. 맨 위 [한눈에 보기] 표에 검사별 결과가 모여 있어서, 이 표부터 보면 어디를 손봐야 하는지 알 수 있습니다.

5.1 – 보고서에서 먼저 볼 곳

Lighthouse 점수는 0점에서 100점 사이로 나옵니다. 점수마다 판정 기준이 정해져 있습니다.

문법 검사 결과는 오류와 경고를 나눠서 봅니다. 두 가지의 무게가 다릅니다.

오류는 규칙을 어긴 것이라 반드시 고칩니다. 경고는 고치면 좋다는 권고라 뒤로 미뤄도 됩니다.

보고서를 다 읽었으면 맨 아래 [먼저 할 일] 항목부터 손댑니다. 여기에 효과가 큰 순서로 세 가지가 적혀 있습니다.

Lighthouse 점수는 잴 때마다 몇 점씩 달라집니다. 인터넷 상태와 검사 서버 상황이 매번 다르기 때문입니다. 한 번 잰 값으로 판단하지 말고 2~3회 재어 비슷하게 나오는 값을 씁니다.

접근성 점수가 100점이어도 접근성 문제가 없다는 뜻은 아닙니다. Lighthouse는 프로그램으로 자동 판정할 수 있는 항목만 검사합니다.

아래 세 가지는 자동으로 확인되지 않으므로 직접 해 봅니다.

1. Tab 키만으로 화면 전체를 쓸 수 있는지 눌러 봅니다.
2. Tab 키를 계속 눌렀을 때 한 곳에 갇히지 않는지 봅니다.
3. 눈에 보이는 순서와 Tab 키가 옮겨 다니는 순서가 맞는지 봅니다.

5.2 – 검사가 실패했을 때 대처하기

네 가지 검사는 서로 독립되어 있습니다. 하나가 막혀도 나머지 세 가지는 그대로 결과가 나옵니다.

실패한 항목은 결과에서 ok 값이 false로 나오고, reason 항목에 실패한 까닭이 적힙니다. 자주 나오는 실패는 아래와 같습니다.

HTTP 429가 나왔을 때 컴퓨터에 lighthouse 명령이 설치되어 있으면 그쪽으로 한 번 더 시도합니다. 그것도 실패하면 결과에 두 가지 실패 까닭이 모두 담깁니다.

CSS 오류가 0건인데 화면이 깨져 보일 때가 있습니다. 문법은 맞지만 값이 의도와 다른 경우이며, 문법 검사로는 잡히지 않습니다.

이때는 브라우저에서 F12 키를 눌러 개발자 도구를 열고 해당 요소를 클릭해 실제 적용된 값을 확인합니다.

이 스킬은 사이트를 고치지 않습니다. 무엇을 어떻게 고칠지 알려 줄 뿐이며 파일을 직접 바꾸지 않습니다. 고치는 작업은 보고서를 읽고 직접 하거나, 보고서를 근거로 따로 요청합니다.