create-ax-project 1.0.0 → 1.0.2

package/template/stages/01-brainstorm/outputs/requirements_analysis.md

@@ -1,222 +0,0 @@
-# 📋 Snake Game - 요구사항 분석
-
-> 생성일: 2026-01-21
-> 스테이지: 01-brainstorm
-> 프로젝트: snake-game
-
----
-
-## 1. 기능적 요구사항 (Functional Requirements)
-
-### FR-01: 게임 시작/종료
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-01-1 | 게임 시작 | 시작 버튼 클릭 또는 스페이스바로 게임 시작 | 필수 |
-| FR-01-2 | 게임 종료 | 충돌 시 게임 오버 화면 표시 | 필수 |
-| FR-01-3 | 재시작 | 게임 오버 후 재시작 버튼 제공 | 필수 |
-| FR-01-4 | 일시정지 | P키 또는 버튼으로 일시정지/재개 | 중요 |
-
-### FR-02: 뱀 조작
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-02-1 | 키보드 조작 | 방향키(↑↓←→)로 이동 방향 변경 | 필수 |
-| FR-02-2 | 터치 조작 | 스와이프 또는 방향 버튼으로 조작 | 중요 |
-| FR-02-3 | 연속 이동 | 뱀은 자동으로 현재 방향으로 이동 | 필수 |
-| FR-02-4 | 반대 방향 제한 | 즉시 반대 방향 이동 불가 (자기 충돌 방지) | 필수 |
-
-### FR-03: 먹이 시스템
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-03-1 | 먹이 생성 | 게임 보드 내 랜덤 위치에 먹이 생성 | 필수 |
-| FR-03-2 | 먹이 획득 | 뱀 머리가 먹이와 충돌 시 획득 | 필수 |
-| FR-03-3 | 성장 | 먹이 획득 시 뱀 길이 +1 | 필수 |
-| FR-03-4 | 새 먹이 | 먹이 획득 후 즉시 새 먹이 생성 | 필수 |
-
-### FR-04: 충돌 감지
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-04-1 | 벽 충돌 | 보드 경계 충돌 시 게임 오버 | 필수 |
-| FR-04-2 | 자기 충돌 | 뱀이 자기 몸과 충돌 시 게임 오버 | 필수 |
-| FR-04-3 | 장애물 충돌 | (선택) 장애물과 충돌 시 게임 오버 | 선택 |
-
-### FR-05: 점수 시스템
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-05-1 | 점수 표시 | 현재 점수 실시간 표시 | 필수 |
-| FR-05-2 | 점수 계산 | 먹이당 10점 (레벨에 따라 보너스) | 필수 |
-| FR-05-3 | 최고 점수 | 최고 점수 저장 및 표시 | 중요 |
-| FR-05-4 | 점수 저장 | localStorage에 하이스코어 저장 | 중요 |
-
-### FR-06: 레벨 시스템
-| ID | 요구사항 | 상세 | 우선순위 |
-|----|---------|------|---------|
-| FR-06-1 | 레벨 표시 | 현재 레벨 표시 | 중요 |
-| FR-06-2 | 레벨업 조건 | 50점마다 레벨 증가 | 중요 |
-| FR-06-3 | 속도 증가 | 레벨당 10% 속도 증가 | 중요 |
-| FR-06-4 | 최대 레벨 | 레벨 10 이후 속도 고정 | 중요 |
-
----
-
-## 2. 비기능적 요구사항 (Non-Functional Requirements)
-
-### NFR-01: 성능
-| ID | 요구사항 | 목표 | 측정 방법 |
-|----|---------|------|----------|
-| NFR-01-1 | 프레임레이트 | 60fps 유지 | Chrome DevTools |
-| NFR-01-2 | 초기 로딩 | 2초 이내 | Lighthouse |
-| NFR-01-3 | 입력 지연 | 16ms 이내 | 수동 테스트 |
-| NFR-01-4 | 번들 크기 | 200KB 이하 | 빌드 분석 |
-
-### NFR-02: 호환성
-| ID | 요구사항 | 대상 | 비고 |
-|----|---------|------|------|
-| NFR-02-1 | 데스크톱 브라우저 | Chrome, Firefox, Safari, Edge 최신 2버전 | |
-| NFR-02-2 | 모바일 브라우저 | iOS Safari, Android Chrome | |
-| NFR-02-3 | 화면 크기 | 320px ~ 1920px | 반응형 |
-
-### NFR-03: 접근성
-| ID | 요구사항 | 상세 |
-|----|---------|------|
-| NFR-03-1 | 키보드 네비게이션 | 모든 UI 키보드로 접근 가능 |
-| NFR-03-2 | 색상 대비 | WCAG AA 기준 충족 |
-| NFR-03-3 | 포커스 표시 | 명확한 포커스 인디케이터 |
-
-### NFR-04: 코드 품질
-| ID | 요구사항 | 기준 |
-|----|---------|------|
-| NFR-04-1 | 타입 안전성 | TypeScript strict 모드 |
-| NFR-04-2 | 린트 | ESLint 규칙 통과 |
-| NFR-04-3 | 테스트 커버리지 | 80% 이상 |
-| NFR-04-4 | 코드 포맷 | Prettier 적용 |
-
----
-
-## 3. 기술적 제약조건
-
-### 필수 기술 스택
-- **프론트엔드**: React 18+
-- **언어**: TypeScript 5+
-- **빌드 도구**: Vite
-- **렌더링**: Canvas API
-
-### 금지 사항
-- 외부 게임 엔진 (Phaser, PixiJS 등) 미사용
-- jQuery 미사용
-- 백엔드 서버 미사용 (정적 배포)
-
-### 권장 사항
-- Custom Hook으로 로직 분리
-- 컴포넌트 단위 테스트 작성
-- CSS Modules 또는 Tailwind CSS
-
----
-
-## 4. 데이터 모델
-
-### 게임 상태 (GameState)
-```typescript
-interface GameState {
-  status: 'idle' | 'playing' | 'paused' | 'gameover';
-  score: number;
-  level: number;
-  highScore: number;
-}
-```
-
-### 뱀 (Snake)
-```typescript
-interface Position {
-  x: number;
-  y: number;
-}
-
-interface Snake {
-  body: Position[];
-  direction: 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
-}
-```
-
-### 먹이 (Food)
-```typescript
-interface Food {
-  position: Position;
-  type: 'normal' | 'bonus';
-}
-```
-
-### 게임 설정 (GameConfig)
-```typescript
-interface GameConfig {
-  boardWidth: number;
-  boardHeight: number;
-  cellSize: number;
-  initialSpeed: number;
-  speedIncrement: number;
-}
-```
-
----
-
-## 5. 사용자 시나리오
-
-### 시나리오 1: 첫 게임 플레이
-1. 사용자가 웹사이트 접속
-2. "Start Game" 버튼 표시됨
-3. 버튼 클릭 또는 스페이스바로 게임 시작
-4. 뱀이 화면 중앙에서 시작
-5. 방향키로 뱀 조작
-6. 먹이를 먹으면 점수 증가
-7. 벽 또는 자기 몸과 충돌하면 게임 오버
-8. "Game Over" 화면과 최종 점수 표시
-9. "Restart" 버튼으로 재시작
-
-### 시나리오 2: 최고 점수 갱신
-1. 게임 플레이 중 현재 점수가 최고 점수 초과
-2. 화면에 "New High Score!" 표시
-3. 게임 오버 시 최고 점수 localStorage에 저장
-4. 다음 게임 시작 시 저장된 최고 점수 표시
-
-### 시나리오 3: 모바일 플레이
-1. 모바일 기기로 접속
-2. 화면이 모바일 크기에 맞게 조정됨
-3. 화면 하단에 방향 버튼 표시
-4. 터치/스와이프로 뱀 조작
-5. 세로 모드에서 최적화된 레이아웃
-
----
-
-## 6. 인수 기준 (Acceptance Criteria)
-
-### 게임 기본 기능
-- [ ] 게임 시작 시 뱀이 화면 중앙에 나타난다
-- [ ] 방향키 입력에 따라 뱀이 즉시 방향을 바꾼다
-- [ ] 뱀이 먹이를 먹으면 길이가 1 증가한다
-- [ ] 먹이를 먹으면 점수가 10점 증가한다
-- [ ] 벽에 부딪히면 게임이 끝난다
-- [ ] 자기 몸에 부딪히면 게임이 끝난다
-- [ ] 게임 오버 후 재시작할 수 있다
-
-### 추가 기능
-- [ ] 50점마다 레벨이 1 증가한다
-- [ ] 레벨이 오르면 뱀의 속도가 빨라진다
-- [ ] 최고 점수가 브라우저에 저장된다
-- [ ] P키를 누르면 일시정지된다
-- [ ] 모바일에서 터치로 조작할 수 있다
-
-### 품질 기준
-- [ ] TypeScript 타입 에러가 없다
-- [ ] ESLint 경고/에러가 없다
-- [ ] 테스트 커버리지 80% 이상
-- [ ] 60fps로 부드럽게 동작한다
-
----
-
-## 📝 요약
-
-| 카테고리 | 필수 | 중요 | 선택 |
-|---------|------|------|------|
-| 기능적 요구사항 | 12개 | 8개 | 2개 |
-| 비기능적 요구사항 | 8개 | 3개 | 0개 |
-| 총계 | 20개 | 11개 | 2개 |
-
-**MVP 범위**: 필수 요구사항 20개 + 중요 요구사항 중 선택 5개

