ait-ut

name	ait-ut
description	앱인토스(토스 미니앱) 사용자 페르소나로 UT(사용성 테스트)를 시뮬레이션합니다. 경로를 자동 분석해 메인 플로우를 파악하고 문서화한 뒤 UT 리포트를 생성합니다.
allowed-tools	Read, Bash, Glob, Write
mode	automated
requires	["ait-implement"]
inputs	[{"key":"persona","type":"text","required":false},{"key":"sessionMode","type":"enum","values":["simulate","session"],"required":false}]
outputs	[{"key":"utReport","type":"file","path":"apps/<appName>/docs/user-test/*.md"}]
idempotencyKey	ait-ut

앱인토스 UT 시뮬레이터

앱인토스(토스 미니앱) 실사용자 데이터 기반 페르소나로 UT를 시뮬레이션합니다. 항상 코드를 자동 분석해서 플로우를 파악합니다.

페르소나 소개

페르소나 레퍼런스: @personas.md

코드	이름	나이/직업	핵심 특성
지우	한지우	25세 마케터	빠른 온보딩·공유·직관적 탐색
민석	오민석	28세 공기업	재테크·정보 투명성·분석적
재준	이재준	32세 IT 직장인	속도·효율·TDS 준수
미영	김미영	44세 주부	혜택 명확성·단순 조작
봉수	최봉수	57세 자영업자	단순함·큰글씨·명확한 CTA

---

호출 형식

/ait-ut apps/my-mini-app
/ait-ut apps/my-mini-app --persona 지우,민석
/ait-ut apps/my-mini-app --mode session --persona 미영

--persona 미지정 시 5명 전원, --mode 미지정 시 simulate.

---

실행 모드

Mode 1: 시뮬레이션 (--simulate, 기본값)

AI가 각 페르소나 관점에서 기능을 분석하고 구조화된 UT 리포트를 생성합니다.

Mode 2: 인터랙티브 세션 (--session)

AI가 선택한 페르소나를 연기하며 실시간으로 UT를 진행합니다.

---

수행 단계

STEP 0: 페르소나 선택

스킬 시작 시 가장 먼저 사용자에게 페르소나를 물어본다.

어떤 페르소나로 유저테스트 하시겠어요?

| 번호 | 이름 | 나이/직업 | 핵심 특성 |
|------|------|-----------|-----------|
| 1 | 한지우 | 25세 마케터 | 빠른 온보딩·공유·직관적 탐색 |
| 2 | 오민석 | 28세 공기업 | 재테크·정보 투명성·분석적 |
| 3 | 이재준 | 32세 IT 직장인 | 속도·효율·TDS 준수 |
| 4 | 김미영 | 44세 주부 | 혜택 명확성·단순 조작 |
| 5 | 최봉수 | 57세 자영업자 | 단순함·큰글씨·명확한 CTA |
| all | 전원 | — | 5명 모두 |

번호, 이름(지우/민석/재준/미영/봉수), 또는 all로 선택해 주세요.

사용자가 선택하면 → STEP 1로 이동. --persona 옵션으로 미리 지정된 경우 이 단계를 건너뜀.

---

STEP 1: 코드 자동 탐색

지정된 경로에서 다음 순서로 파일을 읽어 서비스의 메인 플로우를 파악한다.

① 문서 우선 탐색

{path}/README.md
{path}/docs/**/*.md
{path}/CLAUDE.md

② 라우터·진입점 탐색

