UI 미리보기 게이트

UI 미리보기 게이트은(는) 무엇을 하나요?

화면을 변경하는 모든 작업은 4단계를 거칩니다. 변경이 작아 보인다고 단계를 건너뛰지 마십시오. 이미지가 리뷰어의 승인 기준입니다.

1. 현재 상태 검사
2. 미리보기 및 승인 받기 (작업 시작 전)
3. 구현
4. 결과가 승인된 미리보기와 일치하는지 확인 (작업 종료 후)

예외: 의도한 화면을 변경하지 않는 버그 수정은 2단계를 건너뛸 수 있습니다. 사용자가 여전히 차이를 볼 수 있다면, 수정 전후 이미지를 함께 보고하십시오. 이전과 다른 화면, 대화상자, 시트 또는 메시지를 표시하는 것은 화면 변경이며, 기존 컴포넌트를 재사용하더라도 이 예외에 해당하지 않습니다. 먼저 2단계 승인을 받으십시오.

적용 시기

• 요청받지 않아도 적용하십시오. 사용자가 이 스킬을 직접 언급할 필요가 없어야 합니다.
• 첫 번째 턴뿐만 아니라 모든 턴에서 확인하십시오. 지원, 연구, 리뷰, 버그 보고로 시작된 대화가 중간에 "화면이 X라면 어떨까?"로 바뀌는 경우가 많습니다. 그 턴부터 이 스킬이 적용됩니다.
• 화면에 대한 "어떻게 생각하나요?", "아이디어 있나요?", "어떻게 보일까요?"도 제안으로 간주합니다.
• 시작되면, 승인된 변경이 확인(4단계)되거나 사용자가 변경을 포기할 때까지 이후 턴에서도 계속 따르십시오.
• 텍스트나 사례 표로만 답변된 제안은 불완전합니다. 동일한 답변에 변경 전후 이미지를 첨부하거나, 아직 만들 수 없는 이유와 가능한 시점을 말하십시오.
• UI 변경이 승인 대기 중이거나 진행 중인 동안에는 진행 보고서, 옵션 목록, 관련 질문에도 변경 전후 이미지를 다시 첨부하거나 이미지 경로를 제공해야 합니다. 변경된 화면을 텍스트만으로 설명하지 마십시오.

스킬은 일반적으로 각 턴마다 설명을 기반으로 선택되므로, 대화 중간 턴을 놓칠 수 있습니다. 이 파일 옆의 agent-instructions.md는 AGENTS.md / CLAUDE.md에 추가할 짧은 규칙으로, 에이전트가 매 턴마다 다시 확인하도록 합니다.

1. 현재 상태 검사

기억이나 추측으로 제안하지 마십시오.

• 실행 중인 dev 서버 또는 빌드에서 실제 화면을 캡처하십시오. 기본 뷰포트는 모바일 375px 너비입니다. 변경이 데스크톱 레이아웃에도 영향을 미치는 경우 데스크톱을 추가하십시오.
• 이를 렌더링하는 코드(탭/라우트 구조, 컴포넌트, 현재 카피)를 읽으십시오.
• 증거를 path/to/file:line과 캡처로 기록하십시오. 현재 UI에 대한 모든 주장은 이 중 하나를 가리켜야 합니다.
• 기존 컴포넌트, 패턴, 카피를 우선 사용하십시오. 새 패턴이 필요한 경우, 기존 패턴이 적합하지 않은 이유를 명시하십시오.

scripts/capture.mjs(스크립트 참조)로 캡처하여 이전 화면, 미리보기, 확인 샷이 하나의 뷰포트, 스케일, 데이터 상태를 공유하도록 하십시오.

사례 목록 (첫 번째 미리보기 전에 요청 없이 수행)

승인자는 "탭한 후에는 무엇이 있나요?" 또는 "데이터가 있으면 어떻게 되나요?"라고 묻지 않아야 합니다. 미리보기를 보내기 전에, 코드와 실제 앱에서 변경이 영향을 미치는 모든 사례를 나열하십시오:

