peachsolution/peach-review-ux

peach-review-ux — UX 검증 스킬

피치 UI/프로토타입/웹페이지를 UX 법칙 기준으로 검토하는 읽기전용 리뷰 스킬이다.

이 스킬은 코드를 수정하지 않는다. 문제와 개선안을 정리하고, 실제 반영은 peach-gen-ui, peach-team-ui-proto, peach-team-dev 또는 직접 수정 작업으로 넘긴다.

---

입력 대상

다음 입력 중 하나 이상을 받을 수 있다.

| 입력 | 처리 | |------|------| | URL | 브라우저/HTML 내용을 확인하고 화면 흐름을 검토 | | 스크린샷 | 시각적 계층, 정보 밀도, 액션 배치를 검토 | | Vue 파일 경로 | 컴포넌트 구조, 폼/테이블/버튼 배치를 검토 | | ui-proto 태스크 폴더 | overview, 라우트, 화면 파일을 함께 검토 | | Spec 문서 | 요구 흐름과 실제 화면의 UX 부합 여부 검토 | | 자연어 설명 | 명시된 화면/사용자 흐름을 기준으로 휴리스틱 검토 |

---

핵심 원칙

• 읽기전용: 파일 수정, 커밋, 스테이징을 하지 않는다.
• 맥락 우선: 백오피스/운영 도구는 장식보다 반복 업무 효율, 스캔성, 오류 방지가 우선이다.
• 법칙은 근거: UX 법칙을 절대 규칙처럼 적용하지 말고, 화면 목적과 사용자 역할에 맞는 판단 근거로 사용한다.
• 우선순위 중심: 모든 문제를 나열하지 말고 사용자의 작업 성공률에 직접 영향을 주는 문제부터 보고한다.
• 수정 가능성: 추상적 지적보다 화면/코드에서 바로 고칠 수 있는 제안을 우선한다.
• 억지 지적 금지: 문제 개수는 상한으로 본다. 문제가 1개면 1개만 보고하고, 작은 화면에 3개 이상을 억지로 채우지 않는다.

---

참조 로드 규칙

필요한 reference만 읽는다.

| 상황 | 참조 | |------|------| | UX 법칙별 근거가 필요함 | references/laws-of-ux-summary.md | | 피치 백오피스 화면 검토 | references/backoffice-ux-checklist.md | | 보고서 형식이 필요함 | references/review-report-template.md |

---

워크플로우

1단계: 검토 대상 확정

입력에서 검토 대상을 식별한다.

• URL이면 페이지 목적, 주요 사용자, 핵심 작업을 먼저 파악한다.
• 파일/폴더면 관련 화면 파일과 Spec을 읽는다.
• 대상이 모호하면 질문은 1개만 한다.

예:

검토 대상이 여러 개입니다. 이번에는 URL 화면, Vue 파일, ui-proto 폴더 중 무엇을 기준으로 볼까요?

2단계: 화면 목적과 사용자 작업 정의

검토 전에 아래를 한 줄씩 정리한다.

대상 화면:
주요 사용자:
핵심 작업:
검토 범위:

사용자 역할이 명시되지 않으면 화면 구조에서 추론하되, 추론임을 표시한다.

2.5단계: 근거 레벨 표시

각 지적에는 가능한 한 근거 레벨을 붙인다.

| 근거 레벨 | 의미 | |-----------|------| | 코드 확인 | Vue/TS 코드에서 직접 확인 | | DOM 확인 | 실행 화면 DOM/텍스트/상태에서 확인 | | 스크린샷 확인 | 이미지에서 시각 구조로 확인 | | Spec 확인 | Spec 또는 ui-proto 요구사항과 대조 | | 추정 | 화면 목적상 가능성이 있으나 실행 증거는 부족 |

추정만 있는 항목은 높은 심각도로 판정하지 않는다.

3단계: 1차 UX 체크

피치 화면은 아래 8개 기준을 우선 적용한다.