{path}/src/App.tsx (또는 App.jsx, main.tsx)
{path}/src/router/**
{path}/src/routes/**
{path}/src/pages/**

③ 핵심 화면 컴포넌트 탐색 라우터에서 발견된 페이지 컴포넌트들을 읽어 각 화면의 역할 파악. 화면이 많으면 메인 플로우에 해당하는 것 우선 선택.

④ 서비스/API 레이어 탐색 (선택)

{path}/src/services/**
{path}/src/api/**
{path}/src/hooks/**

핵심 비즈니스 로직이 있는 경우만 읽음.

파악할 내용:

• 앱의 목적과 핵심 가치 제안
• 주요 사용자 태스크 (무엇을 하러 오는 앱인가)
• 화면 플로우 (진입 → 핵심 태스크 완료 → 이탈/재방문)

---

STEP 2: 메인 플로우 확인

탐색 결과를 사용자에게 제시하고 확인을 요청한다.

## 파악한 메인 플로우

**앱 목적**: [한 문장 요약]

**핵심 사용자 태스크:**
1. [태스크 1]
2. [태스크 2]

**주요 화면 플로우:**
[진입점] → [화면 A] → [화면 B] → [완료/결과]

**UT에서 테스트할 태스크:**
- 태스크 1: [구체적 수행 목표]
- 태스크 2: [구체적 수행 목표]

이 내용이 맞나요? 수정하거나 추가할 태스크가 있으면 알려주세요.

사용자 확인 후 → STEP 3으로 이동.

---

STEP 3: 플로우 문서화

확인된 플로우를 앱 폴더 내 docs/user-test/ 에 저장한다.

파일명 규칙: {path}/docs/user-test/{앱폴더명}-flow.md

• 예: apps/coupon-wallet → apps/coupon-wallet/docs/user-test/coupon-wallet-flow.md
• {path}/docs/user-test/ 폴더가 없으면 생성
• 이미 파일이 존재하면 내용을 업데이트

# {앱 이름} 플로우 문서

> 마지막 업데이트: {날짜}

## 앱 개요
[목적 + 핵심 가치 제안]

## 메인 사용자 플로우
[진입] → [화면1] → [화면2] → [완료]

## 화면별 설명
### [화면 이름]
- 목적:
- 주요 액션:
- 다음 화면:

## UT 기준 태스크
| 태스크 | 성공 기준 | 예상 소요 시간 |
|--------|---------|-------------|

---

STEP 4: UT 수행

[simulate 모드] 각 페르소나별 수행

① 스크리닝 체크 페르소나가 이 미니앱을 실제로 사용할 법한지 판단. 적합도 낮으면 "접점이 낮습니다" 명시 후 접근성 관점 분석만 수행.

② 사전 인터뷰 시뮬레이션 페르소나가 이 앱에 처음 접했을 때의 상황, 기대, 선입견을 구체적으로 묘사.

• 어디서, 어떻게 이 앱을 발견했는가
• 앱을 열기 전 어떤 기대를 하고 있는가
• 비슷한 앱 경험이 있는가

③ 태스크 수행 Think Aloud — 핵심 요구사항

페르소나가 실제로 폰을 들고 앱을 쓰는 것처럼, 가감 없는 내면의 목소리를 화면 단위로 서술한다.

작성 원칙:

• 페르소나 특유의 말투, 어휘, 반응 속도를 그대로 살린다
• 긍정적 반응과 부정적 반응을 둘 다 솔직하게 표현한다
• 실제로 헷갈리는 부분에서는 머뭇거림, 잘못된 탭, 잘못된 해석을 구체적으로 묘사한다
• "막혔지만 결국 성공"이 아니라 막히는 순간의 내면을 보여준다
• 페르소나가 아무 생각 없이 넘기는 부분, 오해하는 부분, 기대와 다른 부분을 모두 포함한다
• 이탈 위험이 있으면 "여기서 나갔을 것 같다"고 명시한다

화면별 서술 형식:

[화면명]
(내면의 목소리 — 페르소나 말투 그대로)
"..."
"..."
*(행동 묘사: 탭, 스크롤, 뒤로가기 등)*
→ 결과: 성공 / 헤맴 / 이탈 위험 / 오해

④ 사후 인터뷰 시뮬레이션

진행자가 물어보는 형식으로 구성한다. 페르소나 말투 그대로.

• 진행자: "전체적으로 어떠셨어요?"
• 진행자: "가장 헷갈렸던 순간이 언제였어요?"
• 진행자: "기대한 것과 달랐던 게 있었나요?"
• 진행자: "다음에 또 쓰실 것 같아요?"

⑤ SUS 점수 산정

예상 점수 + 등급 (A: 85+, B: 72+, C: 52+, D: 51 이하) 항목별 감점 근거를 구체적으로 서술.

⑥ 이슈 목록 (심각도 분류)

[심각도 4 - 치명적] 태스크 실패를 유발
[심각도 3 - 중요] 높은 불편감, 이탈 위험
[심각도 2 - 경미] 사소한 혼란, 재시도 필요
[심각도 1 - 미용적] UX 개선 권장

각 이슈는 "어떤 화면에서, 어떤 상황에, 어떤 반응이 나왔는가"를 구체적으로 서술.

---

[simulate 모드] 종합 섹션

페르소나별 요약 매트릭스

페르소나	SUS	태스크 완료율	주요 이슈	이탈 위험

공통 발견 — 여러 페르소나가 공통으로 겪은 문제 (심각도 자동 UP)

세그먼트별 차별 발견 — 특정 페르소나만 경험하는 문제

우선순위 액션 아이템

우선순위	이슈	심각도	관련 페르소나	권장 수정 방향

---

[session 모드] 인터랙티브 진행

1. [AI] 선택된 페르소나 소개 + 사전 인터뷰 시작
2. [User] 화면 설명 or 다음 단계 안내
3. [AI] 페르소나로서 Think Aloud 발화
4. [User] 다음 화면/단계 안내
5. ... 반복 ...
6. [AI] 태스크 완료 후 사후 인터뷰 진행
7. [AI] 세션 종료 후 인사이트 요약

인터랙티브 규칙:

• 페르소나 말투를 일관되게 유지
• 막혔을 때 힌트 절대 금지
• 오조작·혼란·이탈 시도를 그대로 표현
• 페르소나 내면의 솔직한 반응을 검열 없이 발화

---

STEP 5: UT 리포트 저장 [simulate 모드]

저장 경로: {path}/docs/user-test/{YYYY-MM-DD}-user-test-report.md

• {path}/docs/user-test/ 폴더가 없으면 생성
• 같은 날짜에 여러 번 실행하면 기존 파일에 새 섹션 추가

# UT 리포트 — {앱 이름}

> 날짜: {날짜} | 페르소나: {사용된 페르소나}

## 요약
| 페르소나 | SUS | 완료율 | 이슈 수 |
|---------|-----|--------|--------|

## 페르소나별 상세 결과

### {페르소나 이름}

**사전 인터뷰**
[발견 경로, 기대, 선입견]

**Think Aloud**

[화면명]
> "..." (내면의 목소리 — 페르소나 말투)
*(행동 묘사)*
→ 결과

[화면명]
...

**사후 인터뷰**
진행자: "..."
{페르소나}: "..."
...

**SUS**: {점수} / {등급}
[항목별 감점 근거]

**이슈**
- [심각도 N] ...

---

## 공통 발견

## 우선순위 액션 아이템
| 우선순위 | 이슈 | 심각도 | 관련 페르소나 | 권장 수정 방향 |
|--------|------|--------|------------|------------|

---

중요 규칙

1. 가감 없는 발화: Think Aloud는 "정제된 요약"이 아닌 페르소나의 날것 반응으로 작성. 긍정·부정·혼란·오해 모두 포함.
2. 화면 단위 서술: 각 화면마다 페르소나가 무엇을 보고, 무엇을 생각하고, 무엇을 탭했는지 구체적으로.
3. 데이터 기반: 페르소나 반응은 실제 토스 사용자 데이터 기반으로 현실적으로 작성.
4. 과장 금지: 실제 발생 가능한 페인포인트만 언급.
5. 한국어: 모든 발화·리포트는 한국어로 작성.
6. 액션 가능성: 이슈는 개발팀이 수정 가능한 형태로 구체적으로 작성.
7. 사용자 확인 필수: STEP 2에서 반드시 확인 후 진행.

---

종료

리포트 저장이 끝나면 짧은 완료 보고 한 번만 출력하고 세션을 마무리한다.

형식:

✅ UT 리포트 저장: <파일 경로>
페르소나: <이름 리스트> · 주요 이슈 <개수>건

규칙: 완료 보고 1회 후 종료.