launch-audit
스테이징 또는 라이브 사이트를 크롤링하고 증거를 수집하여 사람이 조치할 수 있는 보고서를 제공합니다.
황금률
읽기 전용, 보고 전용. 이 스킬의 어떤 것도 사이트를 편집하거나, 폼을 제출하거나, 설정을 변경하거나, 제공자 API에 쓰거나, 파괴적인 컨트롤을 클릭하지 않습니다. 모든 발견 사항은 인간이 조치할 수 있도록 증거와 함께 제시된 권장 사항입니다.
그로부터 파생되며, 보고서를 제시할 때 다시 언급해야 할 네 가지 원칙:
- 무음 한도 없음. 모든 적용 범위 한도(최대 페이지, 깊이, 샘플링된 페이지, 확인 불가능한 외부 링크)는 미검사 항목에 이름과 함께 보고됩니다.
- 모든 발견 사항에 증거. URL, 상태 코드, 헤더 값, 스크린샷 경로.
미검사 항목은 합격이 아닙니다. 해당 섹션을 인간에게 그대로 반복합니다.- 생략은 합격이 아닙니다. 모든 생략된 검사에는 이유가 명시됩니다.
1. 입력 수집
이미 알지 못하는 것은 물어보십시오. 다음 중 어느 것도 추측하지 마십시오.
- 감사할 URL. 필수.
- 스테이징인가 라이브인가? 스테이징 대상은 noindex가 예상되므로
--staging플래그를 전달하여 사이트 전체 noindex를 블로커에서 정보 제공용으로 낮춥니다. 라이브 대상에서는 블로커입니다. - 기존 사이트를 대체하는가? 그렇다면 이전 사이트의 URL을 받아
--old-url을 전달하십시오. 이는 두 사이트 모두 여전히 접근 가능한 동안(보통 DNS가 이동하기 전) 수행되어야 합니다. 이것이 리디렉션 맵을 자동으로 구축할 수 있는 유일한 시점입니다. - 개발 또는 스테이징 호스트 이름이 빌드에 유출되었을 수 있습니다. 각각을
--dev-host로 전달하십시오. 유출된 호스트 이름은 블로커이며, 감사는 알고 있는 것만 검색할 수 있습니다. - Playwright가 설치되었는가? 설치되어 있다면 브라우저 계층이 실행됩니다: 스크린샷, axe 접근성, Lighthouse, 분석이 실제로 작동하는지 확인. 설치되지 않았다면 그렇게 말하십시오 — 보고서의 약 3분의 1이 생성되지 않으며, 보고서는 어느 3분의 1인지 명시합니다.
2. 스크립트 실행
실행하십시오. 소스를 읽거나 스크립트가 하는 일을 다시 구현하지 마십시오. 스크립트가 하는 모든 것은 읽기 전용입니다: 페이지를 가져오고, 그중 일부를 렌더링하며, 번들을 디스크에 씁니다.
node scripts/launch-audit.mjs --url <url> [--old-url <url>] [--dev-host <host>] [--staging] [--browser auto|on|off] [--out <dir>]
경로는 이 스킬 자체 디렉토리를 기준으로 합니다. 해당 디렉토리에서 명령을 실행하고, --out으로 작업이 있는 곳에 번들을 작성하십시오.
기타 플래그: --max-pages (기본값 200), --max-depth (기본값 4), --ignore-robots, --baseline <이전 baseline.json 경로>, --json, --config <경로>, --help.
브라우저 계층 기본값은 auto입니다: Playwright가 있으면 실행되고, 없으면 이유와 함께 생략됩니다. --browser on을 사용하면 없을 때 오류로 처리하고, off를 사용하면 의도적으로 생략합니다.
발견 사항이 얼마나 많든 종료 코드 0을 반환합니다 — 이는 보고를 위한 것이지 게이트가 아닙니다. 종료 코드 2는 사용법 오류를 의미합니다. Playwright 설치를 제안하는 경우 제안을 전달하십시오. 요청받지 않고 아무것도 설치하지 마십시오.
3. 번들 읽기
스크립트는 번들 경로를 출력하고 다음을 작성합니다:
report.md 차원별 발견 사항, 운영 및 접근 준비 상태, 미검사 항목 순
findings.json 동일한 발견 사항, 기계 판독 가능 형식
crawl.json 도달한 모든 URL, 상태, 깊이, 발견 방법
baseline.json 론칭 후 차이를 비교할 스냅샷
manifest.json 이 실행에서 작성된 정확한 파일 목록
redirects.csv 이전 URL당 한 행 (--old-url 있을 때만)
screenshots/ 렌더링된 페이지당 데스크톱, 태블릿, 모바일 (브라우저 계층 전용)
lighthouse/ 페이지 및 폼 팩터별 Lighthouse 점수와 측정 항목 (브라우저 계층 전용)
report.md를 먼저 읽으십시오: 블로커, 미검사 항목, 그 다음 나머지. 무엇이 확인되지 않았는지 알면 깨끗한 섹션을 읽는 방식이 달라집니다. references/reading-the-report.md에는 심각도 표와 번들을 작업하는 방법이 있습니다.
4. 세 가지 판단 통과를 직접 수행
스크립트는 어떤 검사기도 할 수 없는 세 가지 검토를 위한 증거를 수집합니다. 아무것도 제시하기 전에 세 가지를 모두 수행하십시오. 각각에는 참조 파일이 있습니다. 통과 전에 읽고, 후에는 읽지 마십시오.
스크린샷 — references/reading-the-report.md 참조. 각 렌더링된 페이지의 모바일과 데스크톱 샷을 나란히 열고 레이아웃 깨짐, 수평 오버플로, 누락된 이미지, 잘리거나 잘린 텍스트, 전화 너비에서 축소되지 않는 내비게이션, 론칭까지 살아남은 플레이스홀더 이미지를 찾으십시오. 브라우저가 실행되지 않았다면 스크린샷이 없으며, 이 검토는 수행되지 않았음을 명시하십시오 — 부재가 통과로 읽히지 않도록 하십시오.
폼 — references/forms.md 참조. 인벤토리의 모든 폼을 보고서의 증거를 사용하여 자사, 타사 또는 죽은 폼으로 분류하십시오. 그런 다음 인간에게 테스트 제출이 필요한 폼과 정확히 확인해야 할 사항(성공 메시지, 알림이 스팸 폴더가 아닌 모니터링되는 받은 편지함에 도착하는지, 레코드가 의도된 위치에 나타나는지)을 알려주십시오. 직접 폼을 제출하지 마십시오.
연락처 세부 정보 — references/content.md 참조. 보고서에서 발견된 모든 전화번호, 이메일 주소, 우편 주소를 하나의 목록으로 수집하고, tel: 링크가 옆에 표시된 번호로 연결되는지 확인하며, 사이트 소유자에게 현재 유효한 것이 무엇인지 물으십시오. 한 페이지에 남겨진 두 번째 전화번호는 전화의 절반을 아무데도 연결하지 않으며, 외부에서 어느 것이 올바른지 알 수 없습니다.
5. 보고서 제시
요약을 보고서 구조와 동일하게 구성하고, 개수보다는 결정을 우선시하십시오. 하나의 템플릿에서 나온 40개의 낮은 심각도 발견 사항은 하나의 수정입니다. 하나의 블로커는 론칭을 막습니다.
- 론칭을 막는 것. 블로커당 하나의 평범한 문장. 없으면 직접 그렇게 말하십시오.
- 차원별로 그룹화된 발견 사항, 각 차원 내에서 가장 심각한 것부터. 숫자뿐만 아니라 형태를 제시하십시오: "14개 페이지에 설명이 누락되었습니다 — 하나의 템플릿이므로 하나의 수정입니다". 실패보다는 수정 사항의 이름을 말하고, 평범한 용어로 비용이 얼마인지 말하십시오.
- 운영 및 접근 준비 상태. 이는 사이트 소유자의 작업이며, 론칭일을 망치는 것들입니다.
[human]항목을 소리 내어 읽고 각각에 대한 답변을 받으십시오. - 미검사 항목, 그대로. 모든 줄을 편집 없이, 정직하게 소개하며: "다음은 확인하지 않은 항목입니다". 절대 요약하지 말고, 사소하다고 부르지 말고, 목록이 길다고 생략하지 마십시오.
실행되지 않는 두 가지 검사
모든 보고서는 이것들로 끝납니다. 가장 아프고 어떤 크롤링도 도달할 수 없는 두 가지 실패이기 때문입니다:
- 카피 vs. 원본 문서. 여기서는 사이트의 단어를 승인된 카피와 비교하지 않습니다. 누군가가 둘 다 앉아서 읽어야 합니다.
- 페이지 vs. 합의된 범위. 여기서는 어떤 페이지가 존재해야 했는지 알지 못합니다. 만들어지지 않은 페이지는 크롤러에게 보이지 않습니다.
보고서를 제시할 때 둘 다 소리 내어 말하십시오. 사이트가 이 스킬의 모든 검사를 통과하더라도 합의된 절반이 누락될 수 있습니다.
참조
발견 사항을 설명하기 전에 차원에 대한 파일을 읽으십시오. 각 파일은 발견 사항의 의미, 론칭 시 중요한 이유, 일반적인 스택에서 수정하는 방법, 검사가 알려줄 수 없는 것을 다룹니다.
| 파일 | 내용 |
|---|---|
references/reading-the-report.md | 심각도, 스크린샷 체크리스트, 미검사 항목, 클라이언트에게 제시하기 |
references/indexability.md | 크롤링 및 인벤토리, noindex, robots.txt, 사이트맵, 표준 URL, hreflang |
references/host.md | HTTPS, 인증서, www vs apex, 리디렉션, 보안 헤더, 404 페이지 |
references/head.md | 제목, 설명, 제목, 아이콘, 소셜 카드, 구조화된 데이터 |
references/links.md | 깨지거나 확인 불가능한 링크, 링크 텍스트, mailto: 및 tel: |
references/images.md | 대체 텍스트, 크기, 로딩 전략, 무게, 형식, 비디오 |
references/forms.md | 인벤토리, 엔드포인트, 분류 및 테스트 제출 |
references/accessibility.md | HTML 기본, axe 위반 및 15분 수동 통과 |
references/performance.md | 힌트 vs 측정, Lighthouse 및 작업 정렬 |
references/analytics.md | 태그 감지, 작동, 동의 및 확인 통과 |
references/content.md | 플레이스홀더, 오래된 날짜, 연락처 세부 정보 변형 |
references/redirects.md | 전환 맵, redirects.csv 및 규칙 작성 |
references/ops.md | 이메일 인증, 법적 페이지 및 준비 상태 체크리스트 |
위치
pre-launch는 배포 전에 리포지토리에서 실행되는 게이트입니다. launch-audit는 이것입니다: 보고하고 절대 차단하지 않습니다. post-launch는 DNS가 이동하는 즉시 실행되고 프로덕션을 이 감사가 작성한 기준과 비교합니다. 이 순서로 실행하십시오.