byteratio/ux-agents

UX 테스팅 에이전트 — 페르소나 기반 브라우저 구동 리뷰

단위 테스트와 인간의 셀프 리뷰가 놓치는 UX 문제를 잡아내는 패턴입니다. 실제 브라우저를 Playwright를 통해 구동하는 페르소나 에이전트를 정의하고, 특정 사용자 관점에서 여정을 탐색하며 마찰 지점을 보고합니다. 이 패턴의 유용성을 입증한 실제 사례: 에이전트가 첫 실행 세션에서 워크스페이스 드롭다운 동기화 버그를 누군가 이슈로 등록하기 전에 발견했습니다.

설정 시기

• 프로젝트에 여러 뚜렷한 사용자 유형이 있는 웹 프론트엔드가 있을 때 — 신입 대비 중견 대비 은퇴자, 무료 티어 대비 엔터프라이즈 관리자, 환자 대비 제공자 등. 페르소나는 기본값/용어/사용 가능 기능이 각각에게 실제로 다르게 느껴질 정도로 달라야 합니다.
• 앱의 표면적이 넓어서 모든 변경 사항에 대해 모든 페르소나를 수동으로 테스트하는 것이 현실적이지 않을 때.
• 개발 서버를 인증 절차 없이 로컬에서 실행할 수 있거나 (또는 테스트용으로 스크립트 가능한 인증 우회 방법이 있을 때).

다음의 경우에는 건너뛰세요: UI가 없는 API, CLI, 단일 페르소나 내부 도구.

에이전트 위치

프로젝트 범위의 .claude/agents/ 디렉토리에 위치하며, 사용자의 전역 설정이 아닙니다. 페르소나는 프로젝트별 지식(숫자 범위, 기능 이름, 여정)을 포함하므로 일반화될 수 없습니다. 각 페르소나는 프론트매터와 함께 자신의 .md 파일을 갖습니다:

---
name: <persona-slug>-ux
description: <앱>을 <한 줄 페르소나>의 관점에서 UX 테스트합니다. Playwright를 통해 실제 브라우저를 구동하고, 각 탭을 스크린샷으로 캡처하며, 마찰 지점을 보고합니다. <영역>에 영향을 미치는 UI 변경 후 사전에 사용하세요.
tools: Bash, Read, Write, Edit
---

당신은 <페르소나> 역할을 수행하는 UX 테스팅 에이전트입니다.

## 당신의 페르소나
<5–10줄: 나이, 역할, 지식 수준, 이번 세션의 목표, 그들이 알지 못할 것>

## 워크플로우
1. API를 통해 새 워크스페이스를 생성합니다 (실제 데이터를 오염시키지 마세요).
2. API를 통해 페르소나에 맞는 입력 데이터를 시드합니다.
3. Playwright로 /tmp/ux-<slug>.mjs에서 브라우저를 구동합니다.
4. 이 페르소나와 관련된 탭을 스크린샷으로 캡처합니다.
5. 각 스크린샷을 읽고 평가합니다.
6. 결과를 plans/ux-reports/<slug>-<date>.md에 작성합니다.
7. 테스트 워크스페이스를 정리합니다.

또한 같은 디렉토리에 _shared-ux-protocol.md 파일을 넣습니다(앞줄 밑줄은 에이전트로 오인되지 않도록 함). 이 파일에는 환경 기대 사항, 출력 형식, "평가할 항목" 루브릭 등이 포함됩니다. — 페르소나별 파일은 필요할 때 이를 인용합니다.

필수 준비 사항

• plans/ux-reports/ 디렉토리가 존재해야 합니다 (설정 중에 생성하여 보고서가 저장될 장소를 확보). 이는 plans/ 디렉토리가 진행 중인 작업에 대한 문서를 보관하고, git에 커밋되어 채팅 세션이 끝나도 추론이 유지되는 관례를 가정합니다. UX 보고서도 그러한 문서 중 하나입니다. 프로젝트에 plans/ 디렉토리가 없으면 생성하거나, 사용자와 다른 위치를 협의하여 모든 페르소나 파일에 기록하세요. 에이전트가 경로를 하드코딩하기 때문입니다.
• Playwright가 npx playwright를 통해 작동해야 합니다 (에이전트는 새 머신에서 npx playwright install chromium이 한 번 필요할 수 있습니다 — 이를 에이전트 지침에 포함하세요).
• 데이터 시딩을 위한 API가 존재하거나, 결정론적 UI 흐름이 문서화되어야 합니다. 이 중 하나가 없으면 에이전트가 너무 취약해집니다.