1. 인지 부하: 한 화면에서 이해해야 할 정보가 과하지 않은가
2. 선택 과부하/Hick: 버튼, 필터, 옵션이 한 번에 너무 많이 노출되지 않는가
3. 청킹/근접: 관련 필드와 액션이 의미 있는 그룹으로 묶였는가
4. Jakob/멘탈 모델: 기존 백오피스 관습과 다르게 동작해 사용자를 헷갈리게 하지 않는가
5. Fitts: 주요 버튼과 클릭 대상의 크기·간격이 충분한가
6. Von Restorff/선택적 주의: 핵심 액션이 보조 액션과 구분되는가
7. 피드백/Doherty: 저장, 검색, 로딩, 실패 상태가 즉시 보이는가
8. Peak-End/결과 명확성: 작업 완료 후 결과와 다음 행동이 분명한가

상세 기준은 references/backoffice-ux-checklist.md를 따른다.

4단계: 문제 분류

문제는 아래 심각도로 분류한다.

| 심각도 | 기준 | |--------|------| | 높음 | 사용자가 작업을 실패하거나 잘못된 데이터를 저장할 가능성이 큼 | | 중간 | 작업 시간, 이해 비용, 반복 조작 부담이 커짐 | | 낮음 | 완성도와 일관성 문제이나 즉시 실패로 이어지지는 않음 |

4.5단계: QA 판정 매핑

이 스킬의 판정은 기존 QA 스킬을 직접 실패시키는 판정이 아니다. 후속 작업의 우선순위를 정하기 위한 후보 판정이다.

| 판정 | 조건 | 후속 처리 | |------|------|----------| | REJECTED 후보 | 근거 있는 높음 1건 이상 | 사용자 확인 후 peach-team-ui-proto 또는 peach-team-dev 수정 범위로 넘김 | | CONDITIONAL 후보 | 중간 1건 이상 또는 낮음 여러 건 | 기계 검증과 별개로 UX 리스크 보고 | | 권고 | 낮음만 존재 | 다음 UI 정리 작업 후보로 기록 | | 특이 문제 없음 | 확인 범위 내 주요 UX 리스크 없음 | 통합 작업 없이 종료 |

기계 검증 실패가 아닌 UX 휴리스틱만으로 기존 frontend-qa나 team-e2e를 실패 처리하지 않는다.

5단계: 결과 보고

보고서는 아래 순서로 작성한다.

1. 한줄 결론
2. 주요 문제 3~7개
3. 문제별 UX 법칙 근거
4. 수정 제안
5. 적용 우선순위
6. 남은 확인 사항

보고서 형식은 references/review-report-template.md를 사용한다.

6단계: 후속 연결

리뷰 결과를 다음 작업으로 넘길 때는 아래 기준을 따른다.

| 대상 | 연결 조건 | |------|----------| | peach-team-ui-proto | ui-proto 화면 자체의 레이아웃, 액션 배치, 피드백 문제가 주요 원인 | | peach-team-dev | 본 프로젝트 UI 구현에서 저장/검색/상태 피드백이나 실제 API 흐름 문제가 주요 원인 | | peach-team-e2e | 사용자 흐름에서 결과 확인, 다음 행동, 실패 복구 검증이 필요한 경우 | | 수동 보류 | UX 취향 문제이거나 업무 빈도/사용자 역할 확인이 필요한 경우 |

---

출력 규칙

• 모든 응답은 한글로 작성한다.
• 파일을 직접 수정하지 않는다.
• 문제 없는 항목은 길게 칭찬하지 말고 "특이 문제 없음" 정도로 짧게 처리한다.
• UX 법칙 이름은 한글명 + 영문명을 함께 적는다.
• 근거가 화면에서 확인되지 않으면 "추정"이라고 표시한다.

---

후속 보강 메모

이 스킬은 1차 버전이다. 추후 peach-team-analyze로 다음을 조사해 보강한다.

• Laws of UX 원문과 GeekNews 요약의 법칙 분류 정교화
• 피치 백오피스 화면 패턴별 체크리스트 강화
• proto-ui-qa, frontend-qa, peach-team-e2e에 통합할 최소 체크 항목 선별
• 실제 사용 사례 기반 false positive/false negative 정리