create-ax-project 1.0.0

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

@@ -0,0 +1,176 @@
+# 📊 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 개발 착수
+
+---
+
+## 📝 승인
+
+| 항목 | 상태 |
+|------|------|
+| 기술적 실현 가능성 | ✅ 확인 |
+| 리소스 요구사항 | ✅ 충족 |
+| 리스크 평가 | ✅ 수용 가능 |
+| **최종 결정** | ✅ **개발 진행 승인** |

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

@@ -0,0 +1,403 @@
+# 🔬 Snake Game - 기술 리서치
+
+> 생성일: 2026-01-21
+> 스테이지: 02-research
+> 프로젝트: snake-game
+> AI 도구: Claude + Exa MCP
+
+---
+
+## 📋 조사 항목 요약
+
+| 항목 | 권장 기술 | 근거 |
+|------|----------|------|
+| 렌더링 | Canvas API | 게임 성능, 60fps 유지 |
+| 게임 루프 | requestAnimationFrame | 브라우저 최적화, 탭 비활성화 처리 |
+| 상태 관리 | useReducer + useRef | 복잡한 게임 상태, 리렌더링 최소화 |
+| 모바일 조작 | Custom useSwipe Hook | 터치 이벤트 직접 처리 |
+| 하이스코어 | localStorage | 백엔드 불필요, 간단한 구현 |
+
+---
+
+## 1. Canvas 게임 루프 구현
+
+### 1.1 requestAnimationFrame 기반 게임 루프
+
+**핵심 패턴** (Exa 조사 결과):
+
+```typescript
+// useGameLoop.ts
+const useGameLoop = (callback: (deltaTime: number) => void) => {
+  const requestRef = useRef<number>();
+  const previousTimeRef = useRef<number>();
+
+  const animate = (time: number) => {
+    if (previousTimeRef.current !== undefined) {
+      const deltaTime = time - previousTimeRef.current;
+      callback(deltaTime);
+    }
+    previousTimeRef.current = time;
+    requestRef.current = requestAnimationFrame(animate);
+  };
+
+  useEffect(() => {
+    requestRef.current = requestAnimationFrame(animate);
+    return () => {
+      if (requestRef.current) {
+        cancelAnimationFrame(requestRef.current);
+      }
+    };
+  }, []);
+};
+```
+
+### 1.2 setInterval vs requestAnimationFrame 비교
+
+| 특성 | setInterval | requestAnimationFrame |
+|------|-------------|----------------------|
+| **정확도** | 낮음 (지연 발생) | 높음 (브라우저 최적화) |
+| **탭 비활성화** | 계속 실행 (리소스 낭비) | 자동 일시정지 |
+| **프레임레이트** | 고정 (부정확) | 디스플레이 동기화 (60fps) |
+| **성능** | 보통 | 최적화됨 |
+
+**결론**: requestAnimationFrame 사용 권장
+
+### 1.3 하이브리드 게임 루프 (고정 타임스텝)
+
+```typescript
+// 물리 시뮬레이션과 렌더링 분리
+const TICK_RATE = 1000 / 60; // 60 TPS
+let accumulator = 0;
+
+const gameLoop = (currentTime: number) => {
+  const deltaTime = currentTime - lastTime;
+  accumulator += Math.min(deltaTime, 100); // 프레임 스킵 제한
+
+  while (accumulator >= TICK_RATE) {
+    updateGameState(); // 고정 타임스텝 업데이트
+    accumulator -= TICK_RATE;
+  }
+
+  render(); // 가변 렌더링
+  requestAnimationFrame(gameLoop);
+};
+```
+
+---
+
+## 2. React + Canvas 통합 패턴
+
+### 2.1 useRef로 Canvas 접근
+
+```typescript
+const GameBoard: React.FC = () => {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    // 게임 렌더링 로직
+    const draw = () => {
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      // ... 렌더링
+    };
+
+    draw();
+  }, [gameState]);
+
+  return <canvas ref={canvasRef} width={400} height={400} />;
+};
+```
+
+### 2.2 리렌더링 최소화 전략
+
+**문제**: React setState가 너무 자주 호출되면 성능 저하
+
+**해결책**:
+1. **useRef로 게임 상태 관리** - 리렌더링 없이 상태 업데이트
+2. **Canvas 직접 업데이트** - React DOM 업데이트 우회
+3. **requestAnimationFrame 내에서 렌더링** - 효율적인 드로잉
+
+```typescript
+// 게임 상태는 useRef로 관리
+const gameStateRef = useRef<GameState>({
+  snake: [{x: 10, y: 10}],
+  food: {x: 5, y: 5},
+  direction: 'RIGHT',
+  score: 0
+});
+
+// UI에 표시할 점수만 useState로 관리
+const [displayScore, setDisplayScore] = useState(0);
+```
+
+---
+
+## 3. 모바일 터치 조작 구현
+
+### 3.1 useSwipe 커스텀 훅
+
+**Exa 조사 결과 기반 구현**:
+
+```typescript
+interface SwipeHandlers {
+  left?: () => void;
+  right?: () => void;
+  up?: () => void;
+  down?: () => void;
+}
+
+const useSwipe = (handlers: SwipeHandlers) => {
+  const touchCoordsRef = useRef({
+    touchStart: { x: 0, y: 0, time: Date.now() }
+  });
+
+  useEffect(() => {
+    const handleTouchStart = (e: TouchEvent) => {
+      touchCoordsRef.current.touchStart = {
+        x: e.targetTouches[0].clientX,
+        y: e.targetTouches[0].clientY,
+        time: Date.now()
+      };
+    };
+
+    const handleTouchEnd = (e: TouchEvent) => {
+      const threshold = 50; // 최소 스와이프 거리
+      const maxTime = 500; // 최대 스와이프 시간 (ms)
+
+      const { touchStart } = touchCoordsRef.current;
+      const touchEnd = {
+        x: e.changedTouches[0].clientX,
+        y: e.changedTouches[0].clientY
+      };
+
+      const elapsed = Date.now() - touchStart.time;
+      if (elapsed > maxTime) return;
+
+      const xDiff = touchStart.x - touchEnd.x;
+      const yDiff = touchStart.y - touchEnd.y;
+
+      if (Math.abs(xDiff) > Math.abs(yDiff)) {
+        // 수평 스와이프
+        if (Math.abs(xDiff) > threshold) {
+          xDiff > 0 ? handlers.left?.() : handlers.right?.();
+        }
+      } else {
+        // 수직 스와이프
+        if (Math.abs(yDiff) > threshold) {
+          yDiff > 0 ? handlers.up?.() : handlers.down?.();
+        }
+      }
+    };
+
+    window.addEventListener('touchstart', handleTouchStart, { passive: true });
+    window.addEventListener('touchend', handleTouchEnd, { passive: true });
+
+    return () => {
+      window.removeEventListener('touchstart', handleTouchStart);
+      window.removeEventListener('touchend', handleTouchEnd);
+    };
+  }, [handlers]);
+};
+```
+
+### 3.2 모바일 방향 버튼 (대안)
+
+```typescript
+const MobileControls: React.FC<{ onDirection: (dir: Direction) => void }> = ({ onDirection }) => (
+  <div className="mobile-controls">
+    <button onTouchStart={() => onDirection('UP')}>↑</button>
+    <div>
+      <button onTouchStart={() => onDirection('LEFT')}>←</button>
+      <button onTouchStart={() => onDirection('RIGHT')}>→</button>
+    </div>
+    <button onTouchStart={() => onDirection('DOWN')}>↓</button>
+  </div>
+);
+```
+
+---
+
+## 4. 충돌 감지 알고리즘
+
+### 4.1 벽 충돌 (O(1))
+
+```typescript
+const checkWallCollision = (head: Position, boardSize: number): boolean => {
+  return head.x < 0 || head.x >= boardSize || head.y < 0 || head.y >= boardSize;
+};
+```
+
+### 4.2 자기 몸 충돌 (O(n))
+
+```typescript
+const checkSelfCollision = (head: Position, body: Position[]): boolean => {
+  // body[0]은 머리이므로 1부터 시작
+  return body.slice(1).some(segment =>
+    segment.x === head.x && segment.y === head.y
+  );
+};
+```
+
+### 4.3 먹이 충돌 (O(1))
+
+```typescript
+const checkFoodCollision = (head: Position, food: Position): boolean => {
+  return head.x === food.x && head.y === food.y;
+};
+```
+
+---
+
+## 5. 상태 관리 구조
+
+### 5.1 게임 상태 타입 정의
+
+```typescript
+// types/game.ts
+type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
+type GameStatus = 'idle' | 'playing' | 'paused' | 'gameover';
+
+interface Position {
+  x: number;
+  y: number;
+}
+
+interface GameState {
+  snake: Position[];
+  food: Position;
+  direction: Direction;
+  nextDirection: Direction; // 입력 버퍼
+  score: number;
+  level: number;
+  status: GameStatus;
+}
+
+interface GameConfig {
+  boardSize: number;
+  cellSize: number;
+  initialSpeed: number;
+  speedIncrement: number;
+}
+```
+
+### 5.2 useReducer 기반 상태 관리
+
+```typescript
+type GameAction =
+  | { type: 'START_GAME' }
+  | { type: 'PAUSE_GAME' }
+  | { type: 'RESUME_GAME' }
+  | { type: 'GAME_OVER' }
+  | { type: 'SET_DIRECTION'; payload: Direction }
+  | { type: 'MOVE_SNAKE' }
+  | { type: 'EAT_FOOD' }
+  | { type: 'RESET_GAME' };
+
+const gameReducer = (state: GameState, action: GameAction): GameState => {
+  switch (action.type) {
+    case 'START_GAME':
+      return { ...state, status: 'playing' };
+    case 'SET_DIRECTION':
+      // 반대 방향 이동 방지
+      if (!isOppositeDirection(state.direction, action.payload)) {
+        return { ...state, nextDirection: action.payload };
+      }
+      return state;
+    case 'MOVE_SNAKE':
+      // 뱀 이동 로직
+      return moveSnake(state);
+    // ... 기타 액션
+  }
+};
+```
+
+---
+
+## 6. localStorage 하이스코어
+
+### 6.1 저장 및 로드
+
+```typescript
+const HIGH_SCORE_KEY = 'snake_game_high_score';
+
+const saveHighScore = (score: number): void => {
+  const currentHigh = getHighScore();
+  if (score > currentHigh) {
+    localStorage.setItem(HIGH_SCORE_KEY, score.toString());
+  }
+};
+
+const getHighScore = (): number => {
+  const stored = localStorage.getItem(HIGH_SCORE_KEY);
+  return stored ? parseInt(stored, 10) : 0;
+};
+```
+
+### 6.2 커스텀 훅
+
+```typescript
+const useHighScore = () => {
+  const [highScore, setHighScore] = useState(() => getHighScore());
+
+  const updateHighScore = useCallback((score: number) => {
+    if (score > highScore) {
+      setHighScore(score);
+      saveHighScore(score);
+    }
+  }, [highScore]);
+
+  return { highScore, updateHighScore };
+};
+```
+
+---
+
+## 7. 성능 최적화 팁
+
+### 7.1 Canvas 최적화
+
+1. **오프스크린 캔버스**: 복잡한 요소 미리 렌더링
+2. **부분 리드로잉**: 변경된 부분만 다시 그리기
+3. **이미지 스프라이트**: 여러 이미지 하나로 합치기
+
+### 7.2 React 최적화
+
+1. **useCallback/useMemo**: 불필요한 재생성 방지
+2. **React.memo**: 순수 컴포넌트 메모이제이션
+3. **게임 로직 분리**: Canvas 업데이트는 React 외부에서
+
+---
+
+## 📚 참고 자료
+
+### GitHub 오픈소스 프로젝트
+- [gimnathperera/snake-loop](https://github.com/gimnathperera/snake-loop) - React + RTK Query
+- [markkaylor/react-snake-ts](https://github.com/markkaylor/react-snake-ts) - TypeScript 구현
+- [v662-coder/SnakeGame](https://github.com/v662-coder/SnakeGame) - Canvas 기반
+
+### 기술 문서
+- [30-seconds-of-code: useRequestAnimationFrame](https://github.com/Chalarangelo/30-seconds-of-code)
+- [react-use: useRafLoop](https://github.com/streamich/react-use)
+- [beautiful-react-hooks: useRequestAnimationFrame](https://github.com/antonioru/beautiful-react-hooks)
+
+### 튜토리얼
+- [Learn Advance React Hooks by Building Snake Game](https://javascript.plainenglish.io/learn-advance-react-hooks-by-building-snake-game)
+- [Build Your First Snake Game with TypeScript React](https://javascript.plainenglish.io/build-your-first-snake-game-with-typescript-react)
+- [Create Dead-Simple Canvas Animations in React](https://spin.atomicobject.com/animations-react)
+
+---
+
+## ✅ 리서치 완료 체크리스트
+
+- [x] Canvas 게임 루프 구현 방법 조사
+- [x] React + Canvas 통합 패턴 분석
+- [x] 모바일 터치 이벤트 처리 조사
+- [x] 충돌 감지 알고리즘 정리
+- [x] localStorage 하이스코어 구현 방법
+- [x] 성능 최적화 기법 조사
+- [x] 오픈소스 프로젝트 사례 수집

package/template/stages/02-research/prompts/collaboration.md

@@ -0,0 +1,51 @@
+# AI 협업 프롬프트 - Research
+
+## 협업 모드: Parallel + Sequential
+
+이 스테이지에서는 **병렬 리서치** 후 **순차적 통합**을 진행합니다.
+
+### 참여 모델
+- **Claude**: 심층 분석, 기술 문서 합성
+- **Gemini**: 시장 트렌드, 경쟁사 분석
+
+### 협업 프롬프트
+
+```
+# 병렬 리서치
+/collaborate --mode parallel --models claude,gemini --task "기술 및 시장 리서치"
+
+# 순차적 통합 (Claude가 Gemini 결과 검토)
+/collaborate --mode sequential --chain "gemini:market_research -> claude:synthesis"
+```
+
+### 작업 분담
+
+| AI | 담당 영역 | 출력 |
+|----|----------|------|
+| Gemini | 시장 분석, 경쟁사 조사 | market_analysis.md |
+| Claude | 기술 스택 분석, 실현 가능성 | tech_research.md, feasibility_report.md |
+
+### MCP 서버 활용
+
+- **firecrawl**: 웹 크롤링 (Gemini 활용)
+- **exa**: AI 검색 (Claude 활용)
+- **context7**: 문서 검색 (Claude 활용)
+
+### 출력 형식
+
+```markdown
+## AI 협업 결과
+
+### Gemini 리서치 (시장)
+- 경쟁사 분석
+- 시장 트렌드
+...
+
+### Claude 리서치 (기술)
+- 기술 스택 비교
+- 실현 가능성 평가
+...
+
+### 통합 인사이트
+- [핵심 발견]
+```

package/template/stages/02-research/prompts/feasibility.md

@@ -0,0 +1,73 @@
+# Feasibility Analysis Prompt
+
+## 사용 모델
+Claude
+
+## 프롬프트
+
+```
+당신은 프로젝트 실현 가능성 평가 전문가입니다.
+
+다음 자료를 바탕으로 종합적인 실현 가능성 평가를 수행해주세요:
+
+---
+## 기술 리서치
+{{TECH_RESEARCH}}
+
+## 시장 분석
+{{MARKET_ANALYSIS}}
+
+## 요구사항
+{{REQUIREMENTS}}
+---
+
+## 평가 항목
+
+### 1. 기술적 실현 가능성
+- 기술 스택 성숙도
+- 팀 역량 대비 복잡도
+- 기술적 리스크
+
+점수: /10
+
+### 2. 경제적 실현 가능성
+- 예상 개발 비용
+- 운영 비용 (인프라, 유지보수)
+- ROI 예측
+
+점수: /10
+
+### 3. 일정 실현 가능성
+- MVP 개발 예상 기간
+- 전체 개발 예상 기간
+- 일정 리스크
+
+점수: /10
+
+### 4. 시장 실현 가능성
+- 시장 진입 가능성
+- 차별화 가능성
+- 성장 가능성
+
+점수: /10
+
+### 5. 리스크 매트릭스
+
+| 리스크 | 영향도 | 발생확률 | 완화전략 | 담당 |
+|--------|--------|----------|----------|------|
+
+### 6. Go/No-Go 권고
+
+종합 점수: /40
+
+권고: GO / CONDITIONAL GO / NO-GO
+
+조건 (CONDITIONAL일 경우):
+-
+
+## 출력 형식
+실현 가능성 보고서 (경영진 요약 포함)
+```
+
+## 기대 출력
+`outputs/feasibility_report.md`