사용 설명서

Prefly 는 가상 고객이 내 서비스를 직접 써 보고, 어디서 막히는지 알려 주는 맥 앱이다. 가상 고객은 내 맥에 있는 전용 Chrome 으로 화면을 보고, 누르고, 입력한다. 그래서 내 컴퓨터에서만 열리는 개발 서버(localhost)도 그대로 테스트할 수 있다.

• 맥(macOS) 한 대
• 테스트할 주소. 개발 서버(localhost:3000 같은 주소)나 공개된 주소
• AI 모델 하나. 가상 고객이 다음에 무엇을 할지 판단할 때 쓴다(아래 「AI 모델 연결」)

지금은 출시 전이다. 앱은 대기 명단에 등록한 분께 먼저 보내 드린다.

1. 1앱을 열고 AI 모델을 연결한다.
2. 2테스트할 주소와 맡길 일을 한 문장으로 적는다. 예: 「회원가입하고 첫 주문까지 해 보기」
3. 3Prefly 가 테스트 계획(케이스)을 제안한다. 어떤 고객이 무엇을 할지 보고, 고칠 것이 있으면 고친 뒤 시작한다.
4. 4실행 화면에서 가상 고객이 서비스를 쓰는 모습을 실시간으로 본다. 필요하면 멈추거나, 직접 조작해서 도와줄 수 있다.
5. 5끝나면 리포트에서 찾은 문제를 본다. 문제마다 그때의 화면과 고객이 한 행동이 근거로 붙어 있다.

캡차, 본인인증, 실제 결제처럼 사람이 해야 하는 일은 가상 고객이 대신하지 않는다. 그 앞에서 멈추고 사람에게 넘긴다.

가상 고객은 매 걸음마다 AI 모델에게 「지금 화면에서 무엇을 할지」 묻는다. 아래 중 하나를 연결하면 된다.

Claude Code, Codex, Cursor 같은 코딩 에이전트(코드를 대신 짜 주는 AI)가 터미널의 prefly 명령으로 테스트를 돌리고, 결과를 대화창으로 받을 수 있다. 코드를 고친 뒤 바로 확인할 때 편하다. 앱은 결과를 크게 보고 싶을 때만 열면 된다.

1. prefly 명령을 설치한다. 지금은 Rust 가 깔려 있어야 한다(앱에 같이 넣는 작업을 하고 있다).

cargo install --git https://github.com/inha-developers/prefly prefly-cli

2. 코딩 에이전트에 붙인다. 스킬(에이전트가 읽는 사용 안내)을 써 준다. MCP(에이전트가 도구로 부르는 연결)까지 등록하려면 --mcp 를 붙인다.

prefly install
prefly install --mcp

3. 에이전트에게 말로 맡긴다.

Prefly 로 회원가입부터 첫 주문까지 테스트해 줘

직접 쓸 때 자주 쓰는 명령이다.

• 모델 고르기: --model sonnet, --model haiku 처럼 고른다. 기본값은 이 명령을 부른 에이전트를 따른다.
• 자동 검사(CI)에 넣기: --fail-on bug 를 붙이면 확인된 버그가 있을 때 실패로 끝난다.
• 셸 명령을 못 쓰는 에이전트(Cursor, VS Code 등)는 prefly mcp 로 붙는다.
• 화면 글 언어는 --lang ko 처럼 바꾼다. 한국어, 영어, 일본어, 중국어(간체, 번체)를 고를 수 있다.

맡길 일을 한 문장으로 주면 Prefly 가 케이스(어떤 고객이 무엇을 할지)를 제안한다. 같은 케이스를 계속 쓰고 싶으면 제안을 파일로 받아 두고, 그 파일로 다시 돌린다.

prefly plan localhost:3000 "회원가입하고 첫 주문까지" --json > plan.json
prefly test localhost:3000 --cases plan.json

• 방금 돌린 테스트를 고친 코드로 다시 돌릴 때는 prefly test --again 이 더 간단하다. 앞 결과와 무엇이 달라졌는지도 같이 보여 준다.
• 고객을 바꾸려면 --persona <고객 id> 를, 같은 조건으로 여러 번 돌리려면 --repeat 3 처럼 붙인다.

케이스를 YAML 파일(.prefly/cases/)로 저장해 두고 돌리는 기능은 준비 중이다. 지금은 prefly case validate 로 형식만 검사할 수 있다.

가상 고객 한 명은 얼굴, 이름, 확인할 수 있는 특성 1~3개다. 특성은 조건(엔진이 화면과 환경에 거는 값), 행동(고객이 하는 일), 이탈 기준(언제 그만두나) 셋뿐이다. 나이와 직업은 얼굴과 이름표에만 쓰고 행동을 짐작하는 데 쓰지 않는다. 같은 화면이라도 조건에 따라 막히는 곳이 달라진다.

