qa

# 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/`로 이동
   - **Logseq 기록**: QA 완료 시 `know/pj-{name}___qa___{feature}.md`로 결과 기록 제안

## 중요 원칙

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/` 목록 + 진행률 표시 → 선택적 작업