정적 사이트 검토
목표
사용자가 최종 편집, 게시 또는 완료 처리를 하기 전에 정적 웹사이트 출력물을 검증합니다.
이 스킬은 생성된 HTML/CSS/JS 사이트를 위한 품질 관문입니다. 테마를 선택하거나, 참조 사이트를 재현하거나, 콘텐츠를 마이그레이션하거나, 사이트를 배포하지 않습니다. 생성된 폴더가 실제 정적 사이트처럼 동작하는지 확인합니다.
핵심 검사 사항:
- 소스 파일이 유효한 UTF-8이며 사람이 읽을 수 있어야 합니다.
- 로컬 링크, 스크립트, 스타일시트, 이미지 및 기타 에셋이 정상적으로 연결되어야 합니다.
- 사이트 로컬 링크와 에셋은 기본적으로
/assets/style.css와 같은 루트 절대 경로가 아닌 페이지 상대 경로를 사용해야 합니다. - 사용자가 명시적으로 서버 전용 동작을 수락하지 않은 경우, 수동 미리보기를 위해
index.html에서 직접 열 수 있어야 합니다. - 생성된 페이지가 예상 페이지 유형을 포함해야 합니다.
- 사이트가 로컬 HTTP를 통해 실제 브라우저에서 렌더링되어야 합니다.
- 데스크톱 및 모바일 레이아웃이 사용 가능해야 합니다.
- 콘솔 오류, 깨진 상호작용, 남아있는 플레이스홀더 및 복사된 소스별 텍스트가 보고되거나 수정되어야 합니다.
계약
입력:
site/,dist/,out/,public/,docs/또는 저장소 루트와 같은 정적 사이트 루트입니다.- 선택적 예상 페이지 범위, 로컬 미리보기 URL,
EDITING.md, 참조 URL/스크린샷 및 금지된 소스별 문자열입니다.
출력:
- 심각도별로 정렬된 발견 사항, 또는 검증이 빌드/수정 작업의 일부인 경우 수정 사항입니다.
- 정적 감사 결과, 확인된 브라우저 페이지/뷰포트 및 변경된 파일(있는 경우)입니다.
- 게시 또는 전달 준비 상태에 대한 명확한 통과/실패 상태입니다.
경계:
- 테마를 선택하거나, 웹사이트를 재생성하거나, 콘텐츠를 마이그레이션하거나, 정체성을 개인화하거나, 배포하지 않습니다.
- 시각적 문제가 사용성을 차단하고 사용자가 수정을 요청하지 않는 한, 검증 중에 사이트를 재설계하지 않습니다.
--allow-root-absolute가 의도적으로 사용되고 그 제한 사항이 명시되지 않는 한, 루트 절대 사이트 로컬 경로를 승인하지 않습니다.
성공 조건:
- 차단 요소가 없어야 합니다: 깨진 기본 탐색, 누락된 필수 페이지 유형, 읽을 수 없는 소스 인코딩, 로컬 에셋 실패, 콘솔 충돌, 모바일 사용 불가 또는 우발적인 루트 절대 경로 문제.
- 경고는 수정, 문서화 또는 사용자 동의를 받아야 합니다.
조건 실패 시:
- 검증이 빌드의 일부인 경우 간단한 로컬 문제를 수정합니다.
- 더 큰 실패는 실패한 부분에 따라
make-personal-site,copy-website-style,personalize-site,add-blog-posts또는edit-site-part로 라우팅합니다. - 결정적 감사 및 영향을 받는 브라우저 검사를 다시 실행합니다.
함께 사용하기
다음 이후에 이 스킬을 사용하세요:
make-personal-site가 원본 정적 개인 사이트를 생성하거나 재설계한 경우.copy-website-style이 대상 사이트의 스타일을 정적 파일로 재현한 경우.- 사용자가 기존 정적 출력 폴더를 가리키며 충분한지 묻는 경우.
- 사용자가 게시 전에 정적 사이트를 확인, 검증, QA, 검사, 감사 또는 테스트를 요청하는 경우.
사용자가 프레임워크 소스 프로젝트를 제공하는 경우, 가능하면 이미 빌드된 정적 출력 폴더를 검증하세요. 사용자가 명시적으로 요청하지 않는 한 여기에 프레임워크 빌드 워크플로우를 도입하지 마십시오.
입력
사용 가능한 모든 입력을 사용하세요:
site/,dist/,out/또는public/과 같은 정적 사이트 루트 폴더입니다.- 서버가 이미 실행 중인 경우 로컬 미리보기 URL.
- 예상 페이지 범위: 홈페이지만, 전체 개인 사이트, 블로그, 포트폴리오, 노트, 링크, 스타일 재현 등.
- 다른 스킬에서 생성된
EDITING.md, 페이지 맵 또는 전달 노트. - 스타일 재현을 검증할 때 참조 URL 또는 스크린샷.
- 원본 작성자 이름, 도메인, 이메일, 분석 ID 또는 오래된 플레이스홀더 텍스트와 같이 남아 있어서는 안 되는 알려진 문자열.
사이트 루트가 불분명한 경우, 주변 폴더를 검사하고 index.html과 정적 에셋이 포함된 폴더를 선택하세요.
워크플로우
- 정적 사이트 루트와 예상 페이지 범위를 식별합니다.
EDITING.md를 읽거나 HTML 파일 및 탐색 링크에서 페이지 맵을 추론합니다.- 결정적 파일 감사 스크립트를 실행합니다.
- 정적 루트에 대한 로컬 HTTP 서버를 시작하거나 재사용합니다.
- 실제 브라우저에서 데스크톱 및 모바일 너비로 사이트를 검증합니다.
- 생성된 모든 페이지 유형에 대해 최소한 하나의 대표 페이지를 엽니다.
- 탐색, 테마 전환, 검색/필터, 복사 버튼, 모바일 메뉴 및 페이지 매김과 같은 핵심 상호작용을 테스트합니다.
- 브라우저 콘솔 오류 및 누락된 네트워크 자원을 확인합니다.
- 상대 경로 호환성, 플레이스홀더, UTF-8 가독성 및 소스별 잔여 텍스트를 감사합니다.
- 사용자가 빌드의 일부로 검증을 요청한 경우 간단한 결함을 수정하고, 그렇지 않으면 먼저 발견 사항을 보고합니다.
결정적 파일 감사
브라우저 검증 전에 번들 스크립트를 사용하세요:
python scripts/static_site_check.py <site-root>
스타일 재현 또는 복사된 사이트 정리를 위해 금지된 소스별 문자열을 전달하세요:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
스크립트는 다음을 확인합니다:
- HTML, CSS, JS, JSON, Markdown, SVG, XML 및 텍스트 파일에 대한 UTF-8 디코딩.
- 의심스러운 모지바케 및 대체 문자.
- HTML 파일에서 누락된
<meta charset="utf-8">. - 깨진 로컬
href,src,srcset,poster,action및data-src참조. - 명시적으로 허용되지 않는 한
/assets/...,/posts/...,/data/...또는/images/...와 같은 루트 절대 사이트 로컬 참조. - CSS
url(...)에셋 참조, 누락되거나 루트 절대 로컬 URL 포함. - HTML, JavaScript 및 JSON 데이터 내부의 일반적인 루트 절대 사이트 로컬 문자열.
- 사이트 루트를 벗어나는 링크.
- 일반적인 플레이스홀더 문자열.
--forbid로 제공된 금지된 문자열..env, 개인 키, 자격 증명 파일, 로컬 서비스 계정 아티팩트와 같은 개인정보에 민감한 배포 루트 파일.- 비밀 같은 할당, 알려진 토큰 패턴, 개인 키 블록 및 소스 텍스트의 로컬 절대 파일 시스템 경로.
- 게시되어서는 안 되는 임시, 로그, 백업 및 OS 아티팩트.
- HTML 페이지 수 및 추론된 페이지 유형.
EDITING.md존재 여부.
파일 감사는 벤더 파일의 UTF-8 가독성도 확인해야 하지만, 타사 축소 벤더 번들 내부의 플레이스홀더 같은 단어를 사이트 플레이스홀더 콘텐츠로 취급해서는 안 됩니다.
사용자가 빠른 탐색 검토만 원하지 않는 한 스크립트 오류를 차단 요소로 처리하세요. 경고는 수동으로 검사할 항목으로 처리하세요.
사이트가 의도적으로 사용자 정의 도메인 루트 아래에서 루트 상대 경로를 필요로 하도록 설계된 경우, --allow-root-absolute로 스크립트를 실행하고 직접 file:// 열기 및 GitHub 프로젝트 하위 경로 배포가 보장되지 않는다고 명시하세요. 사용자가 명시적으로 그 트레이드오프를 수락하지 않는 한 생성된 일반 정적 개인 사이트에 대해 이 예외를 사용하지 마십시오.
경로 호환성
생성된 일반 정적 사이트는 세 가지 일반적인 컨텍스트에서 작동해야 합니다:
- 빠른 수동 미리보기를 위해 파일 시스템에서
index.html을 직접 열기. - 브라우저 자동화 및 콘솔/네트워크 검사를 위해 폴더를 로컬 HTTP로 제공.
- 도메인 루트 또는 하위 경로에서 사이트를 제공할 수 있는 정적 호스트에 배포.
기본 규칙:
- 사이트 로컬 링크 및 에셋에 페이지 상대 경로를 사용하세요.
- 루트 페이지에서
assets/style.css,posts/example.html및about.html을 사용하세요. - 중첩된 페이지에서
../assets/style.css,../blog.html및 필요에 따라 형제 상대 링크를 사용하세요. - 기본적으로
/assets/style.css,/posts/example.html,/data/posts.json,/images/foo.png또는 내부 탐색에/를 사용하지 마십시오.
또한 JavaScript 생성 링크, 검색 결과, 태그 필터, 복사 버튼, 동적 카드, RSS/사이트맵 참조, 이미지 커버, CSS url(...) 값, 파비콘, 글꼴 및 KaTeX/수학 벤더 에셋을 확인하세요. 정적 HTML 속성이 상대적이더라도 JavaScript가 나중에 루트 절대 경로를 삽입하는 것으로는 충분하지 않습니다.
루트 절대 경로는 사용자가 명시적으로 서버 루트 전용 배포(예: 사용자 정의 도메인 루트)를 원하고 직접 파일 열기 및 GitHub 프로젝트 Pages 하위 경로가 깨질 수 있음을 이해하는 경우에만 허용됩니다.
브라우저 검증
최종 전달 전에 실제 브라우저를 사용하세요. file://이 아닌 HTTP를 통해 로컬 파일을 제공하세요:
python -m http.server 8000
그런 다음 엽니다:
http://127.0.0.1:8000/
로컬 HTTP 대상을 위한 첫 번째 선택 검증 경로로 실제 사용 가능한 대화형 브라우저 도구를 사용하세요. "사용 가능"은 도구가 스킬, 플러그인 목록 또는 시스템 설명에 언급된 것뿐만 아니라 현재 턴의 호출 가능한 도구 목록에 노출되어 있음을 의미합니다. Codex에서 이는 사용자 또는 클라이언트가 해당 턴으로 라우팅한 경우 Browser/인앱 브라우저 플러그인일 수 있습니다. 다른 에이전트에서는 동등한 가시적 브라우저, browser-use 도구 또는 devtools 기반 브라우저일 수 있습니다. 로컬 URL을 열고, 데스크톱/모바일 뷰포트를 검사하고, 상호작용을 실행하고, 표시되는 콘솔/네트워크 문제를 확인해야 합니다.
현재 턴에 대화형 브라우저 도구가 노출되지 않은 경우, 브라우저 패스가 발생한 것처럼 가장하지 마십시오. 검증이 이에 의존하는 경우, 사용자에게 클라이언트의 라우팅 방법을 사용하여 브라우저 도구를 활성화하거나 호출하도록 요청하세요. Codex의 경우 @browser를 명시적으로 언급하는 요청을 보내는 것을 의미할 수 있습니다. 사용자가 다시 라우팅하지 않거나 클라이언트에 해당 도구가 없는 경우, Playwright, 스크린샷, 정적 감사 또는 셸 검사로 대체하고 이것이 전체 대화형 브라우저 검증이 아닌 대체 방법임을 명시하세요.
대화형 브라우저 도구가 실제로 호출 가능한 경우 Playwright, 헤드리스 전용 스크린샷 스크립트, 셸에서 연 브라우저 창 또는 정적 스크린샷 생성으로 기본 설정하지 마십시오. 스크린샷은 유용한 증거이지만 대화형 브라우저 패스를 대체하지 않습니다. 대화형 브라우저 도구를 호출할 수 없을 때, 사용자가 명시적으로 Playwright를 요청할 때 또는 반복 가능한 스크립팅된 회귀 테스트가 특별히 필요할 때만 Playwright를 대체 방법으로 사용하세요.
작업에 사용자의 Chrome 프로필, 기존 탭, 확장 프로그램, 인증된 원격 페이지 또는 Chrome 특정 동작이 필요한 경우에만 Chrome 자동화를 사용하세요. file:// 페이지에 Chrome 확장 프로그램 자동화에 의존하지 마십시오. 대신 로컬 HTTP를 사용하세요.
자동화는 로컬 HTTP를 사용해야 하지만, 생성된 소스는 상대 경로를 사용하고 핵심 콘텐츠에 대해 서버 전용 가정을 피함으로써 직접 열기 호환성을 유지해야 합니다. 앱/브라우저가 빠른 file:// 스모크 검사를 허용하는 경우, 루트 index.html을 직접 열고 CSS, 이미지, 탐색 및 대표적인 하위 페이지가 깨지지 않았는지 확인하세요. 파일 자동화를 사용할 수 없는 경우, 결정적 루트 절대 경로 감사에 의존하고 직접 열기가 수동 또는 자동으로 확인되었는지 언급하세요.
브라우저 검사:
- 데스크톱 첫 화면: 구성, 간격, 타이포그래피, 표시되는 탐색 및 명백한 오버플로.
- 모바일 첫 화면: 탐색 동작, 텍스트 줄 바꿈, 콘텐츠 우선 순위 및 가로 오버플로.
- 내부 탐색: 모든 기본 탐색 링크가 렌더링됩니다.
- 페이지 유형 범위: 생성된 모든 페이지 유형에 대해 최소한 하나의 브라우저 패스 또는 스크린샷.
- 상호작용 범위: 테마 전환, 메뉴, 필터, 검색, 복사 버튼, 페이지 매김, 아코디언, 탭, 호버/클릭 상태 또는 기타 표시되는 컨트롤.
- 콘솔 상태: 명백한 JavaScript 오류가 없습니다.
- 네트워크 상태: 누락된 로컬 CSS, JS, 이미지 또는 글꼴 에셋이 없습니다.
- 접근성 기본 사항: 대화형 컨트롤의 포커스 가시성, 읽을 수 있는 대비, 의미 있는 페이지 제목 및 가능한 경우 비어 있지 않은 이미지 대체 텍스트.
작은 사이트의 경우 모든 생성된 페이지를 클릭하세요. 큰 사이트의 경우 모든 페이지 유형과 EDITING.md에서 언급된 모든 경로를 샘플링하세요.
페이지 유형 범위
파일 이름, 경로, 표시되는 탐색 및 EDITING.md에서 페이지 유형을 추론하세요.
일반적인 페이지 유형:
- 홈.
- 소개 또는 프로필.
- 블로그, 아카이브, 카테고리, 태그, 노트 또는 목록 페이지.
- 기사 또는 상세 페이지.
- 프로젝트, 포트폴리오, 출판물 또는 작업 페이지.
- 링크, 친구, 리소스, now, uses, 가든, 검색, 테마/설정 또는 기타 특수 페이지.
생성된 사이트가 블로그라고 주장하지만 기사/상세 페이지가 없는 경우 보고하세요. 존재하지 않는 하위 페이지로의 탐색이 있는 경우 차단 요소로 보고하세요.
인코딩 및 소스 가독성
브라우저 스크린샷만으로는 충분하지 않습니다. 소스 파일은 미래의 모델과 사람이 읽을 수 있어야 합니다.
요구 사항:
- HTML 파일에
<meta charset="utf-8">이 포함되어야 합니다. - 비ASCII 텍스트는 UTF-8로 저장되어야 합니다.
- HTML, CSS 주석, JavaScript 문자열, JSON/데이터 파일, SVG 텍스트 및
EDITING.md는 소스 형태로 읽을 수 있어야 합니다. - 모지바케, 대체 문자 또는 우발적인 브라우저 인코딩 복구가 없어야 합니다.
터미널에 모지바케가 표시되지만 브라우저가 올바르게 보이는 경우, 깨졌다고 판단하기 전에 UTF-8 인식 읽기로 확인하세요. 파일 콘텐츠 자체에 모지바케가 포함된 경우, 다른 인코딩 변환을 추가하는 대신 깨끗한 텍스트에서 영향을 받은 문자열을 다시 작성하세요.
플레이스홀더 및 잔여물 감사
생성된 사이트에 다음이 여전히 포함되어 있는지 확인하세요:
TODO,FIXME,lorem ipsum,placeholder,replace me,your name,example.com또는 샘플/데모 텍스트.- 더미 이메일, 가짜 소셜 링크, 빈 버튼 또는 죽은 CTA(행동 촉구).
- 스타일 재현에서 원본 사이트 작성자 이름, 도메인, 기사 제목, 이메일, 분석 ID, 소셜 링크, 친구 링크 또는 개인 URL.
사용자가 여전히 의도적인 편집 가능한 표시자로 필요로 하는 경우 플레이스홀더를 무조건 제거하지 마십시오. 명확하게 보고하거나 사용자가 실제 콘텐츠를 제공한 경우에만 교체하세요.
개인정보 및 로컬 잔여물
게시 전에 다음을 차단 요소로 처리하세요:
- 배포 가능한 루트 내부의
.env,.npmrc,.pypirc, 개인 키 파일, 자격 증명 JSON 파일, 서비스 계정 파일 또는 비밀번호 볼트/내보내기 파일. - HTML, CSS, JavaScript, JSON, Markdown, SVG 또는 텍스트 파일의 비밀 같은 할당, 액세스 토큰, 개인 키 블록 또는 API 키.
- 생성된 소스의 Windows 드라이브 경로,
file:///...,/Users/...,/home/...또는/mnt/...와 같은 로컬 절대 파일 시스템 경로.
로그, 백업, 임시 파일 및 OS 메타데이터는 개인 콘텐츠를 노출하지 않는 한 경고로 처리하세요. 패키징 또는 게시 전에 배포 가능한 출력물에서 제거하세요.
수정 정책
사용자가 "확인", "검토" 또는 "무엇이 잘못되었는지 알려줘"를 요청하는 경우, 먼저 발견 사항을 보고하고 광범위한 편집을 피하세요.
검증이 빌드의 일부인 경우(예: make-personal-site 완료 후 자동으로 호출되는 경우) 간단한 문제를 자동으로 수정하세요.
자동 수정:
- 인코딩 문제: 깨진 파일을 올바른 UTF-8로 다시 작성합니다.
- 누락된
<meta charset="utf-8">: HTML<head>에 추가합니다. - 플레이스홀더 텍스트: 사용자가 실제 콘텐츠를 이미 제공한 경우에만 교체합니다.
- 루트 절대 경로(수정 가능한 경우): 페이지 상대 경로로 변환합니다.
- 민감한 파일:
.env또는 개인 키 파일을 제거합니다(사용자 확인 후).
다음을 위해 사용자에게 라우팅하거나 요청:
- 디자인 선택 또는 테마 불일치.
- 실제 콘텐츠가 필요한 플레이스홀더.
- 복잡한 탐색 재구성.
- 배포 구성.
음수 테스트
다음은 이 스킬의 목적이 아닙니다:
- 새 사이트 생성 또는 테마 선택.
- 기존 사이트 마이그레이션.
- 사이트 배포.
- 사이트 콘텐츠 개인화.
- 참조 사이트의 모든 스타일과 콘텐츠를 완벽하게 재현(스타일 재현에
copy-website-style사용). - JavaScript 빌드 도구 설정.
- 긴 형식의 SEO 또는 접근성 감사 보고서 생성.
- 새 정적 사이트 생성기 프로젝트 초기화.
사용자가 이러한 작업을 요청하는 경우, 적절한 스킬로 리디렉션하거나 사용 가능한 도구를 사용하여 작업을 완료할 수 없는 경우 명확하게 명시하세요.