create-ax-project 1.0.0

package/template/stages/03-planning/outputs/project_plan.md

@@ -0,0 +1,204 @@
+# 📅 Snake Game - 프로젝트 계획
+
+> 생성일: 2026-01-21
+> 스테이지: 03-planning
+> 프로젝트: snake-game
+
+---
+
+## 1. 마일스톤 정의
+
+### Phase 1: MVP (핵심 기능)
+
+| 마일스톤 | 목표 | 완료 기준 |
+|---------|------|----------|
+| M1.1 | 프로젝트 셋업 | Vite + React + TypeScript 환경 구성 완료 |
+| M1.2 | 게임 보드 렌더링 | Canvas에 그리드 표시, 뱀 초기 위치 렌더링 |
+| M1.3 | 뱀 이동 | 방향키로 뱀 이동, 게임 루프 동작 |
+| M1.4 | 먹이 시스템 | 먹이 생성, 먹이 충돌 시 뱀 성장 |
+| M1.5 | 충돌 감지 | 벽/자기 몸 충돌 시 게임 오버 |
+| M1.6 | 점수 & UI | 점수 표시, 게임 오버 화면, 재시작 |
+
+### Phase 2: 향상된 기능
+
+| 마일스톤 | 목표 | 완료 기준 |
+|---------|------|----------|
+| M2.1 | 레벨 시스템 | 점수 증가 시 속도 증가 |
+| M2.2 | 최고 점수 | localStorage 저장/불러오기 |
+| M2.3 | 일시정지 | P/Escape 키로 일시정지/재개 |
+| M2.4 | 모바일 지원 | 터치 스와이프 + 방향 버튼 |
+
+### Phase 3: 폴리싱
+
+| 마일스톤 | 목표 | 완료 기준 |
+|---------|------|----------|
+| M3.1 | 반응형 디자인 | 다양한 화면 크기 대응 |
+| M3.2 | 테스트 작성 | 단위 테스트 커버리지 80%+ |
+| M3.3 | 배포 | GitHub Pages 또는 Vercel 배포 |
+
+---
+
+## 2. 스프린트 계획
+
+### Sprint 1: 프로젝트 기반 (04-ui-ux ~ 05-task-management)
+
+| 태스크 | 담당 스테이지 | 산출물 |
+|--------|-------------|--------|
+| UI/UX 와이어프레임 | 04-ui-ux | wireframes.md |
+| 디자인 토큰 정의 | 04-ui-ux | design-tokens.md |
+| 태스크 분해 | 05-task-management | tasks.md |
+| 스프린트 계획 | 05-task-management | sprint-plan.md |
+
+### Sprint 2: MVP 구현 (06-implementation)
+
+| 태스크 | 우선순위 | 예상 시간 |
+|--------|---------|----------|
+| 프로젝트 초기화 (Vite) | P0 | 10분 |
+| 타입 정의 | P0 | 10분 |
+| 상수 정의 | P0 | 10분 |
+| useGameLoop 훅 | P0 | 15분 |
+| useKeyboard 훅 | P0 | 15분 |
+| gameReducer 구현 | P0 | 20분 |
+| collision.ts 구현 | P0 | 15분 |
+| renderer.ts 구현 | P0 | 20분 |
+| CanvasLayer 컴포넌트 | P0 | 15분 |
+| GameEngine 컴포넌트 | P0 | 20분 |
+| ScoreBoard 컴포넌트 | P1 | 10분 |
+| GameOverModal 컴포넌트 | P1 | 15분 |
+| App 통합 | P0 | 15분 |
+
+### Sprint 3: 기능 확장 (06-implementation 계속)
+
+| 태스크 | 우선순위 | 예상 시간 |
+|--------|---------|----------|
+| 레벨 시스템 | P1 | 15분 |
+| useHighScore 훅 | P1 | 15분 |
+| 일시정지 기능 | P1 | 10분 |
+| useSwipe 훅 | P1 | 20분 |
+| MobileControls 컴포넌트 | P1 | 20분 |
+| StartScreen 컴포넌트 | P2 | 15분 |
+
+### Sprint 4: 품질 개선 (07-refactoring ~ 08-qa)
+
+| 태스크 | 담당 스테이지 | 예상 시간 |
+|--------|-------------|----------|
+| 코드 리뷰 & 리팩토링 | 07-refactoring | 30분 |
+| 성능 최적화 | 07-refactoring | 20분 |
+| 버그 수정 | 08-qa | 20분 |
+| 엣지 케이스 테스트 | 08-qa | 15분 |
+
+### Sprint 5: 테스트 & 배포 (09-testing ~ 10-deployment)
+
+| 태스크 | 담당 스테이지 | 예상 시간 |
+|--------|-------------|----------|
+| 단위 테스트 작성 | 09-testing | 30분 |
+| E2E 테스트 작성 | 09-testing | 20분 |
+| 빌드 설정 | 10-deployment | 10분 |
+| 배포 | 10-deployment | 15분 |
+
+---
+
+## 3. 의존성 그래프
+
+```
+프로젝트 초기화
+       │
+       ▼
+┌──────┴──────┐
+│             │
+▼             ▼
+타입 정의    상수 정의
+│             │
+└──────┬──────┘
+       │
+       ▼
+┌──────┴──────┬──────────────┐
+│             │              │
+▼             ▼              ▼
+useGameLoop  useKeyboard  collision.ts
+│             │              │
+└─────────────┼──────────────┘
+              │
+              ▼
+        gameReducer
+              │
+              ▼
+        renderer.ts
+              │
+              ▼
+       CanvasLayer
+              │
+              ▼
+       GameEngine
+              │
+       ┌──────┼──────┐
+       │      │      │
+       ▼      ▼      ▼
+  ScoreBoard Modal  App
+```
+
+---
+
+## 4. 리스크 관리
+
+### 기술적 리스크
+
+| 리스크 | 확률 | 영향 | 대응 |
+|--------|------|------|------|
+| Canvas 성능 이슈 | 낮 | 중 | requestAnimationFrame 최적화 |
+| 모바일 터치 지연 | 중 | 중 | passive 리스너, 즉시 응답 |
+| 상태 동기화 문제 | 중 | 높 | useRef로 게임 상태 분리 |
+
+### 일정 리스크
+
+| 리스크 | 확률 | 영향 | 대응 |
+|--------|------|------|------|
+| 기능 범위 확대 | 중 | 중 | MVP 우선, Phase 분리 |
+| 디버깅 시간 초과 | 중 | 중 | 단계별 테스트 |
+
+---
+
+## 5. 완료 기준 (Definition of Done)
+
+### 코드 레벨
+- [ ] TypeScript 컴파일 에러 0개
+- [ ] ESLint 경고 0개
+- [ ] 단위 테스트 커버리지 80%+
+
+### 기능 레벨
+- [ ] 방향키로 뱀 이동 가능
+- [ ] 먹이 먹으면 길이 증가 + 점수 획득
+- [ ] 벽/자기 몸 충돌 시 게임 오버
+- [ ] 게임 재시작 가능
+- [ ] 최고 점수 저장/표시
+
+### 품질 레벨
+- [ ] 60fps 유지 (Chrome DevTools 확인)
+- [ ] 모바일 터치 작동
+- [ ] 접근성 기본 준수 (키보드 네비게이션)
+
+---
+
+## 6. 스테이지별 예상 시간
+
+| 스테이지 | 예상 시간 | 주요 산출물 |
+|---------|----------|------------|
+| 04-ui-ux | 15분 | wireframes.md, design-tokens.md |
+| 05-task-management | 15분 | tasks.md, sprint-plan.md |
+| 06-implementation | 60분 | 소스 코드 전체 |
+| 07-refactoring | 30분 | 최적화된 코드 |
+| 08-qa | 20분 | 버그 수정 |
+| 09-testing | 30분 | 테스트 코드 |
+| 10-deployment | 20분 | 배포된 앱 |
+| **총계** | **~3시간** | - |
+
+---
+
+## ✅ 프로젝트 계획 체크리스트
+
+- [x] 마일스톤 정의
+- [x] 스프린트 계획
+- [x] 의존성 그래프
+- [x] 리스크 관리 계획
+- [x] 완료 기준 정의
+- [x] 시간 추정