• 조건: 화면(휴대폰, 폭이 좁은 휴대폰, 큰 휴대폰, 작은 휴대폰, 가로로 든 휴대폰, 태블릿, 가로로 둔 태블릿, 반만 띄운 창, 노트북, 데스크톱, 큰 모니터), 화면 확대, 큰 기본 글꼴, 어두운 화면, 대비 높이기, 움직임 줄이기, 느린 인터넷, 느린 기기, 다른 언어와 시간대, 마우스 없이 키보드만 쓰기, 화면 낭독기, 큰 누를 곳, 색을 보는 방식(색약), 흐리게 보이는 화면, 낮은 대비
• 행동: 같은 단추를 두 번 누르기, 뒤로 가기, 이상한 값 넣기
• 이탈 기준: 숫자 기준(기다리는 시간, 전체 입력 수, 같은 화면 입력 수)과 상황 기준(가입부터 하라고 하면 나가요, 총액을 미리 다 못 보면 그만둬요, 언제 오는지 모르면 그만둬요, 반품 안내가 없으면 그만둬요, 간편결제가 없으면 그만둬요)

명단은 이렇게 고른다. 이번 테스트에서 걸렸는지 확인할 수 있는 특성만 쓰고, 다른 고객과 겹치지 않는 조합만 올리고, 되도록 공개 자료로 왜 그 고객이 있는지 받친다. 사람 수를 채우려고 고객을 지어내지 않는다. 엔진이 걸 수 있는 조건이 늘면서 명단도 계속 늘고 있다.

근거: 고객 한 명 화면의 「근거」에 그 고객이 명단에 있는 까닭을 공개 자료로 적는다. 출처 이름과 조사 때, 한국 밖 자료면 나라 이름이다. 수치는 이용 조건이 허락하는 자료만 보이고, 그렇지 않은 자료는 출처와 조사 때만 보인다. WCAG 같은 공개 기준의 값에는 「기준」이 붙는다. 바깥 자료가 말한 사실이고 Prefly 실행 결과의 비율이 아니다. 출처 이름을 누르면 그 자료가 열린다. 근거는 화면에만 보이고 AI 에 가지 않는다. 근거가 없는 고객도 있다.

고객은 무엇을 잘 찾는 사람인지에 따라 넷(기기와 화면, 몸과 도구, 서두름과 참을성, 실수)으로 나뉜다. 테스트를 맡기면 Prefly 가 과제에 맞는 고객을 골라 준다. 직접 고를 때는 시작 화면의 고객 고르기나 가상 고객 화면에서 묶음 다섯(기본, 결제 점검, 접근성 점검: 보기, 접근성 점검: 입력, 모바일 점검) 가운데 하나를 고르면 된다. 묶음 하나가 테스트 한 번(10명까지)이다.

고객이 많으면 가상 고객 화면의 목록은 무리마다 두 줄만 보이고 「n명 더 보기」로 편다. 목록 위 「이름이나 특성으로 찾기」에 이름, 특성 글, 근거의 출처 이름(예: WebAIM)을 넣으면 맞는 고객만 남는다.

결제 고객: 결제 점검 묶음의 고객은 대부분 상황 기준을 가진다. 상황 기준은 고객이 화면을 보고 판단해 그만두고, 그만둔 화면과 까닭이 기록에 남는다. 숫자 기준은 엔진이 세다가 끝낸다. 결제와 주문 확정 단추는 누르지 않는다.

내 고객: 우리 서비스의 실제 손님 조건으로 보고 싶을 때 같은 특성으로 고객을 만든다. 가상 고객 화면 목록 끝의 「고객 추가」에서 이름, 나이, 특성 1~3개를 고른다. 내장 고객은 「복사해서 바꾸기」로 바꾼다. 내장 고객과 합쳐 64명까지다. 메모는 사람만 보고 AI 에 가지 않는다. 여러 명을 골라 「묶음으로 저장」하면 시작 화면에서 그 묶음으로 고를 수 있다.

prefly customers add --name 김민지 --age 63 --condition pageZoom=200%
prefly customers export > .prefly/customers.json
prefly test localhost:3000 "첫 주문까지" --customers-file .prefly/customers.json --persona <내 고객 id>

고객의 화면 조건(휴대폰, 작은 휴대폰, 확대, 큰 글꼴, 어두운 화면, 움직임 줄이기, 느린 인터넷, 느린 기기)으로 사이트의 화면들을 AI 없이 다시 열어 잰다. 가로로 넘침, 잘린 글, 작은 누를 곳, Tab 으로 닿지 않는 곳, 대비 부족, 멈추지 않는 움직임, 느린 첫 화면(2.5초를 넘는 화면)을 조건 없는 화면과 견줘 그 조건에서만 나온 것을 보인다. 입력은 보내지 않고 AI 사용량도 들지 않는다.