페르소나 설계 규칙

• 지식 격차가 가치다 — 신입 에이전트는 경험이 많은 사용자가 눈 하나 깜짝하지 않을 전문 용어를 발견하고, 은퇴자 에이전트는 지나치게 단순화된 부분을 발견합니다. 두 페르소나가 동일한 보고서를 생성한다면 통합하세요.
• 세션당 구체적인 목표를 명시하세요, 모호한 "앱 탐색"이 아닙니다. "이 급여로 은퇴할 수 있을까?"는 테스트 가능합니다. "앱 사용"은 그렇지 않습니다.
• 그들이 알지 못하는 것을 명시하세요 — "SWR / Coast FI / 72(t)가 무엇인지 모른다"는 에이전트가 해당 용어를 무시하지 않고 표시하도록 강제합니다.
• 숫자 범위가 중요합니다 — 페르소나가 5,000달러를 저축했다면, 500,000달러 저축자를 위해 설계된 기본값은 차트 축 스케일링, 0 처리 등에서 일반적인 페르소나가 놓칠 버그를 드러냅니다.

출력 규율 (모든 에이전트에 인코딩)

• 모든 발견 사항을 [blocker] / [friction] / [polish]로 태그하세요.
• 문제당 한 줄 수정 제안을 포함하세요.
• 우선순위가 지정된 실행 목록을 제공하기 위해 "다음에 출시할 상위 3개 수정 사항" 섹션으로 마무리하세요.
• 실제로 스크린샷/API 응답에서 관찰된 것만 보고하세요 — 추측성 불만은 없습니다.

에이전트 실행

.md 파일을 만든 후, Claude Code를 다시 시작하세요 — 에이전트 정의는 세션 시작 시 스캔됩니다. 새 세션에서: use the <persona>-ux agent to review the calculator after my latest changes를 사용하세요. 각 실행은 몇 분이 소요되며(실제 브라우저), 모든 변경 사항에 대해 실행하지 말고 의미 있는 UI 작업 후에 실행하세요.

사용자를 위해 추적할 사항

이 패턴을 설정할 때 프로젝트의 CHANGELOG.md 또는 plans/ 아래 계획 문서에 다음을 기록하세요:

• 에이전트가 존재한다는 사실과 보고서 위치.
• 개발 서버 사전 요구 사항 (새 기여자가 준비되지 않은 프로젝트에서 에이전트를 실행하려고 시도하지 않도록).
• 페르소나가 의존하는 프로젝트별 데이터 시딩 특이 사항.

일반적인 함정

• 에이전트가 개발 서버를 시작하지 않도록 하세요. 좀비 프로세스를 남기는 경향이 있습니다. curl -fsS http://localhost:<port>로 확인하고 서버가 다운되어 있으면 진행을 거부하도록 하세요 — 사용자가 시작합니다.
• 실제 워크스페이스/데이터셋을 재사용하지 마세요. 항상 UX: <persona> 워크스페이스를 생성했다가 삭제하세요. 남은 상태로 인해 오염된 발견 사항은 사용자의 리뷰 시간을 낭비합니다.
• 페르소나를 일반적인 "캐주얼 사용자"로 만들지 마세요. 거기서 노이즈가 발생합니다. 페르소나가 더 구체적일수록 보고서가 더 유용합니다.
• 너무 많이 병렬로 실행하지 마세요 — 에이전트당 Playwright + 개발 서버 + Chromium은 노트북의 메모리를 빠르게 고갈시킬 수 있습니다. 직렬 실행으로 충분합니다.