package/template/stages/03-planning/outputs/tech_stack.md

@@ -0,0 +1,176 @@
+# 🔧 Snake Game - 기술 스택 결정
+
+> 생성일: 2026-01-21
+> 스테이지: 03-planning
+> 프로젝트: snake-game
+
+---
+
+## 📋 최종 기술 스택
+
+### 핵심 스택
+
+| 카테고리 | 선택 | 버전 | 근거 |
+|---------|------|------|------|
+| **프레임워크** | React | ^18.2.0 | 컴포넌트 기반, 훅 시스템 |
+| **언어** | TypeScript | ^5.3.0 | 타입 안전성, IDE 지원 |
+| **빌드** | Vite | ^5.0.0 | 빠른 HMR, 최적화된 빌드 |
+| **렌더링** | Canvas API | 네이티브 | 게임 성능, 60fps |
+| **상태관리** | useReducer + useRef | React 내장 | 외부 의존성 최소화 |
+
+### 개발 도구
+
+| 카테고리 | 선택 | 버전 | 용도 |
+|---------|------|------|------|
+| **린터** | ESLint | ^8.55.0 | 코드 품질 |
+| **포맷터** | Prettier | ^3.1.0 | 코드 일관성 |
+| **테스트** | Vitest | ^1.1.0 | 단위/통합 테스트 |
+| **E2E** | Playwright | ^1.40.0 | E2E 테스트 |
+
+### 스타일링
+
+| 카테고리 | 선택 | 근거 |
+|---------|------|------|
+| **CSS** | CSS Modules | 스코프 격리, 번들 최적화 |
+| **대안** | Tailwind CSS | 빠른 프로토타이핑 (선택) |
+
+---
+
+## 📦 package.json 의존성
+
+```json
+{
+  "name": "snake-game",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "@vitest/coverage-v8": "^1.1.0",
+    "@testing-library/react": "^14.1.0",
+    "@testing-library/jest-dom": "^6.1.6",
+    "@playwright/test": "^1.40.0",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "jsdom": "^23.0.1",
+    "prettier": "^3.1.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.1.0"
+  }
+}
+```
+
+---
+
+## ⚖️ 기술 결정 근거
+
+### 1. React vs Vue vs Svelte
+
+| 항목 | React | Vue | Svelte |
+|------|-------|-----|--------|
+| 생태계 | ⭐⭐⭐ | ⭐⭐ | ⭐ |
+| 학습 곡선 | 중간 | 낮음 | 낮음 |
+| 게임 개발 자료 | 많음 | 보통 | 적음 |
+| 커뮤니티 | 최대 | 큼 | 성장 중 |
+
+**선택: React** - 풍부한 게임 개발 자료, 훅 시스템 활용
+
+### 2. Canvas vs CSS Grid vs SVG
+
+| 항목 | Canvas | CSS Grid | SVG |
+|------|--------|----------|-----|
+| 성능 (대량 요소) | ⭐⭐⭐ | ⭐ | ⭐⭐ |
+| 구현 복잡도 | 중간 | 낮음 | 높음 |
+| 애니메이션 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
+| 반응형 | 코드 필요 | 자동 | 자동 |
+
+**선택: Canvas** - 게임에 최적화, 60fps 보장
+
+### 3. 상태 관리: useReducer vs Redux vs Zustand
+
+| 항목 | useReducer | Redux | Zustand |
+|------|-----------|-------|---------|
+| 번들 크기 | 0KB | ~43KB | ~3KB |
+| 복잡도 | 낮음 | 높음 | 낮음 |
+| 게임 적합성 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
+
+**선택: useReducer** - 외부 의존성 없음, 게임 규모에 적합
+
+### 4. Vite vs CRA vs Next.js
+
+| 항목 | Vite | CRA | Next.js |
+|------|------|-----|---------|
+| 빌드 속도 | ⭐⭐⭐ | ⭐ | ⭐⭐ |
+| 설정 복잡도 | 낮음 | 낮음 | 중간 |
+| 정적 빌드 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
+
+**선택: Vite** - 빠른 개발 경험, 최적화된 빌드
+
+---
+
+## 🚫 미사용 기술
+
+| 기술 | 미사용 이유 |
+|------|-----------|
+| Phaser.js | 게임 엔진 금지 (순수 React) |
+| PixiJS | 게임 엔진 금지 |
+| jQuery | 레거시, React와 충돌 |
+| MobX | 과도한 복잡성 |
+| Next.js | SSR 불필요 (정적 게임) |
+| Sass/SCSS | CSS Modules로 충분 |
+
+---
+
+## 📁 프로젝트 생성 명령
+
+```bash
+# Vite로 React + TypeScript 프로젝트 생성
+npm create vite@latest snake-game -- --template react-ts
+
+# 디렉토리 이동
+cd snake-game
+
+# 의존성 설치
+npm install
+
+# 개발 도구 설치
+npm install -D @vitest/coverage-v8 @testing-library/react \
+  @testing-library/jest-dom jsdom @playwright/test
+
+# 개발 서버 시작
+npm run dev
+```
+
+---
+
+## ✅ 기술 스택 체크리스트
+
+- [x] 핵심 프레임워크 선택 (React 18)
+- [x] 언어 선택 (TypeScript 5)
+- [x] 빌드 도구 선택 (Vite 5)
+- [x] 렌더링 방식 선택 (Canvas API)
+- [x] 상태 관리 방식 선택 (useReducer + useRef)
+- [x] 스타일링 방식 선택 (CSS Modules)
+- [x] 테스트 도구 선택 (Vitest + Playwright)
+- [x] 의존성 목록 작성

