create-ax-project 1.0.0 → 1.0.1

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

@@ -1,400 +0,0 @@
-# 🏗️ Snake Game 시스템 아키텍처 설계서
-
-> 생성일: 2026-01-21
-> 스테이지: 03-planning
-> 프로젝트: snake-game
-> AI 도구: Gemini CLI
-
----
-
-## 1. 컴포넌트 구조
-
-이 프로젝트는 단일 캔버스 렌더링 방식과 React UI 오버레이를 결합한 **하이브리드 구조**를 채택합니다.
-
-### 1.1 컴포넌트 역할
-
-| 컴포넌트 | 타입 | 역할 |
-|---------|------|------|
-| **App** | Container | 전체 레이아웃, 최상위 상태(테마 등) 관리 |
-| **GameEngine** | Smart | 핵심 비즈니스 로직 연결, Canvas/UI 조율 |
-| **CanvasLayer** | Presentation | Canvas 접근, 게임 렌더링 수행 |
-| **UIOverlay** | Presentation | HTML/CSS 기반 UI (점수, 모달 등) |
-| **ScoreBoard** | UI | 현재 점수와 최고 점수 표시 |
-| **GameOverModal** | UI | 게임 종료 시 재시작 버튼과 결과 |
-| **StartScreen** | UI | 게임 시작 전 타이틀 화면 |
-| **MobileControls** | UI | 모바일 방향 버튼 |
-
-### 1.2 계층 구조 다이어그램
-
-```
-+-------------------------------------------------------+
-|                       App                             |
-|-------------------------------------------------------|
-|  +-------------------------------------------------+  |
-|  |                  GameEngine                     |  |
-|  | (Holds Game State, Refs, and Event Listeners)   |  |
-|  |-------------------------------------------------|  |
-|  |  +-------------------+   +-------------------+  |  |
-|  |  |    CanvasLayer    |   |     UIOverlay     |  |  |
-|  |  | (Rendering Target)|   | (React Components)|  |  |
-|  |  |                   |   |                   |  |  |
-|  |  |  [Snake] [Food]   |   |  [ScoreBoard]     |  |  |
-|  |  |  [Grid]  [Fx]     |   |  [GameOverModal]  |  |  |
-|  |  |                   |   |  [MobileControls] |  |  |
-|  |  +-------------------+   +-------------------+  |  |
-|  +-------------------------------------------------+  |
-+-------------------------------------------------------+
-```
-
-### 1.3 컴포넌트 의존성 그래프
-
-```
-                    App
-                     │
-              GameEngine
-                     │
-        ┌────────────┼────────────┐
-        │            │            │
-   CanvasLayer   UIOverlay    Hooks
-        │            │            │
-        │      ┌─────┴─────┐     │
-        │      │     │     │     │
-        │  Score  Modal  Mobile │
-        │  Board  Over  Controls│
-        │                        │
-        └────────────────────────┘
-              Canvas Context
-```
-
----
-
-## 2. 데이터 흐름
-
-React의 선언적 상태 관리와 Canvas의 명령형 렌더링을 조화시키는 것이 핵심입니다.
-
-### 2.1 게임 상태 흐름
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                      State Flow                        │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│   useReducer ──────────────────────────────────────┐   │
-│       │                                            │   │
-│       ▼                                            │   │
-│   gameState ────────────────────────────────────►  │   │
-│   (snake, food, direction, score, status)          │   │
-│       │                                            │   │
-│       │  requestAnimationFrame                     │   │
-│       ▼         │                                  │   │
-│   gameLoop ◄────┘                                  │   │
-│       │                                            │   │
-│       ├──► dispatch({ type: 'TICK' })              │   │
-│       │                                            │   │
-│       ▼                                            │   │
-│   Canvas.draw() ◄──────────────────────────────────┘   │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 2.2 이벤트 처리 흐름
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Event Flow                          │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│   User Input                                           │
-│       │                                                │
-│       ├──► Keyboard (useKeyboard) ──┐                  │
-│       │                              │                  │
-│       └──► Touch (useSwipe) ────────┤                  │
-│                                      │                  │
-│                                      ▼                  │
-│                              Direction Normalized       │
-│                              (UP/DOWN/LEFT/RIGHT)      │
-│                                      │                  │
-│                                      ▼                  │
-│            dispatch({ type: 'CHANGE_DIRECTION' })      │
-│                                      │                  │
-│                                      ▼                  │
-│                              Collision Check           │
-│                                      │                  │
-│                     ┌────────────────┼────────────┐    │
-│                     │                │            │    │
-│                     ▼                ▼            ▼    │
-│                  Wall Hit       Self Hit      Eat Food │
-│                     │                │            │    │
-│                     ▼                ▼            ▼    │
-│                GAME_OVER        GAME_OVER    Grow +10  │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 2.3 상태 vs 참조 분리
-
-| 데이터 | 관리 방식 | 이유 |
-|--------|----------|------|
-| snake, food, score | `useReducer` | UI 리렌더링 필요 |
-| direction (버퍼) | `useRef` | 빠른 입력 처리, 리렌더링 방지 |
-| canvasRef | `useRef` | DOM 참조 |
-| animationFrameId | `useRef` | 루프 관리 |
-
----
-
-## 3. 커스텀 훅 설계
-
-### 3.1 useGameLoop
-
-```typescript
-/**
- * requestAnimationFrame 기반 게임 루프 관리
- * @param callback 매 프레임 실행될 함수
- * @param isRunning 루프 실행 여부
- */
-const useGameLoop = (
-  callback: (deltaTime: number) => void,
-  isRunning: boolean
-) => void;
-```
-
-**특징**:
-- 컴포넌트 언마운트 시 자동 정리
-- deltaTime 계산하여 프레임 독립적 애니메이션
-- isRunning으로 일시정지/재개 제어
-
-### 3.2 useKeyboard
-
-```typescript
-/**
- * 키보드 입력 감지 및 방향 변환
- * @param onDirectionChange 방향 변경 시 콜백
- * @param onPause 일시정지 토글 콜백
- * @param onRestart 재시작 콜백
- */
-const useKeyboard = (
-  onDirectionChange: (direction: Direction) => void,
-  onPause?: () => void,
-  onRestart?: () => void
-) => void;
-```
-
-**지원 키**:
-- Arrow Keys: 방향 이동
-- WASD: 방향 이동 (대안)
-- P / Escape: 일시정지
-- R / Space: 재시작
-
-### 3.3 useSwipe
-
-```typescript
-/**
- * 터치 스와이프 제스처 감지
- * @param handlers 각 방향별 핸들러
- */
-const useSwipe = (handlers: {
-  left?: () => void;
-  right?: () => void;
-  up?: () => void;
-  down?: () => void;
-}) => void;
-```
-
-**특징**:
-- 최소 스와이프 거리 (threshold): 50px
-- 최대 스와이프 시간: 500ms
-- passive 리스너로 성능 최적화
-
-### 3.4 useHighScore
-
-```typescript
-/**
- * localStorage 기반 최고 점수 관리
- */
-const useHighScore = () => {
-  highScore: number;
-  updateHighScore: (score: number) => boolean;  // 갱신 여부 반환
-  resetHighScore: () => void;
-};
-```
-
----
-
-## 4. 파일/폴더 구조
-
-```
-snake-game/
-├── public/
-│   └── favicon.svg
-├── src/
-│   ├── assets/              # 정적 자산
-│   │   └── sounds/          # 효과음 (선택)
-│   │
-│   ├── components/          # React UI 컴포넌트
-│   │   ├── CanvasLayer.tsx  # Canvas 래퍼
-│   │   ├── GameOverlay.tsx  # UI 오버레이 컨테이너
-│   │   ├── ScoreBoard.tsx   # 점수판
-│   │   ├── StartScreen.tsx  # 시작 화면
-│   │   ├── GameOverModal.tsx # 게임 오버 모달
-│   │   └── MobileControls.tsx # 모바일 버튼
-│   │
-│   ├── hooks/               # 커스텀 훅
-│   │   ├── useGameLoop.ts
-│   │   ├── useKeyboard.ts
-│   │   ├── useSwipe.ts
-│   │   └── useHighScore.ts
-│   │
-│   ├── engine/              # 게임 핵심 로직
-│   │   ├── gameReducer.ts   # 상태 관리 리듀서
-│   │   ├── collision.ts     # 충돌 감지
-│   │   └── renderer.ts      # Canvas 렌더링
-│   │
-│   ├── types/               # TypeScript 타입
-│   │   └── index.ts
-│   │
-│   ├── utils/               # 유틸리티 함수
-│   │   └── random.ts        # 랜덤 좌표 생성
-│   │
-│   ├── constants/           # 상수 정의
-│   │   └── config.ts
-│   │
-│   ├── styles/              # 스타일
-│   │   └── index.css
-│   │
-│   ├── App.tsx              # 루트 컴포넌트
-│   ├── GameEngine.tsx       # 게임 엔진 컴포넌트
-│   └── main.tsx             # 진입점
-│
-├── index.html
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-└── README.md
-```
-
----
-
-## 5. 타입 정의
-
-```typescript
-// types/index.ts
-
-/** 좌표 타입 */
-export interface Point {
-  x: number;
-  y: number;
-}
-
-/** 이동 방향 */
-export type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
-
-/** 게임 진행 상태 */
-export type GameStatus = 'IDLE' | 'PLAYING' | 'PAUSED' | 'GAME_OVER';
-
-/** 전체 게임 상태 (Reducer State) */
-export interface GameState {
-  status: GameStatus;
-  snake: Point[];           // 뱀 몸통 (0번이 머리)
-  food: Point;              // 먹이 위치
-  direction: Direction;     // 현재 방향
-  nextDirection: Direction; // 입력 버퍼 (다음 틱에 적용)
-  score: number;
-  level: number;
-  speed: number;            // 현재 속도 (ms)
-}
-
-/** Reducer Actions */
-export type GameAction =
-  | { type: 'START_GAME' }
-  | { type: 'PAUSE_GAME' }
-  | { type: 'RESUME_GAME' }
-  | { type: 'GAME_OVER' }
-  | { type: 'TICK' }
-  | { type: 'CHANGE_DIRECTION'; payload: Direction }
-  | { type: 'EAT_FOOD' }
-  | { type: 'RESTART' };
-
-/** 게임 설정 */
-export interface GameConfig {
-  boardSize: number;        // 그리드 크기 (20x20)
-  cellSize: number;         // 셀 픽셀 크기
-  initialSpeed: number;     // 초기 속도 (ms)
-  speedDecrement: number;   // 레벨업 시 속도 감소량
-  minSpeed: number;         // 최소 속도 (최대 난이도)
-  pointsPerFood: number;    // 먹이당 점수
-  pointsForLevelUp: number; // 레벨업 필요 점수
-}
-
-/** 키보드 핸들러 */
-export interface KeyboardHandlers {
-  onDirectionChange: (direction: Direction) => void;
-  onPause?: () => void;
-  onRestart?: () => void;
-}
-
-/** 스와이프 핸들러 */
-export interface SwipeHandlers {
-  left?: () => void;
-  right?: () => void;
-  up?: () => void;
-  down?: () => void;
-}
-```
-
----
-
-## 6. 게임 설정 상수
-
-```typescript
-// constants/config.ts
-
-export const GAME_CONFIG: GameConfig = {
-  boardSize: 20,           // 20x20 그리드
-  cellSize: 20,            // 각 셀 20px
-  initialSpeed: 150,       // 150ms (초기)
-  speedDecrement: 10,      // 레벨업 시 10ms 감소
-  minSpeed: 50,            // 최소 50ms (최고 난이도)
-  pointsPerFood: 10,       // 먹이당 10점
-  pointsForLevelUp: 50,    // 50점마다 레벨업
-};
-
-export const COLORS = {
-  background: '#1a1a2e',
-  grid: '#16213e',
-  snake: '#00ff88',
-  snakeHead: '#00cc6a',
-  food: '#ff6b6b',
-  text: '#ffffff',
-};
-
-export const INITIAL_SNAKE: Point[] = [
-  { x: 10, y: 10 },  // 머리
-  { x: 9, y: 10 },
-  { x: 8, y: 10 },
-];
-
-export const DIRECTION_VECTORS: Record<Direction, Point> = {
-  UP: { x: 0, y: -1 },
-  DOWN: { x: 0, y: 1 },
-  LEFT: { x: -1, y: 0 },
-  RIGHT: { x: 1, y: 0 },
-};
-
-export const OPPOSITE_DIRECTIONS: Record<Direction, Direction> = {
-  UP: 'DOWN',
-  DOWN: 'UP',
-  LEFT: 'RIGHT',
-  RIGHT: 'LEFT',
-};
-```
-
----
-
-## ✅ 아키텍처 체크리스트
-
-- [x] 컴포넌트 구조 정의
-- [x] 데이터 흐름 설계
-- [x] 커스텀 훅 설계
-- [x] 파일/폴더 구조 정의
-- [x] 타입 정의
-- [x] 게임 설정 상수 정의

