qa

name	qa
description	기능별 QA 체크리스트 생성, 수동 테스트 실행, 결과 기록. Use when QA 테스트, 체크리스트 만들기, 수동 검증, 기능 확인, qa 진행, checklist. Do NOT use for automated test code (use plan-review tdd / code-review instead) or BDD spec (use plan-review bdd instead).
argument-hint	[create|run|list] [feature-name]

QA

기능별 수동 QA 체크리스트를 생성하고, 사용자와 함께 항목별로 실행하며, 결과를 기록하는 living spec 관리 도구.

핵심 철학:

• QA = Living Spec: 체크리스트는 기능의 expected behavior 명세이자 회귀 테스트 기준
• Human-in-the-loop: 사람이 직접 확인하는 수동 테스트 — Claude는 항목 제시/기록 담당
• Project-local: .claude/qa/{feature}.md에 저장, 프로젝트와 함께 관리
• 재실행 가능: 체크박스 초기화 후 언제든 재검증 가능

자동화 테스트의 품질 기준은 본 스킬이 아닌 /principles (FIRST, TEST-BEHAVIOR, TEST-PYRAMID, DAMP, TEST-SMELLS, BEYONCE-RULE)에서 관리한다.

Instructions

워크플로우 1: QA 체크리스트 생성

$ARGUMENTS에 "create" 또는 "만들어", "리스트", "목록" 포함 시, 또는 구현 완료 후 QA 요청 시.

1. 구현 분석

   • git diff/log로 변경사항 파악
   • 관련 플랜 파일 확인 (.claude/plans/)
   • 코드에서 사용자 영향 기능 추출 (API 엔드포인트, UI 변경, 상태 변화)
   • 테스트 유형 감지:
     • API: curl/httpie 명령, 인증 토큰 준비
     • 모바일: 디바이스/시뮬레이터, push 토큰, 딥링크 스킴, adb 명령
     • 웹 UI: 브라우저, Network 탭 확인, 계정 상태

2. 체크리스트 초안 작성

   • 템플릿: templates/checklist.md Read 후 적용
   • 섹션은 알파벳 순서 (A, B, C...), 항목은 번호 (A1, A2...)
   • 카테고리 구성:
     • 사전 준비: 테스트 환경, 계정, 데이터
     • 핵심 기능: 구현한 기능의 happy path
     • 엣지 케이스: 경계값, 에러, 권한
     • 회귀 확인: 기존 기능 영향 없음 확인

3. 사용자 확인

   • 초안을 보여주고 피드백 반영
   • 항목 추가/삭제/수정

4. 파일 저장

   • 경로: .claude/qa/{feature-name}.md
   • 기존 QA 디렉토리 없으면 생성
   • 날짜 포함 필요 시: .claude/qa/{feature}-{YYYY-MM-DD}.md

워크플로우 2: QA 실행

$ARGUMENTS에 "run" 또는 "진행", "실행", "하나 줘" 포함 시, 또는 기존 QA 파일 기반 테스트 요청 시.

1. QA 문서 로드

   • .claude/qa/ 에서 대상 파일 확인
   • 파일 없으면 → "어떤 기능을 테스트하시겠어요?" 질문 → 워크플로우 1로
   • 여러 파일이면 목록 제시 후 선택

2. 미완료 항목 탐색

   • - [ ] 항목 중 첫 번째 미체크 항목 찾기
   • 모두 완료면 → "전체 완료" 보고 + 워크플로우 3 제안
   • 사용자가 ID 지정 시 (예: "B3부터") → 해당 항목으로 점프
   • 섹션 단위 스킵 가능 (예: "C 섹션 넘어가")

3. 항목 제시

   • 한 번에 하나씩 제시 (사용자가 집중할 수 있도록)
   • 형식:

     **{ID}. {테스트 내용}**
     기대 결과: {expected}
     준비: {필요한 조작/명령} (있으면)
     

   • 필요 시 테스트 데이터 준비 지원 (DB 쿼리, curl, adb 명령 등)

4. 결과 기록

   • 사용자 응답에 따라 체크리스트 업데이트:
     • 성공: - [x] {ID}. ... ✅ {메모}
     • 실패: - [x] {ID}. ... ❌ {증상}
     • 스킵: - [ ] {ID}. ... (그대로 유지)
   • 파일에 즉시 반영 (Edit)
   • 실패 시 재검증 사이클:
     • 원인 조사 → 코드 수정 → 커밋
     • 실패 항목을 - [ ]로 리셋하여 재검증 대상으로 복원
     • 회귀 가능성 있으면 관련 항목도 리셋 제안

5. 반복

   • 다음 미완료 항목 자동 제시
   • 사용자가 "넘어가" / "다음" 하면 스킵
   • "중단" / "여기까지" 하면 현재 진행률 보고 후 종료

워크플로우 3: QA 관리

$ARGUMENTS에 "list" 또는 "목록", "상태", "문서" 포함 시.

1. QA 문서 목록

   • .claude/qa/ 디렉토리에서 *.md 파일 탐색
   • 파일별 진행률 표시: {filename} — {완료}/{전체} ({%}) | ❌ {실패} failed

2. 선택적 작업

   • 초기화: 체크박스 전부 [ ]로 리셋 (재검증용)
   • 아카이브: 완료된 QA를 .claude/qa/archive/로 이동
   • Obsidian 기록: QA 완료 시 projects/{name}/qa/{feature}.md로 결과 기록 제안 (형식은 obsidian-write 참조)

중요 원칙

1. 한 번에 하나: QA 항목은 반드시 하나씩 제시. 목록 전체를 던지지 않는다
2. 실제 동작 기록: "성공" 뿐 아니라 실제 관찰된 동작을 메모 (예: ✅ "loved your match!" 메시지 확인)
3. 테스트 데이터 지원: QA 실행 중 필요한 데이터를 능동적으로 준비 (DB insert, API 호출 등)
4. 실패 즉시 대응: 실패 항목 발견 시 원인 조사 → 수정 → 재검증 사이클 제안
5. Living Spec: QA 문서는 일회성이 아닌 기능 명세 — 코드 변경 시 QA 문서도 갱신

Examples

구현 후 QA 생성

User: "이거 테스트할건데, qa 리스트 만들어줘" → WF1: git diff 분석 → 체크리스트 초안 → 사용자 확인 → .claude/qa/{feature}.md 저장

QA 실행

User: "qa 진행하자" / "체크리스트 하나 줘" → WF2: 미완료 항목 찾기 → 항목 제시 → 사용자 확인 → 결과 기록 → 다음 항목

QA 현황 확인

User: "qa 문서 체크좀" → WF3: .claude/qa/ 목록 + 진행률 표시 → 선택적 작업