package/template/stages/02-research/HANDOFF.md

@@ -1,158 +0,0 @@
-# HANDOFF: 02-research → 03-planning
-
-> 생성일: 2026-01-21
-> 프로젝트: snake-game
-> 현재 스테이지: 02-research (완료)
-> 다음 스테이지: 03-planning
-
----
-
-## ✅ 완료된 작업
-
-- [x] Canvas 게임 루프 구현 방법 조사
-- [x] React + Canvas 통합 패턴 분석
-- [x] 모바일 터치 이벤트 처리 조사
-- [x] 충돌 감지 알고리즘 정리
-- [x] localStorage 하이스코어 구현 방법
-- [x] 성능 최적화 기법 조사
-- [x] 오픈소스 프로젝트 사례 수집
-- [x] 실현 가능성 보고서 작성
-
----
-
-## 📋 핵심 기술 결정사항
-
-### 1. 렌더링 방식
-- **선택**: Canvas API
-- **이유**: 게임 성능, 60fps 유지, 복잡한 애니메이션 지원
-- **대안 기각**: CSS Grid (대량 요소 시 성능 저하)
-
-### 2. 게임 루프
-- **선택**: requestAnimationFrame
-- **이유**: 브라우저 최적화, 탭 비활성화 시 자동 일시정지
-- **대안 기각**: setInterval (정확도 낮음)
-
-### 3. 상태 관리
-- **선택**: useReducer + useRef 조합
-- **이유**: 복잡한 게임 상태, 리렌더링 최소화
-- **패턴**: 게임 로직은 useRef, UI 표시용만 useState
-
-### 4. 모바일 조작
-- **선택**: Custom useSwipe 훅 + 방향 버튼
-- **이유**: 검증된 패턴, 두 가지 입력 방식 모두 지원
-
----
-
-## 📁 생성된 산출물
-
-| 파일 | 설명 |
-|------|------|
-| `outputs/tech_research.md` | 기술 리서치 상세 결과 |
-| `outputs/feasibility_report.md` | 실현 가능성 보고서 |
-| `HANDOFF.md` | 이 문서 |
-
----
-
-## 🔧 권장 기술 스택
-
-```yaml
-# 프로젝트 구조
-framework: React 18+
-language: TypeScript 5+
-build: Vite 5+
-rendering: Canvas API
-state: useReducer + useRef
-styling: CSS Modules 또는 Tailwind CSS
-testing: Vitest + React Testing Library
-```
-
----
-
-## 📊 핵심 코드 패턴 요약
-
-### 게임 루프 훅
-```typescript
-const useGameLoop = (callback: (deltaTime: number) => void) => {
-  const requestRef = useRef<number>();
-  const previousTimeRef = useRef<number>();
-  // ... requestAnimationFrame 기반 루프
-};
-```
-
-### 스와이프 감지 훅
-```typescript
-const useSwipe = (handlers: { left, right, up, down }) => {
-  // touchstart/touchend 기반 방향 감지
-};
-```
-
-### 타입 정의
-```typescript
-type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
-type GameStatus = 'idle' | 'playing' | 'paused' | 'gameover';
-interface Position { x: number; y: number; }
-interface GameState { snake, food, direction, score, status }
-```
-
----
-
-## 🔜 다음 스테이지 작업
-
-### 03-planning에서 결정할 사항
-
-1. **상세 아키텍처**
-   - 컴포넌트 구조도
-   - 데이터 흐름 다이어그램
-   - 훅 의존성 관계
-
-2. **파일 구조**
-   - src/ 디렉토리 구조
-   - 컴포넌트/훅/유틸/타입 분리
-
-3. **게임 설정 상수**
-   - 보드 크기, 셀 크기
-   - 초기 속도, 속도 증가량
-   - 레벨업 조건
-
-4. **API 설계**
-   - 게임 상태 인터페이스
-   - 액션 타입 정의
-   - 리듀서 로직
-
----
-
-## ⚠️ 주의사항
-
-1. **외부 게임 엔진 미사용**: Phaser, PixiJS 등 금지
-2. **순수 React 구현**: jQuery 미사용
-3. **리렌더링 최소화**: Canvas는 직접 업데이트
-4. **성능 우선**: 60fps 목표
-
----
-
-## 📊 AI 호출 기록
-
-| AI | 시간 | 도구 | 결과 | 상태 |
-|----|------|------|------|------|
-| Claude | 12:10 | Exa MCP | Canvas 게임 루프 패턴 수집 | ✅ |
-| Claude | 12:12 | Exa MCP | 모바일 터치 조작 패턴 수집 | ✅ |
-| Claude | 12:15 | - | tech_research.md 작성 | ✅ |
-| Claude | 12:16 | - | feasibility_report.md 작성 | ✅ |
-
----
-
-## 🚀 다음 단계
-
-```bash
-# 다음 스테이지 실행
-/run-stage 03-planning
-
-# 또는
-/planning
-```
-
----
-
-**생성자**: ClaudeCode
-**검토자**: -
-**승인**: 대기

