HTML SEO 리뷰
개요
하나 이상의 정적 HTML 파일에 대해 실행 가능하고 심각도 순으로 정렬된 결과 목록을 생성합니다. 이 스킬은 표준 라이브러리만으로 작성된 HTML 파서(모든 SEO 관련 신호를 단일 JSON 문서로 추출), 포괄적인 평가 기준(rubric), 결과 보고서 템플릿을 함께 제공하여 매번 예측 가능한 출력으로 감사를 실행할 수 있게 합니다.
사용 시기
입력이 하나 이상의 정적 .html 파일(또는 해당 파일의 디렉토리)이고 사용자가 실행 가능한 온페이지 SEO 결과를 원할 때 사용합니다. 트리거 예시: "SEO 리뷰", "SEO 감사", "이 HTML SEO 점검", "이 페이지의 메타 태그 검토", "온페이지 SEO 감사".
다음과 같은 경우에는 사용하지 마십시오:
- 아티팩트가 정적 사이트 생성기(Jekyll/Hugo/Astro/Eleventy/Next.js)의 소스인 경우. 이러한 소스는 소스를 인식하는 리뷰가 필요합니다. 향후
ssg-seo-review스킬로 연기하세요. - 사용자가 실제 성능 메트릭(LCP, CLS, INP)을 원하는 경우. HTML만으로는 이를 생성할 수 없습니다. Lighthouse 또는 PageSpeed Insights를 권장합니다.
- 사용자가 백링크, 도메인 권위 또는 기타 오프페이지 분석을 원하는 경우. 이를 위해서는 타사 도구(Ahrefs, SEMrush 등)가 필요합니다.
워크플로우
1. 신호 추출
대상에 대해 파서를 실행합니다. 단일 파일 또는 디렉토리(재귀적으로 *.html 검색)를 허용합니다:
python3 scripts/extract_seo_signals.py <경로> --pretty
출력은 다음 최상위 키를 포함하는 JSON 문서입니다: lang, title, meta, links, scripts, headings, images, links_audit, body_word_count. 각 요소는 결과를 인용할 수 있도록 line 번호를 포함합니다.
디렉토리의 경우 출력은 {"files": [<파일별 객체>]}입니다.
스크립트는 Python 표준 라이브러리만 사용합니다 — pip install이 필요하지 않습니다. 특정 파일 구문 분석에 실패하면 해당 파일의 결과에 error 필드가 포함되고 감사는 나머지 파일에 대해 계속됩니다.
2. 신호를 평가 기준에 매핑
references/seo-checklist.md를 로드합니다. 각 섹션을 순서대로 살펴보고 해당 JSON 경로를 확인합니다. 평가 기준은 모든 검사에 대해 검사할 경로를 명시적으로 나열합니다(예: images.missing_alt, meta.description.length, scripts.render_blocking_candidates).
실패한 각 검사에 대해 다음을 기록합니다:
- 평가 기준의 심각도(P0/P1/P2/P3)
- JSON 출력의 줄 번호
- 파일의 정확히 인용된 마크업 또는 속성 값(파일을 줄 번호로 다시 읽어 문자 그대로 인용 — 절대 의역하지 마십시오)
- 수정 방법: 변경이 기계적인 경우 구체적인 before/after diff 형식으로 작성합니다.
3. 보고하기 전에 각 결과 확인
결과를 작성하기 전에 문제를 기계적으로 확인합니다:
- 속성이 "누락"되었다는 주장은 HTML을 훑어보는 것이 아니라 파서의 구조화된 출력에서 비롯되어야 합니다.
- 값이 "너무 짧음/김"이라는 주장은 JSON의 실제 문자 수를 인용해야 합니다.
- 인용된 마크업은 정확해야 합니다. 파일에서 문자 그대로 재현할 수 없는 인용은 삭제합니다.
이는 가장 흔한 리뷰 실패(실제로 존재하지 않는 문제를 만들어내는 것)를 방지합니다.
4. 결과 보고서 생성
assets/findings-template.md를 구조로 사용합니다. 다음을 채웁니다:
- 전체 평결과 심각도 개수를 포함한 요약 단락.
- 심각도(P0 → P3), 그런 다음 파일 순서로 정렬된 결과당 하나의 블록.
- 결과 수가 약 10개를 초과할 때 선택적 "퀵 윈" 섹션 — 가장 영향력이 큰 3-5개의 수정 사항을 선택합니다.
- 사용자가 외부 도구(Lighthouse: 실제 CWV, curl: 표준 URL 해석 등)로 후속 조치해야 할 사항을 나열하는 "범위 외 항목 참고" 섹션.
여러 파일을 다루는 경우, 파일별로 결과를 심각도 계층 아래에 그룹화하여 모든 파일을 다루는 하나의 보고서를 생성합니다(파일당 하나의 보고서가 아님).
5. 적절히 건너뛰기
검사에 파서가 생성할 수 없는 정보가 필요한 경우(예: "이 표준 URL이 200을 반환하는가?"), 추측하지 마십시오. 보고서의 "범위 외 항목" 섹션에 기록하고 넘어갑니다.
참고
scripts/extract_seo_signals.py— HTML 파서. 표준 라이브러리만 사용. 줄 번호와 함께 구조화된 JSON 출력.references/seo-checklist.md— 전체 평가 기준. 카테고리별로 구성되며, 심각도 계층 및 모든 검사에 대한 JSON 경로 포함.assets/findings-template.md— 감사 보고서의 출력 형식.