> ## Content Index
> Fetch the complete content index at: https://zerodraftlab.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# AI 사용성 테스트, 클릭 기록이 없으면 통과를 못 준다: ux-audit 스킬 판정 기준
- URL: https://zerodraftlab.com/ai-usability-test-ux-audit/
- Published: 2026-11-05T00:00:00.000Z
- Updated: 2026-11-05T00:00:00.000Z
- Description: jezweb/claude-skills의 ux-audit 스킬은 에이전트가 실제로 입력하고 누른 기록이 없으면 판정을 '미완료'로 막는다. SKILL.md 본문을 원문 순서대로 설명하고 기준값의 한계를 짚는다.
- Author: JooMong
- Tags: 무료

AI 에이전트에게 "앱 한번 훑어보고 문제 있으면 알려 줘"라고 시키면, 페이지 몇 개를 열어 본 뒤 "특별한 문제는 보이지 않는다"는 답이 돌아오기 쉽다. jezweb/claude-skills 저장소의 ux-audit 스킬은 이런 답을 판정으로 인정하지 않는다. 에이전트가 실제로 입력하고, 누르고, 결과를 지켜본 기록을 내지 못하면 결론은 "미완료" 하나뿐이다.

원문은 아래 SKILL.md 파일이다. 이 글은 2026년 9월 28일 main 브랜치의 내용을 원문 순서대로 설명한다.