package/template/stages/03-planning/prompts/architecture.md

@@ -0,0 +1,62 @@
+# Architecture Design Prompt
+
+## 사용 모델
+Gemini
+
+## 프롬프트
+
+```
+당신은 시니어 소프트웨어 아키텍트입니다.
+
+다음 요구사항과 기술 리서치를 바탕으로 시스템 아키텍처를 설계해주세요:
+
+---
+## 요구사항
+{{REQUIREMENTS}}
+
+## 기술 리서치 결과
+{{TECH_RESEARCH}}
+
+## 실현 가능성 평가
+{{FEASIBILITY}}
+---
+
+## 설계 항목
+
+### 1. 시스템 개요
+- 시스템 목적
+- 주요 기능
+- 비기능적 요구사항 대응
+
+### 2. 아키텍처 스타일
+- 선택: Monolithic / Microservices / Serverless / Hybrid
+- 선택 근거
+
+### 3. 컴포넌트 설계
+각 컴포넌트에 대해:
+- 이름
+- 책임
+- 인터페이스
+- 의존성
+
+### 4. 데이터 아키텍처
+- 데이터 모델 개요
+- 데이터 흐름
+- 저장소 전략
+
+### 5. 통합 포인트
+- 외부 API
+- 서드파티 서비스
+- 인증/인가
+
+### 6. 다이어그램 (Mermaid)
+- 시스템 컨텍스트
+- 컨테이너 다이어그램
+- 컴포넌트 다이어그램
+
+## 출력 형식
+Mermaid 다이어그램을 포함한 마크다운 문서
+```
+
+## 기대 출력
+`outputs/architecture.md`