package/template/stages/02-research/outputs/feasibility_report.md

@@ -1,176 +0,0 @@
-# 📊 Snake Game - 실현 가능성 보고서
-
-> 생성일: 2026-01-21
-> 스테이지: 02-research
-> 프로젝트: snake-game
-
----
-
-## 1. 기술적 실현 가능성
-
-### 1.1 종합 평가
-
-| 항목 | 난이도 | 실현 가능성 | 비고 |
-|------|--------|------------|------|
-| Canvas 렌더링 | ⭐⭐ | ✅ 높음 | 표준 API, 풍부한 자료 |
-| 게임 루프 | ⭐⭐ | ✅ 높음 | requestAnimationFrame 표준 |
-| 키보드 입력 | ⭐ | ✅ 높음 | 기본 이벤트 처리 |
-| 터치 입력 | ⭐⭐ | ✅ 높음 | 검증된 패턴 존재 |
-| 충돌 감지 | ⭐ | ✅ 높음 | 간단한 알고리즘 |
-| 상태 관리 | ⭐⭐ | ✅ 높음 | useReducer 활용 |
-| localStorage | ⭐ | ✅ 높음 | 브라우저 기본 API |
-| 반응형 디자인 | ⭐⭐ | ✅ 높음 | CSS + JS 조합 |
-
-**종합 평가**: ✅ **높은 실현 가능성**
-
----
-
-### 1.2 기술 스택 적합성
-
-| 기술 | 선택 이유 | 대안 | 리스크 |
-|------|----------|------|--------|
-| React 18 | 컴포넌트 기반, 훅 시스템 | Vue, Svelte | 낮음 |
-| TypeScript | 타입 안전성, IDE 지원 | JavaScript | 낮음 |
-| Vite | 빠른 개발 서버, HMR | CRA, Next.js | 낮음 |
-| Canvas API | 게임 렌더링 최적화 | CSS Grid | 낮음 |
-
----
-
-## 2. 리소스 요구사항
-
-### 2.1 개발 환경
-
-| 항목 | 요구사항 | 현재 상태 |
-|------|---------|----------|
-| Node.js | 18+ | ✅ |
-| npm/yarn | 최신 | ✅ |
-| IDE | VSCode + TypeScript | ✅ |
-| 브라우저 | Chrome/Firefox 최신 | ✅ |
-
-### 2.2 외부 의존성
-
-| 패키지 | 버전 | 용도 | 필수 |
-|--------|------|------|------|
-| react | ^18.2.0 | UI 프레임워크 | ✅ |
-| react-dom | ^18.2.0 | DOM 렌더링 | ✅ |
-| typescript | ^5.0.0 | 타입 시스템 | ✅ |
-| vite | ^5.0.0 | 빌드 도구 | ✅ |
-
-**외부 게임 엔진 불필요** - 순수 React + Canvas로 구현 가능
-
----
-
-## 3. 리스크 평가
-
-### 3.1 기술적 리스크
-
-| 리스크 | 확률 | 영향도 | 대응 방안 |
-|--------|------|--------|----------|
-| 모바일 성능 저하 | 중 | 중 | Canvas 최적화, 프레임 스킵 |
-| 터치 입력 지연 | 낮 | 중 | passive 리스너, 즉시 응답 |
-| 브라우저 호환성 | 낮 | 낮 | 폴리필, 기능 감지 |
-| 메모리 누수 | 낮 | 중 | cleanup 함수, useEffect 정리 |
-
-### 3.2 프로젝트 리스크
-
-| 리스크 | 확률 | 영향도 | 대응 방안 |
-|--------|------|--------|----------|
-| 범위 확장 | 중 | 중 | MVP 우선, 기능 동결 |
-| 테스트 부족 | 중 | 중 | TDD 접근, 커버리지 목표 설정 |
-| 일정 지연 | 낮 | 낮 | 버퍼 시간 확보 |
-
----
-
-## 4. MVP vs 전체 기능 비교
-
-### 4.1 MVP 범위 (Phase 1)
-
-| 기능 | 복잡도 | 예상 시간 | 우선순위 |
-|------|--------|----------|---------|
-| 기본 뱀 조작 | 낮 | 30분 | 🔴 필수 |
-| 먹이 시스템 | 낮 | 20분 | 🔴 필수 |
-| 충돌 감지 | 낮 | 20분 | 🔴 필수 |
-| 점수 시스템 | 낮 | 10분 | 🔴 필수 |
-| 게임 재시작 | 낮 | 15분 | 🔴 필수 |
-| **소계** | - | **~1.5시간** | - |
-
-### 4.2 추가 기능 (Phase 2)
-
-| 기능 | 복잡도 | 예상 시간 | 우선순위 |
-|------|--------|----------|---------|
-| 레벨 시스템 | 낮 | 20분 | 🟡 중요 |
-| 최고 점수 저장 | 낮 | 15분 | 🟡 중요 |
-| 일시정지 | 낮 | 15분 | 🟡 중요 |
-| 모바일 터치 | 중 | 40분 | 🟡 중요 |
-| **소계** | - | **~1.5시간** | - |
-
-### 4.3 선택 기능 (Phase 3)
-
-| 기능 | 복잡도 | 예상 시간 | 우선순위 |
-|------|--------|----------|---------|
-| 사운드 효과 | 중 | 30분 | 🟢 선택 |
-| 테마/스킨 | 중 | 45분 | 🟢 선택 |
-| 장애물 모드 | 중 | 30분 | 🟢 선택 |
-| **소계** | - | **~2시간** | - |
-
----
-
-## 5. 성공 지표
-
-### 5.1 기술 지표
-
-| 지표 | 목표 | 측정 방법 |
-|------|------|----------|
-| 프레임레이트 | 60fps | Chrome DevTools |
-| 초기 로딩 | < 2초 | Lighthouse |
-| 번들 크기 | < 200KB | vite-bundle-visualizer |
-| 테스트 커버리지 | > 80% | vitest coverage |
-
-### 5.2 품질 지표
-
-| 지표 | 목표 | 측정 방법 |
-|------|------|----------|
-| TypeScript 에러 | 0개 | tsc --noEmit |
-| ESLint 경고 | 0개 | eslint . |
-| 접근성 | WCAG AA | axe-core |
-
----
-
-## 6. 결론 및 권장사항
-
-### 6.1 최종 평가
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  실현 가능성: ✅ 매우 높음                               │
-│  기술적 난이도: ⭐⭐ (중하)                              │
-│  리스크 수준: 🟢 낮음                                   │
-│  권장 진행: ✅ 승인                                     │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 6.2 권장사항
-
-1. **MVP 우선 개발**: 핵심 기능 먼저 완성 후 확장
-2. **Canvas 사용**: CSS Grid 대신 성능 우선
-3. **useRef 활용**: 게임 상태는 리렌더링 최소화
-4. **테스트 병행**: 로직 테스트 먼저, UI 테스트 나중
-5. **점진적 모바일 지원**: 데스크톱 완성 후 터치 추가
-
-### 6.3 다음 단계
-
-1. **03-planning**: 상세 아키텍처 설계
-2. **04-ui-ux**: 게임 화면 와이어프레임
-3. **05-tasks**: 스프린트 계획 수립
-4. **06-implementation**: MVP 개발 착수
-
----
-
-## 📝 승인
-
-| 항목 | 상태 |
-|------|------|
-| 기술적 실현 가능성 | ✅ 확인 |
-| 리소스 요구사항 | ✅ 충족 |
-| 리스크 평가 | ✅ 수용 가능 |
-| **최종 결정** | ✅ **개발 진행 승인** |