frogger: Instructions file for Claude Code

Project: Prova

AI 기반 알고리즘 시각화 디버거. 브라우저에서 코드를 실행하고, AI가 실행 흐름을 시각화 + 자연어 해설로 변환한다. 핵심 철학: 역할 분리 — 실행의 정확성은 엔진이, 해석과 설명은 AI가, 디자인은 프론트엔드가 전담.

Tech Stack

• Framework: Next.js (App Router), React, Tailwind CSS
• State: Zustand (단일 스토어)
• Visualization: D3, Three.js
• Execution: Pyodide (Python WASM), Acorn (JS AST 계측), Web Worker, Java 원격 실행 서버
• AI: Gemini/OpenAI/Groq/Anthropic/OpenRouter (멀티 프로바이더 폴백)

Directory Structure

app/
├── api/analyze/     # AI: 알고리즘 분류 + 전략 결정
├── api/java/execute/ # Java 원격 실행 프록시
├── page.tsx         # 메인 페이지
src/
├── config/          # 실행 제한 설정 (timeout, maxSteps)
├── features/
│   ├── execution/   # Worker 라이프사이클 (ProvaRuntime)
│   ├── trace/       # rawTrace + AI 어노테이션 → mergedTrace 병합
│   ├── playback/    # 재생/탐색 컨트롤
│   └── visualization/  # GridLinearPanel, GraphPanel, 3D Volume
├── lib/             # AI 프로바이더, 태그 정규화, 피벗 보강
├── store/           # Zustand 스토어 (useProvaStore)
├── types/           # 파이프라인 전체 타입 (prova.ts)
public/worker/       # pyodide.worker.js, js.worker.js
docs/                # 개발자 아키텍처 문서
prompts/             # AI에게 던질 프롬프트 모음 (UI, pitch, 언어 확장)

3-Step Pipeline

1. TRACE — Worker(Pyodide/JS) 또는 원격 JVM(Java)이 코드 실행 + trace 수집 → {rawTrace, branchLines, varTypes}
2. AI — /api/analyze(알고리즘 분류·전략·변수 매핑·enrichment)
3. RENDER — mergedTrace[currentStep] 기준으로 시각화 패널 렌더링

AI Integration Rules

• AI 분류 규칙: 역할은 타입/이름이 아닌 사용 패턴으로만 결정 (상세: app/api/analyze/CLAUDE.md)
• var_mapping[].var_name은 반드시 실제 varTypes 키여야 함
• aiError 키 이름 고정 (error, analysisError 등 사용 금지)
• AI는 action 이름 + params만 반환, 색상/스타일 절대 포함 금지

Custom Commands

• /qa — feature별 QA 체크리스트 생성/업데이트
• /test — feature별 테스트 작성 + 커밋
• /review — feature + test 코드 품질 검사 + 커밋
• /docs — 아키텍처 문서 + JSDoc + 인라인 주석 업데이트
• /trace-validate — trace 스키마 + 병합 무결성 검증
• /prompt-diff — AI 프롬프트 변경 회귀 체크
• /refactor-audit — export 타입/시그니처 호환성 검증
• /pr-ready — lint + type check + build + 변경 요약