package/template/stages/03-planning/prompts/collaboration.md

@@ -0,0 +1,57 @@
+# AI 협업 프롬프트 - Planning
+
+## 협업 모드: Debate
+
+이 스테이지에서는 **토론 모드**를 사용하여 최적의 아키텍처와 기술 스택을 결정합니다.
+
+### 참여 모델
+- **Gemini**: 아키텍처 설계, 다이어그램 생성
+- **Claude**: 기술적 검증, 실현 가능성 평가
+
+### 협업 프롬프트
+
+```
+/collaborate --mode debate --topic "시스템 아키텍처 결정" --rounds 3
+```
+
+### 토론 주제
+
+1. **아키텍처 패턴**: Monolith vs Microservices vs Modular Monolith
+2. **기술 스택**: 프레임워크 및 라이브러리 선택
+3. **데이터베이스**: SQL vs NoSQL vs Hybrid
+
+### 토론 형식
+
+| 라운드 | Gemini | Claude |
+|--------|--------|--------|
+| 1 | 제안 | 반론/대안 |
+| 2 | 보완 | 검증/평가 |
+| 3 | 최종안 | 합의/확인 |
+
+### 파이프라인 분기 트리거
+
+아키텍처 대안이 2개 이상 유효할 경우:
+```
+/fork create --reason "아키텍처 대안 탐색" --direction "monolith"
+/fork create --reason "아키텍처 대안 탐색" --direction "microservices"
+```
+
+### 출력 형식
+
+```markdown
+## AI 토론 결과
+
+### 주제: [아키텍처 결정]
+
+### 라운드 1
+- **Gemini**: [제안]
+- **Claude**: [반론/대안]
+
+### 라운드 2
+- **Gemini**: [보완]
+- **Claude**: [검증]
+
+### 최종 결론
+- [합의된 아키텍처]
+- [근거]
+```

package/template/stages/03-planning/prompts/validation.md