언제: 레이아웃, CSS, 글꼴, 색을 바꿨을 때. 고객 테스트를 돌리기 전에 먼저 보면 좋다.

1. 1프로젝트 지도에서 「돌아보기」로 사이트를 한 번 둘러본다(크롤링).
2. 2가상 고객 화면의 「화면별」 보기에서 「조건으로 훑기」를 누르고 조건을 고른다(8개까지, 느린 인터넷과 느린 기기는 4개까지).
3. 3끝나면 조건마다 걸린 화면 수가 나온다. 화면 줄을 펼치면 값과 사진이 보인다. 앞 훑기가 있으면 「앞 훑기와 견줌: 없어짐, 새로 생김, 그대로」가 같이 나온다.
4. 4고친 뒤 다시 훑어 그 줄이 사라졌는지 본다.

「못 잼」: 느린 인터넷과 느린 기기는 앞 화면 10개만 다시 열어 첫 화면이 그려지는 시간을 잰다. 화면은 열렸는데 시간을 재지 못하면 「느린 3G: 못 잰 화면 10개」처럼 따로 적고, 펼친 줄에는 「느린 3G 못 쟀어요」로 보인다. 못 잰 칸은 0 이나 「훑음」으로 세지 않는다.

prefly sweep localhost:3000 --crawl --customer-set mobile
prefly sweep localhost:3000 --customers <고객 id>,<고객 id> --fail-on overflow,slow

자동 검사(CI)에서는 --fail-on 으로 문턱을 건다. 넘으면 종료 코드 1, 판정할 값이 모자라면 3 이다. 엔진의 앞 훑기 대신 저장해 둔 결과(prefly sweep --json)와 견주려면 --compare-with 를 쓴다.

조건이 다른 고객 여럿으로 테스트하면, 같은 화면을 본 고객 가운데 이 조건의 고객에게서만 엔진이 잰 값(가로로 넘침, 잘린 글, 작은 누를 곳, 접근성 규칙, 오류, 느린 첫 화면)을 따로 모아 보인다.

언제: 조건이 다른 고객 셋 이상으로 돌렸을 때. 묶음 「기본」으로 돌리면 된다.

• 앱: 결과의 「자동 검사」 안 「조건별 차이」, 가상 고객 화면의 「화면별」 보기와 고객 한 명 화면
• 터미널: 결과 글의 「조건별 차이」 절, JSON 의 runs[].conditionDiffs

- pageZoom=200% 고객에게서만: shop.test/checkout 가로로 넘침 340px (1명 가운데 1명. 견준 고객 2명에게는 없었다)

「이 조건의 고객에게서만 있었다」는 사실이고, 그 조건 때문이라는 판정은 아니다. 조건이 둘인 고객은 어느 쪽 때문인지 모른다. 가리려면 조건 바꿔 다시 실행을 쓴다.

고객이 기록한 누르기, 스크롤, 뒤로 가기를 AI 없이 다시 해서, 조건 하나만 빼거나 바꿨을 때 같은 단계에서 같은 일이 생기는지 견준다. 입력한 글자는 다시 넣지 않는다.

언제: 찾은 문제나 조건별 차이가 그 조건 때문인지 가릴 때. 통과한 경로를 다른 고객들의 조건으로 넓게 볼 때.

• 문제 화면의 「조건 빼고 다시 실행」: 그 고객의 조건을 하나씩 뺀 채 한 번씩 다시 실행한다.
• 고객 한 명 화면의 「다른 조건으로 다시 실행」, 「화면별」 표의 「통과한 경로를 다른 조건으로 다시 실행」: 고른 고객들의 조건으로 한 번씩 다시 실행한다. 시작 전에 몇 번 실행하는지 보인다.

prefly contrast --review <검토 id> --issue <문제 id>
prefly contrast --run <실행 id> --customer <통과한 고객 id> --with <고객 id>

누르기를 다시 보내므로(장바구니 담기 같은 것이 한 번 더 남을 수 있다) 테스트 환경에서만 쓴다. 결제와 주문 확정, 로그인 단추는 누르지 않고, 저장한 로그인으로 시작한 고객은 다시 실행하지 않는다.

• 먼저 prefly doctor 를 돌린다. 무엇이 준비되지 않았는지 알려 준다.
• 테스트가 시작되지 않으면 AI 모델이 연결됐는지 확인한다.
• 개발 서버를 테스트할 때는 그 서버가 켜져 있는지 확인한다.