[jezweb/claude-skills — ux-audit/SKILL.md](https://github.com/jezweb/claude-skills/blob/main/plugins/dev-tools/skills/ux-audit/SKILL.md?ref=zerodraftlab.com)

이 스킬은 저장소의 dev-tools 플러그인에 들어 있고 MIT 라이선스다. 메타데이터에 `claude-code-only`라고 적혀 있어 Claude Code 전용이다. 본문은 473줄이고 참고 문서 23개가 딸려 있다. 9월 28일 조회 기준으로 저장소 스타는 1,033개, skills.sh 설치 수는 약 2,700회다. 이 글은 본문을 다루며, 참고 문서 23개를 모두 읽지는 않았다.

## 판정은 네 가지, 기록이 없으면 하나

감사는 다음 넷 중 하나로 끝난다.

- **Pass**: Critical·High 발견 0건, 하드 게이트 전부 통과, 상호작용 기록(Interaction Manifest) 완비.
- **Conditional Pass**: 조건은 Pass와 같고 Medium·Low 발견만 남은 상태.
- **Fail**: Critical이나 High가 하나라도 있거나, 하드 게이트 하나가 깨진 상태.
- **Incomplete**: 기록에 필수 항목이 빠졌거나, 단계를 건너뛰었거나, "감사의 감사" 검사에 걸린 상태.

원문은 "It looked OK" is not Pass라고 못 박는다. 상호작용 기록이 없으면 가능한 판정은 Incomplete뿐이다. 기록이 있어도 시간이 비현실적이면 받아 주지 않는다. 예를 들어 기록 항목 사이 간격의 중앙값이 0.5초 미만이면, 실제로 조작하지 않고 한꺼번에 찍어 낸 것으로 보고 감사를 다시 하게 한다.

![상호작용 기록 완비 여부, Critical·High나 하드 게이트 위반 여부, Medium·Low 발견 여부에 따라 Incomplete, Fail, Conditional Pass, Pass로 갈리는 판정 흐름도](https://storage.ghost.io/c/da/13/da13bbbc-4992-4354-bf2c-1426bcf8788c/content/images/2026/11/agent-ux-audit-walkthrough.png)

## 하드 게이트: 낮춰 줄 수 없는 숫자

아래 조건 중 하나라도 걸리면 감사는 자동으로 떨어진다. 심각도를 낮춰 줄 수도 없다.

| 조건                             | 기준       | 위반 시 심각도        |
| ------------------------------ | -------- | --------------- |
| 걷는 동안 콘솔 에러                    | 1건 이상    | Critical        |
| 걷는 동안 콘솔 경고                    | 1건 이상    | High            |
| 네트워크 5xx                       | 1건 이상    | Critical        |
| 로그인한 페이지의 403·404              | 1건 이상    | High            |
| 시험한 화면 폭·패널 조합에서 레이아웃 붕괴       | 1건 이상    | High            |
| axe-core Critical / Serious 위반 | 1건 이상    | Critical / High |
| 대표 경로의 LCP                     | 4.0초 초과  | High            |
| 대표 경로의 CLS                     | 0.25 초과  | High            |
| 대표 경로의 INP                     | 500ms 초과 | High            |

콘솔 경고가 High라는 점이 눈에 띈다. 원문은 "Medium 콘솔 에러"라는 분류가 이 스킬에 없다고 적는다. 대신 Sentry 정보 로그, 브라우저 확장이 내는 메시지, 로그인 확인용 요청의 예상된 401처럼 버그가 아닌 잡음은 프로젝트 설정 파일(`audit-config.yml` 등)의 허용 목록에 올려 발견 목록에서 뺄 수 있다. 뺀 항목도 기록에는 남고, 판정 블록에는 "경고 3건(허용 1, 보고 2)"처럼 두 숫자를 함께 적는다.

성능은 대표 경로 한 곳에서만 잰다. 원문은 이 기준을 "망가진 수준보다 한참 위, Google Core Web Vitals의 Good 기준보다 한참 아래"에 둔 실용 기준이라고 설명한다. 랜딩 페이지가 아니라 사용자가 오래 머무는 앱 내부 화면에 맞춘 선이다.

## 일곱 단계

1. 사전 점검(Pre-flight): 페르소나, 브라우저 도구, URL, 화면 크기, 도구 작동 확인
2. 탐색(Discovery): 사이트맵, 업무 흐름 목록, 요소 목록
3. 동선 걷기(Walkthrough): 상호작용 기록, 흐름 따라가기, 요소 전수 조작, 다중 패널 스트레스, 첫 사용자 관점
4. 다듬기(Polish): 시각 세부, 컴포넌트 점검, 접근성, 성능
5. 스트레스(Stress): 시나리오 11개와 추가 스트레스 레시피
6. 판정(Verdict): 판정 블록, 상위 5개, 재현 단계가 붙은 발견 목록
7. 고치고 재확인(Fix-and-verify)

## 1단계: 누구의 눈으로 볼지 먼저 잠근다

감사는 페르소나부터 정한다. 원문 설명으로는 페르소나가 없으면 발견 사항이 "괜찮아 보인다" 쪽으로 흐른다. 사용자가 인자로 준 페르소나("바쁜 보험 설계사로서 감사해 줘")가 1순위다. 없으면 프로젝트의 페르소나 파일을 찾고, 그것도 없으면 "누가 무엇을 하려고 이 앱을 쓰나요?"라고 한 번 묻는다. 역할, 기술 숙련도, 시간 압박, 감정 상태, 사용 기기를 적는다. 좋은 페르소나는 그 사람이 무엇을 놓칠지 예측하게 해 준다. 원문의 예는 "전화 사이사이에 일하는 접수 직원은 화면 아래로 스크롤하지 않는다"이다.

브라우저 도구는 대상에 따라 고른다. 로그인이 필요한 앱은 사용자의 실제 Chrome 세션을 쓰는 Chrome MCP로, 공개 사이트는 Playwright MCP로 본다. 로그인이 필요한데 Chrome MCP가 연결돼 있지 않으면 새 Playwright 세션으로 조용히 넘어가지 말고 멈추라고 적혀 있다. 로그인을 못 하면 감사가 의미 없기 때문이다.

URL은 배포된 실제 버전을 우선한다. 실제 인증, 지연, CDN, CORS를 거쳐야 하기 때문이다. 로컬 개발 서버는 사용자가 요청했거나 기능이 아직 배포되지 않았을 때만 쓴다. 창은 1440×900에서 시작하고 2000px를 넘기지 않는다. 걷기 전에는 스크린샷, 콘솔 읽기, 네트워크 요청 목록, 요소 선택자 조회를 한 번씩 해서 도구가 작동하는지 증명한다. 콘솔을 못 보는 감사는 쓸모없다는 것이 원문의 입장이다.

## 2단계: 경로 지도와 하루 업무 흐름부터 만든다

페이지를 하나라도 감사하기 전에 전체 페이지 목록을 만든다. 앱의 라우터 설정을 읽고, 사이드바와 메뉴를 전부 눌러 보고, 문서에 적힌 딥링크를 모은다. 결과는 경로 하나당 한 줄로, 그 화면의 목적을 붙여 적는다. 원문 예시는 `/app/clients — list of clients, search, add new`다.

그다음 사용자의 하루를 이루는 실제 업무 3\~5개를 고른다. 원문은 이것을 스레드(thread)라 부르고 감사의 "척추"라고 설명한다. 보험 설계사라면 계약 갱신, 고객 등록, 오늘 할 일 처리다. 요소 목록은 페이지에 도착할 때마다 그 페이지의 조작 가능한 요소를 적는 식으로 만든다. 이 목록이 "31개 중 29개 테스트" 같은 커버리지 수치의 분모가 된다.

## 3단계: 걸으면서 전부 기록한다

이 단계가 감사의 본체다. 모든 조작은 시각, 선택자와 함께 상호작용 기록에 남는다. 원문 예시의 일부는 다음과 같다.

> \[✓\] 14:32:01 Typed "@assistant test" into message input  
> \[✓\] 14:32:05 Clicked Send (button\[aria-label="Send"\])  
> \[✓\] 14:32:06 Verified input cleared within 1000ms

감사한 페이지마다 최소한 다음 기록이 있어야 한다. 입력창 하나에 실제 글자 입력, 주요 행동(보내기·저장·제출·생성·게시 중 맞는 것) 하나 실행, 모달이나 상세 패널 하나 열기, 주요 행동 뒤 콘솔 읽기, 주요 행동 전후 스크린샷, 그리고 행동 뒤 기대한 상태가 됐는지 확인하는 것이다. 입력창이 비었는지, 성공 알림이 떴는지, 목록이 갱신됐는지를 본다.

스레드는 앱의 입구에서 시작한다. 실제 사용자는 흐름 중간이 아니라 `/`나 `/dashboard`에 도착하기 때문이다. 페르소나가 대충 훑을 사람이면 에이전트도 훑고, 라벨을 잘못 읽을 사람이면 잘못 읽는다. 상태가 바뀔 때마다 스크린샷을 찍고 비용을 센다. 클릭 수, 결정 지점, 막다른 길, 중단 후 복귀가 그 비용이다. 중단 후 복귀는 3단계에서 탭을 닫았다가 4단계에서 돌아왔을 때 상태가 남아 있는지 보는 것이다. 스레드가 끝나면 페르소나 입장에서 세 질문에 답한다. 끝이 분명했나? 다시 올까? 두 배 쉽게 만들 한 가지는 무엇인가?

이 밖에 원문이 필수로 두는 항목은 다음과 같다.

- **요소 전수 조작**: 스레드에서 누르지 않은 요소를 마저 누른다. 목록과 표는 데이터가 허락하면 0건, 1건, 100건, 1,000건 이상으로 시험한다.
- **다중 패널 스트레스**: 사이드바·스레드·서랍이 있는 앱은 1920px부터 375px까지 여섯 가지 폭과 패널 조합을 모두 돌린다. 원문은 1280px를 버그가 많은 폭, 1024px를 치명적 버그가 나는 폭으로 표시한다. 세 패널을 모두 연 1024\~1280px에서만 글자가 세로로 쌓이던 실제 버그(2026년 4월 29일)를 예로 든다.
- **첫 사용자 관점**: 정한 페르소나와 별개로, 이 앱에 처음 로그인한 사람의 눈으로 여러 페이지에 걸친 기능을 모두 다시 본다. 코드나 문서 없이 과업을 끝낼 수 있는지, 라벨에 `agentClass`나 `slug` 같은 내부 용어가 새어 나오지 않는지, 드롭다운이 ID 대신 각 선택지가 하는 일을 보여 주는지 묻는다. 원문은 이것을 AI 도구와 사내 도구의 가장 큰 맹점이라고 부른다.
- **실제 클릭 확인**: 코드를 읽으면 버튼에 `onClick`이 있는지는 알 수 있지만, 눌렀을 때 무언가 일어나는지는 모른다. 누르고, 네트워크 탭에 요청이 나갔는지 보고, 화면이 바뀌었는지 본다. 둘 다 변화가 없으면 버그다.
- **왕복 확인**: A에서 B로 가서 무언가를 바꾸고 A로 돌아왔을 때, 새로고침 없이 A에 바뀐 상태가 보여야 한다.
- **세션 만료**: 감사 중 로그인이 풀리면 몰래 다시 로그인하지 않는다. 그 뒤의 관찰이 모두 오염되기 때문이다. 멈추고, 끊긴 지점을 발견 사항으로 남기고, Incomplete로 끝낸다.

## 4·5단계: 다듬기와 스트레스

다듬기 단계에서는 페이지마다 시각 세부를 본다. 원문은 광학적 중심 맞추기, 어긋난 간격, 애매한 회색, 테두리 두께 흔들림, 그림자 방향 등 열 가지를 "AI 티(AI-tell)" 범주로 묶었다. 컴포넌트는 버튼, 입력·폼, 내비게이션, 시각 일관성, 모바일·터치(누를 수 있는 면 48×48 이상), 성능·피드백의 여섯 범주로 확인한다. 주요 컴포넌트마다 기본, 스켈레톤, 빈 상태, 부분, 에러, 비활성의 여섯 상태를 본다. 체크 항목마다 스크린샷이나 콘솔 줄 같은 증거가 붙어야 한다.

접근성은 모든 페이지에 axe-core를 주입해 돌린다. 원문은 키보드만으로 걷는 수동 검사가 구조적 접근성 버그의 약 80%를 놓치고, axe-core가 그 부분을 페이지당 1초 안에 잡는다고 설명한다.

스트레스 단계의 시나리오 11개는 항상 전부 돈다. 처음 보는 사람으로 앱 파악하기, 작업 중 탭 닫기와 새로고침, 일부러 잘못 누른 뒤 복귀하는 데 몇 번 걸리는지, 재방문, 키보드만 쓰기, 500건 이상의 데이터, 삭제·발송·결제처럼 되돌리기 어려운 행동의 확인 문구, 권한이 적은 역할, 첫 가입자와 첫 초대자와 나중 합류자가 보는 서로 다른 화면, 왕복 흐름, 0·1·7·30일치 시간 분포 데이터다.

추가 레시피로는 더블클릭 경쟁, 3G 속도, 동작 줄이기 설정, 긴 독일어·아랍어·한중일 문자, 오프라인, 인쇄, 고대비 모드를 시험한다. 폼이 있는 앱이라면 "실제 맛 데이터(real-flavour data)" 검사가 필수다. 아포스트로피나 악센트가 조용히 지워지는지, 긴 입력이 경고 없이 잘리는지, .heic 사진이나 50MB PDF 업로드가 어떻게 처리되는지 본다. 원문은 AI가 만든 UI가 개발용 데이터로만 깨끗하게 작동하기로 악명 높다고 적는다.

## 6단계: 판정 보고서의 형식

보고서 맨 위에는 판정 블록이 온다. 판정, 페르소나, 감사한 경로 수, 기록 완비 여부, 하드 게이트 수치, 성능 수치, 심각도별 발견 수, 단계별 소요 시간, 그리고 영향과 고치기 쉬운 정도를 함께 따져 고른 상위 5개가 들어간다.

발견 목록을 내기 전에 새 서브에이전트를 띄워 항목마다 KEEP, GENERIC, DUPLICATE를 매긴다. 이 앱과 이 페르소나와 이 화면에만 해당하면 KEEP, 아무 웹앱에나 해당하면 GENERIC, 다른 항목과 원인이 같으면 DUPLICATE다. GENERIC과 DUPLICATE는 버린다. 처음 쓴 에이전트는 자기 결과물을 방어하기 쉬워서 새 에이전트에게 맡긴다는 설명이다.

발견 하나에는 ID, 층위, 심각도, 화면(경로·폭·패널), 페르소나, 번호 붙은 재현 단계, 관찰한 것, 기대한 것, 증거, 의심되는 코드 위치(`file:line`), 가장 작은 패치가 모두 들어가야 한다. "Consider X", "Improve Y" 같은 제안형 문장은 허용하지 않는다. 바로 커밋할 수 있는 구체적 수정이어야 한다. 이 형식을 어기거나, 3단계가 1분도 안 걸렸거나, 스크린샷이 경로 수의 두 배보다 적으면 판정이 Incomplete로 뒤집힌다.

보고서의 끝에는 두 가지가 붙는다. 하나는 발견을 24\~48시간 안의 빠른 수정, 1\~2주의 구조 수정, 출시 뒤 다듬기로 나눈 로드맵이다. 다른 하나는 "이 앱이 물건이라면 손에 쥐고 싶은가"에 답하는, 형식 없는 문단 하나다. 원문은 이 문단에서만큼은 느낌이 핵심이라고 적는다.

## 7단계와 30초 점검

보고서를 낸 뒤에는 "Critical N건, High M건을 지금 고치고 재확인할까요?"라고 묻는다. 수락하면 파일과 영역별로 묶어 고치고, 앱 전체가 아니라 영향받은 부분만 다시 걷는다. 이때 원래 버그를 드러낸 조작을 새 스크린샷과 함께 반복한다. 결과는 고침, 여전함, 새 문제로 표시한다.

원문은 이 감사가 무겁다고 스스로 인정하고, 변경마다 쓰는 30초 점검을 따로 권한다. 프로젝트의 CLAUDE.md에 규칙으로 넣으라는 것이다.

1. 바뀐 페이지를 연다.
2. 아무 입력창에 입력한다.
3. 주요 행동을 누른다.
4. 다음 상태를 2초 동안 지켜본다.
5. 관련 화면(스레드, 모달, 상세)을 연다.
6. 콘솔을 읽는다.

하나라도 예상과 다르면 그 변경은 끝난 것이 아니다. 원문은 전체 감사를 주 1회 함께 돌리라고 권한다. 회귀를 막는 용도로는 핵심 흐름 10\~15개를 Playwright 테스트로 만들어 배포 때마다 돌리라고 덧붙인다.

## 에이전트가 스스로 할 일과 물어야 할 일

원문은 권한을 세 칸으로 나눈다. 이동, 스크린샷, 페이지 읽기, 레이아웃 검사 스크립트 주입, 가짜 테스트 데이터로 폼 제출, 보고서 파일 작성은 묻지 않고 한다. 삭제, 발송, 게시, 결제는 먼저 묻는다. 외부 사람에게 이메일이나 알림이 가는 일은 멈추고 확인받는다.

감사는 서브에이전트가 아니라 메인 세션이 직접 몰아야 한다. 조작 사이의 상태를 계속 지켜본 세션만 2차 발견을 잡는다는 이유다. 한 번 돈 뒤에는 페르소나, 흐름, 데이터 양, 시작 지점을 바꿔 다시 돌고, 새 발견이 더 나오지 않을 때 멈춘다. 30분 넘게 걸릴 감사라면 15분마다 도는 `/loop` 점검을 곁에 두라고 한다.

## 해석: 작은 팀이 가져갈 것

여기부터는 ZDL의 해석이다. 이 스킬에서 눈여겨볼 곳은 체크리스트의 길이보다 증거 규칙이다. 에이전트가 "봤다"고 말하는 것과 실제로 눌러 본 것을 시각, 선택자, 스크린샷으로 갈라 두었고, 증거가 모자라면 합격 판정 자체를 낼 수 없게 했다. 에이전트에게 QA를 맡겼다가 "문제없어 보입니다"라는 답을 받아 본 사람이라면, 이 스킬이 그 답이 나올 자리를 규칙으로 막아 두었다는 점이 가장 쓸모 있을 것이다.

2단계의 경로 목록과 스레드 목록은 따로 떼어 써도 된다. 루트 URL에서 시작해 경로마다 무엇을 하는 화면인지 적고, 하루 업무 3\~5개를 그 위에 선으로 이으면 사용자 동선 지도가 된다. 전체 감사를 돌리기 전에 이 두 목록만 먼저 뽑아 보는 것도 방법이다.

혼자 또는 작은 팀으로 운영한다면 원문이 권하는 층 나누기가 현실적이다. 변경마다 30초 점검, 핵심 흐름은 자동 테스트, 전체 감사는 가끔이다. 전체 절차는 시나리오 11개, 여섯 가지 화면 폭, 모든 페이지의 axe-core 검사를 요구하므로 한 번 돌리는 데 드는 시간과 토큰이 적지 않다.

## 읽을 때 유의할 것

원문은 배포된 실제 버전을 우선하라고 하면서, 가짜 데이터로 폼을 제출하는 일은 묻지 않고 해도 되는 일로 분류한다. 운영 중인 서비스에 그대로 돌리면 테스트 레코드가 실제 데이터베이스에 쌓일 수 있다. 삭제·발송·결제는 묻게 되어 있지만, 어떤 폼이 외부 알림을 일으키는지는 앱마다 다르다. 스테이징 환경이 있다면 그쪽에서 돌리는 편이 안전하다.

로그인이 필요한 앱은 사용자의 실제 Chrome 세션으로 조작한다. 에이전트가 그 계정의 권한을 그대로 갖는다는 뜻이다. 관리자 계정보다 감사용 계정을 따로 두는 편이 낫다.

LCP 4.0초, CLS 0.25, INP 500ms는 스킬 작성자가 정한 실용 기준이다. [Google의 Core Web Vitals](https://web.dev/articles/vitals?ref=zerodraftlab.com)가 Good으로 보는 기준은 LCP 2.5초, INP 200ms, CLS 0.1 이하이며, 원문도 자기 기준이 이보다 느슨하다고 밝힌다. "수동 키보드 검사가 구조적 접근성 버그의 약 80%를 놓친다"는 수치는 원문의 설명이고 이 글에서 검증하지 않았다. 이 글은 스킬을 실제 앱에 돌려 보지 않았다. 스타 수와 설치 수는 9월 28일 조회 값이다.

skills CLI로 이 스킬 하나만 설치하려면 `npx skills add jezweb/claude-skills -g -a claude-code -s ux-audit --full-depth -y`를 쓴다. `-s`로 스킬 이름을 지정하지 않으면 저장소의 다른 스킬까지 함께 설치될 수 있다.

이 글을 읽고 나면, 에이전트에게 UX 감사를 맡길 때 어떤 기록이 있어야 결과를 믿을 수 있는지 판단할 수 있다.

[이메일로 다음 글 받기](#/portal/signup)