• 변경된 화면의 상태: 비어 있음 / 데이터 있음 / 항목 많음(생략, "모두 보기") / 로딩 / 오류 / 요금제, 역할 또는 권한에 의해 잠김 / 기타 구성(단일 vs. 다중 스토어, 기능 플래그).
• 새롭거나 변경된 컨트롤에서 접근 가능한 모든 화면: 양식, 선택기, 대화상자, 유효성 검사 오류, 취소/뒤로, 확인, 성공, 실패.
• 작업 후: 작업 완료 후 원래 화면의 모습(새 항목 나타남, 카운터 변경), 실행 취소 또는 편집 방법.
• 동일한 데이터를 표시하는 다른 곳: 목록, 상세 화면, 히스토리, 보고서, 내보내기, 다른 플랫폼(데스크톱, 웹, LINE, 고객 측). 각각을 변경됨 / 변경되지 않았지만 새 데이터 표시 / 영향을 받지 않음으로 표시하십시오.

첫 번째 미리보기와 함께 사례를 표로 보내십시오: 사례, 사용자가 보는 것, 재사용된 기존 컴포넌트, 이미지 상태(첨부됨 / 테스트 데이터 필요 - 준비 방법 / 범위 밖 - 이유). 미리보기는 배치로 도착할 수 있지만, 첫 번째 메시지는 항상 전체 사례 목록을 보여주며, 한 이미지의 승인이 아직 표시되지 않은 사례의 승인을 의미하지 않습니다. 질문만 나열하지 말고 미결 결정에 대한 합리적인 기본값을 제안하십시오.

2. 미리보기 및 승인 받기

구현 코드를 작성하기 전에, 승인자에게 하나의 나란히 배치된 이미지와 간단한 요약을 보여주고 명시적인 확인을 기다리십시오.

이미지 규칙:

• 이전(왼쪽)과 이후(오른쪽)를 하나의 이미지에 표시하십시오.
• 변경된 영역에 박스를 그리십시오: 이전은 빨간색, 이후는 초록색.
• 박스를 쌍으로 배치하십시오: 모든 변경 사항은 양쪽의 일치하는 위치에 박스가 있어야 합니다. 추가의 경우, 이전 화면의 삽입 지점에 얇은 마커를 간격에 표시하십시오("pad": 0, 작은 h). 제거의 경우, 이후 화면의 간격을 표시하십시오. 누락된 요소를 대신하기 위해 관련 없는 이웃(예: 아래 행)에 박스를 절대 씌우지 마십시오.
• 박스 좌표는 capture.mjs --selector 출력(또는 상호작용이 필요한 상태(예: 입력 후 열리는 대화상자)에서는 e2e 테스트에서 Playwright로 측정한 요소 rect)에서 가져오고, 눈대중으로 하지 마십시오. 보내기 전에 구성된 이미지를 확인하여 각 박스가 대상 위에 있는지 확인하십시오.
• 양쪽 모두 동일한 뷰포트, 스크롤 위치, 샘플 데이터를 사용하십시오.
• 화면이 상태(데이터 있음/없음, 오류, 비어 있음, 역할별 또는 구성별)에 따라 분기되는 경우, 변경이 닿는 모든 상태에 대해 하나의 변경 전후 쌍을 보여주십시오. 표시하지 않은 상태는 승인되지 않습니다. 상태당 하나의 이미지를 만드십시오. 여러 쌍을 하나의 이미지에 넣지 마십시오.
• 스테이징(임시로 코드를 변경하여 열리게 함)을 통해서만 접근 가능한 실제 화면은 사양에 "staged"를 포함해야 이미지에 표시됩니다.
• 전송 전 확인: compose.mjs는 이러한 규칙을 위반하는 사양을 거부하고 체크리스트를 출력합니다. 이미지를 열고 각 항목에 답변한 후 메시지에 답변을 넣으십시오(템플릿 참조). 항목이 실패하면 수정하고 다시 구성하십시오. 텍스트로 실패한 항목을 설명하지 마십시오.
• 아래 이미지 정책을 따르십시오.

이미지 정책

사용자 또는 프로젝트가 목업 허용 여부를 결정합니다. 요청 또는 프로젝트 설명(AGENTS.md, CLAUDE.md, 기여 문서)에서 선택 사항을 찾으십시오. 명시된 바가 없으면 real-only를 사용하십시오. 캡처가 어렵다는 이유로 스스로 mockup-allowed로 전환하지 말고 대신 물으십시오.

