Before and after
하나의 PNG를 생성합니다: 시각적 변경 사항마다 한 행씩, 각 행에는 변경 이름, 한 줄 메모, 기준 브랜치 스크린샷, 현재 브랜치 스크린샷이 포함된 테이블입니다. 코드를 보지 않은 사람도 이미지만 보고 무엇이 어떻게 달라졌는지 알 수 있어야 합니다.
이미지는 변경 목록의 정확성에 따라 품질이 결정됩니다. 다섯 개 중 세 개만 보여주거나, 코드 때문이 아닌 다른 데이터로 인한 차이를 보여주는 테이블은 독자를 오도합니다. 대부분의 작업은 모든 시각적 변경을 찾고 코드만 달라지도록 각 쌍을 캡처하는 데 있습니다.
이미지 저장 위치. 이 스킬이 생성하는 모든 것은 사용자의 Documents 폴더 ~/Documents/before-after/<repository>/<branch>/에 저장됩니다: 스크린샷, 매니페스트, shots.mjs 복사본, 최종 before-after.png 파일. 스크립트는 스스로 이 폴더를 선택하며 출력 경로를 인자로 받지 않습니다. ~/Documents/before-after 외의 다른 루트를 원하는 사용자는 BEFORE_AFTER_DIR 환경 변수를 설정할 수 있으며, 이는 사용자가 설정하는 변수이지 에이전트가 설정하는 것이 아닙니다. 이미지를 다른 곳에 쓰거나 이후에 이동/복사하지 마십시오; 스크래치패드는 기준 worktree와 shots.mjs 초안 작성을 위해서만 사용합니다. 동일한 브랜치에 대해 나중에 다시 실행하면 폴더를 재사용합니다.
이 파일 옆 scripts/ 디렉토리에는 두 개의 스크립트가 있습니다: capture.mjs는 스크린샷을 촬영하고, compose.mjs는 테이블을 구성하고 검사합니다. 각 스크립트는 헤더에 입력 형식을 문서화하고 있습니다. 시작하기 전에 두 헤더를 모두 읽으십시오.
로컬 노트. 이 파일 옆에 LOCAL.md 파일이 있다면 시작하기 전에 읽으십시오. 여기에는 사용자가 작업 중인 프로젝트에 대한 기본값(명령어, 호스트, 계정, 경로)이 저장되어 있으며 공개된 스킬의 일부가 아닙니다. 해당 프로젝트에 관한 내용이라면 프로젝트 지침의 일부로 간주합니다; 해당되지 않으면 무시하십시오.
1. 변경 사항 수집
기준 브랜치가 주어지지 않은 경우, 풀 리퀘스트의 기준 브랜치(gh pr view --json baseRefName --jq .baseRefName)를 사용하고, 그다음 기본 브랜치(git symbolic-ref --short refs/remotes/origin/HEAD), 그다음 origin/main을 사용합니다. 원격 추적 ref를 선호합니다. 커밋되지 않은 작업도 포함합니다:
base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short # 추적되지 않은 파일도 읽음
git log --oneline "$base"..HEAD
풀 리퀘스트 설명과 이슈도 있다면 함께 읽으십시오. 변경 사항이 대상으로 하는 화면과 사람들이 보기를 기대하는 스크린샷이 자주 언급됩니다.
2. 모든 시각적 변경 목록 작성
각 변경 덩어리(hunk)를 사용자에게 보이는 것으로 추적합니다:
- 뷰 코드, 스타일, 토큰, 아이콘, 카피, 번역. 각각이 후보입니다. 공유 코드(UI 컴포넌트, 포맷팅 헬퍼, CSS 토큰)의 경우, 호출자를 검색하고 이를 렌더링하는 모든 화면을 나열합니다. 공유 코드 변경은 일반적으로 브랜치가 의도한 것보다 더 많은 곳에서 보입니다.
- 데이터 상태. 각 화면에 대해 변경된 코드가 취하는 분기를 읽습니다: 로드됨, 로딩 중, 빈 상태, 오류, 값 없음, 0과 음수, 긴 텍스트, 하나의 항목과 많은 항목, 각 모드나 설정. Diff가 렌더링을 변경하는 상태만 유지합니다.
- 상호작용 상태. 호버, 포커스, 눌림, 비활성화, 선택됨; 열린 팝오버, 메뉴, 시트, 다이얼로그; 유효성 검사 오류를 표시하는 필드. 이러한 상태는 스크린샷 전에 단계가 필요합니다(4단계).
- 브랜치가 추가하거나 제거하는 화면. 이러한 경우 한쪽만 있으므로, 행은 다른 쪽에 플레이스홀더를 표시합니다.
- 프로젝트가 지원하는 환경 중 변경 사항이 다르게 보일 수 있는 환경: 다크 테마, 모바일 및 데스크톱 너비, 다른 로케일.
후보를 세 가지 목록으로 정렬합니다:
- 시각적: 화면에 차이가 있습니다. 이 항목들이 행이 됩니다.
- 비시각적: 변경 사항이 접근성 트리, 속성, 스크린리더 전용 텍스트, 동작 또는 코드 구조에만 영향을 미칩니다. 이들은 행이 아닙니다. 보고서에 이름을 나열하여 독자가 고려되었고 누락되지 않았음을 알 수 있게 합니다. 사용자가 그래도 표시하기를 원하는 경우, 접근성 트리 발췌문을 이미지로 캡처하여 행에 표시하고 그렇게 레이블을 붙입니다.
- 불확실: 보이지 않게 의도되었지만 무언가를 이동하거나 색상을 변경할 수 있는 마크업이나 클래스 변경(새로운 래퍼 요소, 포지셔닝 클래스, 교체된 헬퍼). 이들을 캡처하고 픽셀 검사가 판단하게 합니다.
모션 변경(애니메이션, 전환, 타이밍)은 정지 이미지로 표시할 수 없습니다. 보고서의 "표시되지 않음" 아래에 두고 확인 방법을 설명합니다.
행을 적절하게 그룹화합니다: 호출 사이트별이 아니라, 뚜렷한 모양별로 하나의 행을 만듭니다. 변경된 셀을 동일한 방식으로 사용하는 화면이 열 개라면 그중 하나 또는 두 개를 보여주고 나머지는 메모에 이름을 나열합니다. 사람이 실제로 읽을 테이블을 목표로 합니다. 약 12행을 넘으면 영역별로 두 번째 이미지를 만들고 그렇게 언급합니다.
시각적 및 불확실 목록이 모두 비어 있으면 여기서 중단합니다. 사용자에게 브랜치에 시각적 변경 사항이 없음을 알리고, 고려된 항목과 각 항목이 시각적이지 않은 이유를 나열하며, 이미지를 생성하지 않습니다. 불확실 항목만 있고 모든 쌍이 동일한 것으로 판명된 경우에도 결과는 같으며, 동일한 쌍이 증거입니다: 확인되었고 변경되지 않음으로 보고합니다.
3. 기준 브랜치와 현재 브랜치를 로컬에서 빌드
두 브랜치 모두 로컬 빌드에서 캡처하며, 배포에서는 절대 캡처하지 않습니다: 배포는 작업 트리보다 뒤처져 있으며 커밋되지 않은 작업을 표시할 수 없습니다.
-
현재 브랜치: 마지막 변경 후 빌드된 현재 작업 트리.
-
기준 브랜치: 병합 기준(merge base)의 별도 worktree. 사용자의 작업 트리는 절대 건드리지 않습니다. 사용자의 체크아웃에서 브랜치를 전환하거나 stash하지 마십시오.
git worktree add --detach <scratchpad>/before-after-base "$base"거기에 종속성을 설치합니다. 메인 체크아웃의 종속성 디렉토리를 심볼릭 링크하는 것은 diff가 잠금 파일을 건드리지 않을 때만 괜찮습니다. 작업이 끝나면 worktree를 제거합니다(
git worktree remove).
프로젝트의 문서화된 명령어를 사용합니다(README, AGENTS.md, CLAUDE.md, 개발 문서 및 run 스킬 읽기). 양쪽 모두 동일한 스테이징 또는 테스트 백엔드와 통신해야 하며, 프로덕션은 절대 안 됩니다. 어떤 명령어가 어떤 백엔드를 대상으로 하는지 불분명하면 빌드 구성을 읽고, 그래도 의심스러우면 중단하고 질문합니다. 캡처하기 전에 각 브랜치에서 실제 API 요청의 호스트를 확인합니다.
프로젝트의 프로덕션 빌드를 정적으로 서빙하는 것(build 다음에 preview 또는 정적 서버)을 개발 서버보다 선호합니다. 개발 서버는 핫 리로드 클라이언트와 오버레이를 추가하고, worktree당 watcher 프로세스가 필요할 수 있으며, 출시되는 것과 다르게 렌더링될 수 있습니다. 프로젝트 자체 빌드 명령어가 아닌 도구로 빌드하는 경우, 페이지가 렌더링되는지 확인합니다: 프로젝트가 번들을 후처리할 수 있습니다. 빌드는 사용자의 작업 트리에서 출력 디렉토리를 비우거나 덮어쓸 수도 있습니다. 이들은 생성된 파일이지만, 보고서에 재빌드한 내용을 말하고, 빌드가 제거한 것이 개발 설정에서 기대하는 것이라면 되돌려 놓습니다.
캡처를 신뢰하기 전에, 두 빌드가 다르다는 것을 확인합니다: 각 브랜치에서 변경된 요소의 마크업을 읽고 diff의 변경 사항을 확인합니다. 동일한 코드를 서빙하는 두 서버는 증명할 것이 없는 동일한 쌍을 제공합니다.
두 빌드를 서빙하는 방법을 선택합니다:
- 두 개를 동시에, 두 개의 사용 가능한 포트에서. 이것이 가장 간단하며, 쌍의 두 캡처가 몇 초 간격으로 이루어집니다. 로그인이 필요 없거나 로그인이 포트 변경에도 유지되는 화면에서 작동합니다. 쿠키는 동일한 호스트의 포트 간에 공유되지만 로컬 스토리지는 그렇지 않으며, 백엔드는 특정 오리진만 허용할 수 있습니다. 두 번째 포트에서 로그인된 화면이 실제로 로드되는지 확인한 후에 의존합니다.
- 하나씩, 동일한 포트에서. 기준 브랜치를 프로젝트의 일반적인 포트에서 서빙하고
--side=before로 캡처한 후 중단하고, 현재 브랜치를 그 포트에서 서빙하고--side=after로 캡처합니다. 저장된 로그인 상태와 허용된 오리진이 양쪽에 적용됩니다. 캡처 간격이 분 단위이므로 데이터를 모의(mock)하거나 안정적이라고 알려진 데이터여야 합니다.
프로젝트에 컴포넌트 카탈로그(Storybook, "workshop" 앱 등)가 있고 변경 사항이 공유 컴포넌트에 있다면, 전체 앱보다 카탈로그에서 캡처하는 것이 더 저렴하고 안정적이며 일반적으로 로그인이 필요 없습니다. 그래도 가능한 경우 변경당 최소한 하나의 실제 화면을 캡처하여 이미지가 컨텍스트 안에서 보이도록 합니다. 실제 화면에 도달할 수 없는 경우(예: 테스트 로그인 없음), "표시되지 않음" 아래에 그렇게 언급합니다.
4. 동일한 조건에서 각 쌍 캡처
스크래치패드에 shots.mjs를 scripts/capture.mjs 헤더에 명시된 형식으로 작성하고, 프로젝트 루트에서 실행하여 Playwright가 해결되고 출력 폴더가 올바른 저장소 및 브랜치 이름을 얻도록 합니다:
node <this skill>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>
스크립트는 두 URL에 대해 동일한 단계를 실행합니다. 설치된 Chrome, 장치 스케일 팩터 2, 축소된 모션을 사용합니다. 전환을 끄고, 무한 애니메이션(쉬머, 스피너)을 첫 번째 프레임으로 재설정하고 유한한 애니메이션을 완료하며, 글꼴과 네트워크 안정을 기다리고, 시간을 지정하면 시계를 고정합니다. 위에서 설명한 Documents 폴더에 shots/<slug>.before.png, shots/<slug>.after.png, 그리고 5단계용 manifest.json을 쓰고, shots.mjs를 복사하며, 마지막 줄로 폴더 경로를 출력합니다. --only=<slug>는 한 행만 다시 캡처합니다. 실패한 샷은 <slug>.<side>.FAILED.png로 페이지 전체 뷰포트를 남겨서 페이지가 어떻게 보였는지 보여줍니다.
프로젝트의 엔드 투 엔드 설정에 저장된 로그인 상태가 있으면 storageState로 전달합니다(프로젝트 문서에서 어떻게 만들어졌는지 읽기). Orca에서 내장 브라우저(orca-cli 스킬)도 한두 쌍에 대해 작동하지만, 스크립트가 쌍을 반복 가능하게 만듭니다.
shots.mjs에서 올바르게 처리해야 할 사항:
- 양쪽에 동일한 데이터. 라이브 데이터는 두 캡처 사이에 변동됩니다: 가격이 변하고 목록이 재정렬됩니다. 샷의
mock에서 화면이 의존하는 응답을 모의(mock)하는 것이 좋습니다: 스테이징에서 하나의 실제 페이로드를 캡처하고 양쪽에서 동일한 것으로 fulfill합니다. 두 가지 한계:- 브랜치가 요청이나 응답 형태를 변경하는 경우(새 엔드포인트, 새 필드, 변경된 디코더), 하나의 페이로드가 양쪽을 서빙할 수 없습니다. 각 브랜치에 코드가 기대하는 페이로드를 동일한 기본 값에서 구성하여 제공하고, 서브타이틀에 그렇게 언급합니다.
- WebSocket이나 서버 전송 이벤트를 통해 도착하는 데이터는
page.route로 처리되지 않습니다.page.routeWebSocket을 사용하거나, 스트림이 조용한 화면이나 시간을 선택하거나, 주제가 아닌 경우 라이브 요소를 숨깁니다.
- 의도적으로 상태에 도달합니다. 로딩, 오류, 값 없음 상태는 테스트 계정에서 거의 발생하지 않습니다:
mock에서 생성합니다(응답 지연, 실패, 필드 null). 요청 경로와 필드 이름은 추측이 아닌 코드에서 파생합니다.steps에서 상호작용 상태에 도달합니다(호버, 포커스, 클릭하여 열기). - 변경 사항을 컨텍스트와 함께 크롭합니다.
target을 변경 사항을 보여주면서도 화면의 일부로 인식 가능한 가장 작은 요소로 설정합니다: 전체 페이지가 아닌 카드, 테이블, 시트. 약 650 CSS px 이하 너비로 크롭하는 것을 목표로 합니다. 이는 나란히 전체 크기로 맞춰지는 너비입니다. 더 넓은 크롭은 위아래로 쌓이고(before 위, after 아래), 약 1300 CSS px보다 넓으면 축소되어 텍스트를 읽기 어렵게 만듭니다. 양쪽에서 동일한 대상을 사용하여 크롭이 정렬되도록 합니다. - 주제가 아니고 계속 움직이는 것 (티커, 시계, 늦게 로드되는 아바타)을
steps의 스타일 태그로 양쪽에서 숨깁니다.
5. 합성 및 검사
node <this skill>/scripts/compose.mjs <folder>/manifest.json [--diff] [--stack]
이미지는 매니페스트 옆에 before-after.png로 작성되며, 출력의 마지막 줄에 경로가 표시됩니다. --diff는 변경된 픽셀을 마젠타색으로 표시한 행별 이미지를 추가합니다. 변경 사항이 작거나 미묘할 때(간격, 색상, 하나의 글리프) 사용하고, 변경 사항이 명확할 때는 생략합니다. 행의 두 샷 크기가 다른 경우, 비교는 왼쪽 위 모서리에 정렬되므로 이동 이후의 모든 것이 변경된 것으로 간주됩니다. 행에 그렇게 명시되며, diff 이미지는 대략적인 가이드일 뿐입니다.
스크립트는 행의 두 샷을 동일한 배율로 그립니다. 행당 변경된 픽셀 비율과 각 행의 레이아웃 방식을 출력하며, 쌍이 동일하면 종료 코드 3으로 종료합니다. 그런 다음:
- 동일한 쌍은 캡처가 변경 사항을 놓쳤거나(잘못된 상태, 잘못된 화면, 캐시, 실제로 기준이 아닌 기준 빌드) 변경 사항이 시각적이지 않음을 의미합니다. 원인을 찾습니다. 캡처를 수정하거나, 행을 매니페스트에서 제거하고 항목을 비시각적 목록으로 "확인됨, 픽셀 차이 없음"으로 이동합니다. 동일한 쌍이 있는 행을 절대 출시하지 마십시오.
- 이미지를 살펴보고(PNG 읽기) 모든 행을 확인합니다: 보이는 차이가 노트가 설명하는 바로 그 차이이며, 다른 것은 달라지지 않아야 합니다. diff로 설명되지 않는 차이(다른 가격, 누락된 행, 다른 곳의 레이아웃 이동)는 데이터 변동이거나 예상치 못한 회귀입니다. 다시 캡처하거나 사용자에게 가능한 회귀로 보고합니다. 숨기지 마십시오.
- 모든 샷의 텍스트를 읽을 수 있는지 확인합니다. 스크립트의 "텍스트를 읽을 수 없을 수 있음" 경고에 대해 조치를 취합니다: 더 좁게 크롭하고
--only로 해당 행을 다시 캡처합니다. - 이미지가 매우 길면 영역별로 분할합니다: 브랜치 폴더 내에 영역별 하위 폴더를 만들고, 각각
../shots/...를 가리키는 경로의 자체manifest.json을 가지며, 각각을 합성합니다.
6. 보고
사용자에게 제공:
- PNG의 전체 절대 경로.
- 행별 한 줄씩.
- 표시되지 않음: 비시각적 변경 사항, 픽셀 검사에서 변경되지 않은 것으로 확인된 불확실 항목, 모션 변경, 캡처할 수 없었던 시각적 변경 사항(그 이유 포함), 표시된 행의 중복으로 제외된 호출 사이트.
- 픽셀 검사나 직접 확인에서 발견한 예상치 못한 모든 것.
- 쌍이 어떻게 생성되었는지(실제 스테이징 데이터 또는 모의된 응답; 카탈로그 또는 실제 앱)에 대한 설명, 그래서 독자가 이미지가 무엇을 증명하는지 알 수 있습니다.
시작한 개발 서버를 중지하고 기준 worktree를 제거합니다. 샷, shots.mjs 복사본 및 매니페스트는 출력 폴더에 남아 나중에 --only로 단일 행을 다시 캡처할 수 있습니다.