@@ -0,0 +1,59 @@
+# 산출물 검증 프롬프트 - Planning
+
+## 검증 대상
+
+| 산출물 | 필수 조건 | 검증 방법 |
+|--------|----------|----------|
+| `architecture.md` | 다이어그램 4종 | 구조 확인 |
+| `tech_stack.md` | 버전/의존성 명시 | 항목 확인 |
+| `project_plan.md` | 마일스톤 3개+ | 수량 확인 |
+| `implementation.yaml` | 구현 규칙 정의 | 스키마 검증 |
+| `HANDOFF.md` | 다음 단계 지침 | 항목 확인 |
+
+## 검증 명령
+
+```bash
+/validate --stage 03-planning
+```
+
+## 품질 기준
+
+### architecture.md
+- [ ] 시스템 컨텍스트 다이어그램
+- [ ] 컨테이너 다이어그램
+- [ ] 컴포넌트 다이어그램
+- [ ] 시퀀스 다이어그램 (핵심 플로우)
+- [ ] 데이터 흐름 설명
+
+### tech_stack.md
+- [ ] 프론트엔드 스택 명시
+- [ ] 백엔드 스택 명시
+- [ ] 데이터베이스 선택
+- [ ] 버전 및 의존성 정의
+- [ ] 선택 근거 문서화
+
+### project_plan.md
+- [ ] 마일스톤 3개 이상
+- [ ] 각 마일스톤별 산출물
+- [ ] 스프린트 계획
+- [ ] 리소스 할당
+
+### implementation.yaml
+- [ ] 컴포넌트 타입 정의
+- [ ] 스타일링 방식 정의
+- [ ] 상태 관리 패턴 정의
+- [ ] 네이밍 규칙 정의
+- [ ] 폴더 구조 정의
+
+## 자동 검증 스크립트
+
+```bash
+# 다이어그램 수 확인 (mermaid 블록)
+grep -c "```mermaid" outputs/architecture.md
+
+# implementation.yaml 유효성
+yq eval '.' outputs/implementation.yaml
+
+# 마일스톤 수 확인
+grep -c "^## Milestone" outputs/project_plan.md
+```

package/template/stages/04-ui-ux/CLAUDE.md

@@ -0,0 +1,88 @@
+# Stage 04: UI/UX Planning
+
+사용자 인터페이스 및 경험 설계 단계
+
+## 🎭 페르소나: User Experience Designer
+
+> 당신은 User Experience Designer입니다.
+> 항상 사용자 관점에서 생각하고, 직관적인 경험을 설계하세요.
+> 모든 사용자가 쉽게 사용할 수 있도록 접근성을 고려하세요.
+
+### 특성
+- 사용자 공감
+- 시각적 사고
+- 인터랙션 설계
+- 접근성 고려
+
+### 권장 행동
+- 사용자 시나리오 기반
+- 직관적 인터페이스
+- 일관된 디자인 시스템
+- 접근성 고려
+
+### 지양 행동
+- 기술 중심 사고
+- 복잡한 인터랙션
+- 사용자 무시
+
+### AI 설정
+- **Temperature**: 0.7 (창의적 설계)
+- **사용자 집중도**: High
+
+## 실행 모델
+- **Primary**: Gemini (창의적 UI 설계)
+- **Mode**: Plan Mode
+
+## 목표
+1. 와이어프레임 설계
+2. 사용자 플로우 정의
+3. 디자인 시스템 기초 수립
+4. 컴포넌트 라이브러리 정의
+
+## 입력 파일
+- `../01-brainstorm/outputs/requirements_analysis.md`
+- `../03-planning/outputs/architecture.md`
+- `../03-planning/HANDOFF.md`
+
+## 출력 파일
+- `outputs/wireframes.md` - 와이어프레임 (ASCII/Mermaid)
+- `outputs/user_flows.md` - 사용자 플로우
+- `outputs/design_system.md` - 디자인 시스템
+- `HANDOFF.md` - 다음 스테이지 인계 문서
+
+## 워크플로우
+
+### 1. 정보 아키텍처
+- 화면 구조 정의
+- 네비게이션 설계
+- 콘텐츠 계층
+
+### 2. 와이어프레임
+- 주요 화면 와이어프레임
+- 반응형 고려사항
+- 상호작용 정의
+
+### 3. 사용자 플로우
+- 핵심 사용자 여정
+- 엣지 케이스 처리
+- 에러 상태
+
+### 4. 디자인 시스템
+- 색상 팔레트
+- 타이포그래피
+- 스페이싱 시스템
+- 컴포넌트 목록
+
+## 완료 조건
+- [ ] 주요 화면 와이어프레임 (5개 이상)
+- [ ] 핵심 사용자 플로우 3개 이상
+- [ ] 디자인 시스템 기초 정의
+- [ ] 컴포넌트 목록 작성
+- [ ] HANDOFF.md 생성
+
+## 다음 스테이지
+→ **05-task-management**: 태스크 분해 및 스프린트 계획
+
+
+
+