• real-only (기본값): 양쪽 모두 실제 실행 중인 앱의 전체 화면 캡처입니다. 이후 화면을 프로토타입 브랜치나 기능 플래그 뒤에 빌드하고 캡처하십시오. 잘린 조각이나 붙여넣은 조각, 코드나 수작업으로 다시 그린 목업(생성된 이미지 포함), 행을 반으로 자른 캡처, 실제 앱이 표시하는 것과 다른 더미 데이터를 사용하지 마십시오.
• mockup-allowed: 이후 화면은 사용자 또는 프로젝트가 명시적으로 허용하는 경우에만 목업일 수 있습니다. 이전 화면은 여전히 실제 캡처입니다. 구성 사양에서 모든 목업 패널에 "mockup": true를 표시하여 이미지에 표시되도록 하고, 승인 요청에 명시하십시오. 목업은 4단계 증거로 간주되지 않습니다. 확인은 항상 구현된 화면의 실제 캡처를 사용합니다.

더 엄격한 프로젝트 규칙이 항상 느슨한 사용자 선호를 우선합니다. 충돌하는 경우 지적하고 프로젝트 규칙을 따르십시오.

요약 (references/templates.md 참조):

• 위치: 어떤 화면/탭과 그 위의 어디에 변경이 나타나는지
• 사용자 유형별로 가능해지는 것 (예: 관리자, 고객)
• 변경되지 않는 것, 및 영향을 받는 플랫폼/표면

승인은 정확히 표시된 내용을 다룹니다. 그 외의 것은 새 미리보기가 필요합니다.

3. 구현

승인된 미리보기에 맞춰 빌드하십시오. 구현 과정에서 눈에 띄는 차이(레이아웃, 카피, 동작, 새 플랫폼 영향)가 발생하면 중단하고 업데이트된 미리보기로 2단계로 돌아가고, 차이를 그대로 출시하지 마십시오.

여기에는 코드 리뷰에 따른 작은 카피 수정 및 수정도 포함됩니다. 수정이 승인된 이미지 이상으로 사용자가 보는 것을 변경하는 경우 중단하고 먼저 새 미리보기 승인을 받으십시오. 이후 텍스트로 보고하는 것은 인정되지 않습니다.

4. 승인된 미리보기와 비교 확인

코드 차이만으로 완료를 보고하지 마십시오.

1. 미리보기와 동일한 캡처 설정 및 상태를 사용하여 구현된 화면을 다시 캡처하십시오.
2. 확인 이미지를 구성하십시오: 승인된 미리보기 | 실제 결과. 약속된 각 변경 사항에 박스를 씌우고, 승인된 미리보기와의 모든 차이점(작은 이동이라도)을 호박색으로 박스 처리하십시오. 텍스트로만 설명된 차이는 확인되지 않습니다.
3. 항목별로 확인:
   • 약속된 모든 변경 사항이 존재하고 미리보기와 일치하는지
   • "변경되지 않음"으로 나열된 모든 것이 변경되지 않았는지
   • 박스 영역 밖의 어떤 것도 이동, 줄바꿈, 오버플로되지 않았는지
   • 변경된 상호작용이 렌더링될 뿐만 아니라 실제로 작동하는지 e2e 테스트 통과는 동작만 확인합니다. 변경되지 않아야 하는 각 상태에 대한 이미지 확인을 대체하지 않습니다.
4. 결정:
   • 일치: 확인 이미지와 체크리스트 결과를 함께 보고하십시오.
   • 승인된 의도 내에서의 사소한 불일치: 수정하고, 다시 캡처하고, 다시 확인하십시오.
   • 승인된 내용을 변경하는 불일치: 보고하고 다시 승인을 받으십시오.

확인할 수 없는 항목(플랫폼, 기기, 실제 데이터)은 별도로 나열하고 완료되었다고 말하지 마십시오.

스크립트

두 스크립트 모두 Node 18+와 Playwright가 필요합니다 (npm i -D playwright && npx playwright install chromium). 기존 설치를 재사용하려면 PLAYWRIGHT_MODULE을 모듈 경로로 설정하십시오.

화면을 캡처하고 요소의 박스 좌표를 가져옵니다:

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

선택자의 rect를 CSS 픽셀 단위로 출력하며, boxes로 붙여넣을 준비가 됩니다.

JSON 사양으로 패널을 구성합니다:

node scripts/compose.mjs spec.json

사양 형식, 톤 및 확인 레이아웃은 references/compose-spec.md에 있습니다.