qa

Prompt file imported from ultra-ai-dle/frogger (.claude/commands/qa.md). Fill in {{arguments}} before use. Copyright stays with the author.

/qa — Feature별 QA 체크리스트 생성/업데이트

목적

현재 코드 기반으로 사용자 관점의 QA 체크리스트를 생성하거나 업데이트한다.

입력

• {{arguments}} — (선택) 대상 feature 이름 (예: execution, visualization, ai-pipeline, trace, playback)
  • 생략 시: git diff main...HEAD --name-only로 변경된 feature를 자동 감지한다.
  • 변경된 feature가 없으면 전체 feature를 대상으로 한다.

실행 절차

1. 대상 feature 결정:

   • {{arguments}}가 있으면 해당 feature만 대상으로 한다.
   • 없으면 git diff main...HEAD --name-only에서 src/features/ 하위 변경을 감지한다.
   • feature 이름 → 디렉토리 매핑:
     • execution → src/features/execution/
     • trace → src/features/trace/
     • visualization → src/features/visualization/
     • playback → src/features/playback/
     • ai-pipeline → app/api/analyze/

2. 컨텍스트 수집 (feature별로):

   • 해당 feature의 소스 코드를 읽는다.
   • CLAUDE.md (해당 디렉토리)를 읽는다.
   • docs/features/{feature}.md 아키텍처 문서를 읽는다.
   • docs/qa-questions.tsv에서 관련 QA 원칙을 참고한다.

3. QA 시나리오 도출:

   • 다음 4가지 카테고리로 분류한다:
     • 정상 동작 — golden path. 사용자가 기대하는 기본 흐름.
     • 엣지 케이스 — 빈 입력, 최대값, 경계값, 특수 문자 등.
     • 에러 케이스 — 네트워크 실패, AI 실패, Worker 크래시, 타임아웃 등.
     • UI 상태 — 로딩/완료/에러 전환, 비활성화 상태, 반응형 등.
   • 각 항목은 "~하면 → ~된다" 형식의 자연어 문장으로 작성한다.
   • 항목 앞에 볼드로 행동 이름을 붙인다 (예: **Python 실행**, **빈 코드 제출**).
   • 사용자가 브라우저에서 눈으로 확인할 수 있는 UI 반응을 기술한다.
   • 내부 구현 용어(rawTrace, onDone, mergeTrace 등)를 쓰지 않는다.
   • 코드에서 실제 처리하는 분기/에러 핸들링을 기반으로 도출한다.

4. 문서 작성/업데이트:

   • 출력 위치: docs/qa/{feature}.md
   • 파일이 없으면 새로 생성한다.
   • 파일이 있으면:
     • 기존 체크 상태(- [x])는 유지한다.
     • 코드 변경으로 새로 추가된 시나리오만 추가한다.
     • 코드에서 제거된 기능의 항목은 ~~취소선~~으로 표시하되 삭제하지 않는다.
   • 문서 상단에 메타 정보를 포함한다:

     # QA: {Feature 이름}
     
     > 마지막 업데이트: {오늘 날짜}
     > 대상 파일: {소스 파일 경로들}

5. 결과 보고:

   ✅ QA 체크리스트 업데이트 완료
   - {feature}: {총 항목 수}개 ({새로 추가된 수}개 추가)
   

출력 형식 예시

# QA: Execution Engine

> 마지막 업데이트: 2026-04-11
> 대상 파일: src/features/execution/runtime.ts

## 정상 동작
- [ ] **Python 실행** — Python 코드를 입력하고 실행하면 → 하단 패널이 Visualization 탭으로 자동 전환되고 스텝 슬라이더가 활성화된다
- [ ] **JS 실행** — JavaScript 코드를 입력하고 실행하면 → Python과 동일하게 시각화 패널이 전환되고 스텝 탐색이 가능하다
- [ ] **stdin 입력** — stdin이 필요한 코드를 실행하면 → stdin 입력 영역에 값을 넣은 뒤 정상 실행된다
- [ ] **재실행** — 실행 완료 후 코드를 수정하고 다시 실행하면 → 이전 시각화가 초기화되고 슬라이더가 0으로 리셋된다

## 엣지 케이스
- [ ] **빈 코드 제출** — 코드 없이 실행 버튼을 누르면 → "코드를 입력한 후 디버깅을 시작하세요" 메시지가 표시되고 실행되지 않는다
- [ ] **대량 스텝** — 10,000 step을 초과하는 코드를 실행하면 → step limit 경고가 표시되고 수집이 중단된다
- [ ] **stdin 미입력 (Python)** — Python 코드에서 stdin을 비워두고 실행하면 → "예시 입력을 입력하세요" 안내가 표시된다

## 에러 케이스
- [ ] **문법 에러** — 문법 에러가 있는 코드를 실행하면 → 에디터 해당 라인에 에러 표시가 나타나고 하단에 에러 메시지가 출력된다
- [ ] **무한루프** — 무한루프 코드를 실행하면 → 120초 후 "실행 시간 초과" 메시지가 표시되고 재실행 버튼이 활성화된다
- [ ] **Worker 크래시** — Worker가 예기치 않게 종료되면 → 에러 메시지가 표시되고 재실행이 가능하다

## UI 상태
- [ ] **실행 중 표시** — 코드 실행이 시작되면 → 로딩 인디케이터가 표시되고 실행 버튼이 비활성화된다
- [ ] **타임아웃 복귀** — 타임아웃이 발생하면 → 에러 메시지 표시 후 실행 버튼이 다시 활성화된다

주의사항

• QA 항목은 유닛 테스트가 아니라 사용자 관점의 수동 검증 시나리오다.
• 코드 내부 구현이 아닌, 사용자가 브라우저에서 확인할 수 있는 동작을 기술한다.
• 기존 docs/qa-questions.tsv의 QA 원칙(스크롤 금지, 데스크탑 전용 등)을 반영한다.
• 이 커맨드는 코드를 수정하지 않는다. QA 문서만 생성/업데이트한다.