package/template/stages/03-planning/outputs/implementation.yaml

@@ -1,209 +0,0 @@
-# Snake Game - Implementation Rules
-# 생성일: 2026-01-21
-# 스테이지: 03-planning
-
-project:
-  name: snake-game
-  type: game
-  framework: react
-  language: typescript
-
-# 컴포넌트 규칙
-components:
-  type: functional  # functional | class
-  naming: PascalCase
-  file_extension: tsx
-
-  # 컴포넌트 구조
-  structure:
-    - props_interface  # Props 인터페이스 정의
-    - component_function
-    - exports
-
-  # 컴포넌트 카테고리
-  categories:
-    - name: containers
-      path: src/
-      examples: [App.tsx, GameEngine.tsx]
-    - name: presentation
-      path: src/components/
-      examples: [CanvasLayer.tsx, ScoreBoard.tsx]
-    - name: ui
-      path: src/components/
-      examples: [GameOverModal.tsx, MobileControls.tsx]
-
-# 스타일링 규칙
-styling:
-  method: css-modules  # css-modules | tailwind | styled-components
-  naming: kebab-case
-  file_pattern: "{ComponentName}.module.css"
-
-  # 색상 변수 (CSS Custom Properties)
-  colors:
-    background: "#1a1a2e"
-    grid: "#16213e"
-    snake: "#00ff88"
-    snake_head: "#00cc6a"
-    food: "#ff6b6b"
-    text: "#ffffff"
-
-# 상태 관리
-state_management:
-  global: useReducer  # context | redux | zustand | useReducer
-  local: useState
-  refs: useRef  # 게임 루프, Canvas ref
-
-  # 상태 분리 원칙
-  principles:
-    - "UI 리렌더링 필요한 상태 → useReducer"
-    - "빠른 업데이트 필요한 상태 → useRef"
-    - "Canvas DOM 참조 → useRef"
-
-# 훅 규칙
-hooks:
-  naming: "use{Name}"
-  location: src/hooks/
-
-  # 커스텀 훅 목록
-  custom:
-    - name: useGameLoop
-      purpose: requestAnimationFrame 기반 게임 루프
-    - name: useKeyboard
-      purpose: 키보드 입력 처리
-    - name: useSwipe
-      purpose: 터치 스와이프 감지
-    - name: useHighScore
-      purpose: localStorage 최고점수 관리
-
-# 타입 정의 규칙
-types:
-  location: src/types/
-  naming: PascalCase
-
-  # 핵심 타입
-  core:
-    - Point
-    - Direction
-    - GameStatus
-    - GameState
-    - GameAction
-    - GameConfig
-
-# 상수 규칙
-constants:
-  location: src/constants/
-  naming: SCREAMING_SNAKE_CASE
-
-  # 핵심 상수
-  core:
-    - GAME_CONFIG
-    - COLORS
-    - INITIAL_SNAKE
-    - DIRECTION_VECTORS
-    - OPPOSITE_DIRECTIONS
-
-# 유틸리티 규칙
-utilities:
-  location: src/utils/
-  naming: camelCase
-
-  # 유틸리티 함수
-  functions:
-    - generateRandomPosition
-    - isCollision
-    - isValidDirection
-
-# 폴더 구조
-folder_structure:
-  type: type-based  # feature-based | type-based
-
-  structure:
-    src:
-      - components/  # React 컴포넌트
-      - hooks/       # 커스텀 훅
-      - engine/      # 게임 로직 (reducer, collision, renderer)
-      - types/       # TypeScript 타입
-      - constants/   # 상수
-      - utils/       # 유틸리티 함수
-      - styles/      # 글로벌 스타일
-      - assets/      # 정적 자산
-
-# 파일 명명 규칙
-file_naming:
-  components: PascalCase.tsx
-  hooks: camelCase.ts
-  types: index.ts  # 단일 파일 또는 camelCase.ts
-  constants: camelCase.ts
-  utils: camelCase.ts
-  styles: index.css 또는 {Component}.module.css
-
-# 임포트 규칙
-imports:
-  order:
-    - react  # React 관련
-    - external  # 외부 라이브러리
-    - internal  # 내부 모듈 (절대 경로)
-    - relative  # 상대 경로
-    - styles  # 스타일
-    - types  # 타입
-
-  alias:
-    "@": src/
-
-# 코드 품질
-code_quality:
-  eslint: true
-  prettier: true
-  typescript_strict: true
-
-  rules:
-    - "no-any: 가능한 한 any 타입 사용 금지"
-    - "explicit-return-types: 함수 반환 타입 명시"
-    - "no-unused-vars: 미사용 변수 금지"
-
-# 테스트 규칙
-testing:
-  framework: vitest
-  location: src/__tests__/ 또는 컴포넌트 옆 {name}.test.ts
-
-  coverage_target: 80%
-
-  naming:
-    unit: "{name}.test.ts"
-    e2e: "{feature}.e2e.ts"
-
-# 성능 규칙
-performance:
-  # Canvas 최적화
-  canvas:
-    - "requestAnimationFrame 사용"
-    - "오프스크린 캔버스 고려"
-    - "불필요한 리렌더링 방지"
-
-  # React 최적화
-  react:
-    - "React.memo 필요시 사용"
-    - "useCallback/useMemo 과도한 사용 자제"
-    - "게임 상태는 useRef로 관리"
-
-# Git 커밋 규칙
-git:
-  conventional_commits: true
-
-  types:
-    feat: 새 기능
-    fix: 버그 수정
-    refactor: 리팩토링
-    test: 테스트
-    docs: 문서
-    style: 포맷팅
-    chore: 기타
-
-# 금지 사항
-prohibited:
-  - "외부 게임 엔진 (Phaser, PixiJS 등)"
-  - "jQuery"
-  - "Class 컴포넌트 (함수형만 사용)"
-  - "any 타입 남용"
-  - "전역 변수"
-  - "setInterval (requestAnimationFrame 대신 사용)"