create-ax-project 1.0.0

package/template/stages/05-task-management/templates/parallel_groups.yaml

@@ -0,0 +1,153 @@
+# Parallel Task Groups Configuration
+# ax-templates-3 병렬 태스크 관리 (Issue #9 해결)
+
+parallel_execution:
+  # 병렬 실행 활성화 여부
+  enabled: true
+
+  # 기본 규칙
+  default_mode: "sequential"  # sequential | parallel_when_safe
+
+# 의존성 분석 규칙
+dependency_analysis:
+  # 의존성 없는 태스크 자동 그룹화
+  auto_group_independent: true
+
+  # 의존성 유형
+  dependency_types:
+    - type: "blocks"
+      description: "완료되어야 다음 태스크 시작 가능"
+
+    - type: "informs"
+      description: "참조하지만 블로킹 아님"
+
+    - type: "none"
+      description: "완전 독립"
+
+# 병렬 그룹 템플릿
+parallel_groups:
+  # 예시: 스프린트 1 태스크 그룹
+  sprint_1:
+    # 그룹 A: 병렬 실행 가능
+    group_a:
+      tasks:
+        - "TASK-001: 프로젝트 초기 설정"
+        - "TASK-002: 환경 변수 설정"
+        - "TASK-003: ESLint/Prettier 설정"
+      parallel: true
+      reason: "독립적인 설정 작업들"
+
+    # 그룹 B: 그룹 A 완료 후 병렬 실행
+    group_b:
+      depends_on: ["group_a"]
+      tasks:
+        - "TASK-004: 레이아웃 컴포넌트"
+        - "TASK-005: 네비게이션 컴포넌트"
+        - "TASK-006: 푸터 컴포넌트"
+      parallel: true
+      reason: "공통 컴포넌트, 상호 의존성 없음"
+
+    # 그룹 C: 순차 실행 필요
+    group_c:
+      depends_on: ["group_b"]
+      tasks:
+        - "TASK-007: API 클라이언트 설정"
+        - "TASK-008: 인증 서비스 구현"
+        - "TASK-009: 보호된 라우트 설정"
+      parallel: false
+      reason: "순차적 의존성 있음"
+
+# 병렬 실행 규칙
+execution_rules:
+  # 병렬 실행 가능 조건
+  parallel_allowed_when:
+    - "no_shared_files"           # 동일 파일 수정 없음
+    - "no_data_dependency"        # 데이터 의존성 없음
+    - "different_modules"         # 다른 모듈
+    - "explicit_parallel_flag"    # 명시적 병렬 플래그
+
+  # 병렬 실행 금지 조건
+  parallel_prohibited_when:
+    - "same_file_modification"    # 동일 파일 수정
+    - "database_migration"        # DB 마이그레이션
+    - "sequential_dependency"     # 순차 의존성
+    - "shared_state"              # 공유 상태
+
+# 태스크 분류 가이드
+classification_guide:
+  # 병렬 가능 태스크 유형
+  parallelizable:
+    - "독립적인 UI 컴포넌트 구현"
+    - "서로 다른 모듈의 유틸리티 함수"
+    - "독립적인 테스트 작성"
+    - "문서 작성"
+    - "환경 설정 (충돌 없는 경우)"
+
+  # 순차 필수 태스크 유형
+  sequential_required:
+    - "데이터베이스 스키마 변경"
+    - "인증/인가 흐름"
+    - "API 엔드포인트 → 클라이언트 통합"
+    - "의존성 있는 컴포넌트 체인"
+    - "버전 업그레이드"
+
+# 시각화 형식
+visualization:
+  # 의존성 그래프 형식
+  graph_format: "mermaid"
+
+  # 예시 출력
+  example: |
+    ```mermaid
+    graph LR
+      A[TASK-001] --> D[TASK-004]
+      B[TASK-002] --> D
+      C[TASK-003] --> D
+      D --> G[TASK-007]
+      E[TASK-005] --> G
+      F[TASK-006] --> G
+      G --> H[TASK-008]
+      H --> I[TASK-009]
+
+      subgraph "그룹 A (병렬)"
+        A
+        B
+        C
+      end
+
+      subgraph "그룹 B (병렬)"
+        D
+        E
+        F
+      end
+
+      subgraph "그룹 C (순차)"
+        G
+        H
+        I
+      end
+    ```
+
+# 실행 최적화
+optimization:
+  # 동시 실행 최대 수
+  max_concurrent_tasks: 3
+
+  # 리소스 제한
+  resource_limits:
+    cpu_intensive_concurrent: 2
+    io_intensive_concurrent: 5
+
+  # 우선순위 기반 스케줄링
+  priority_scheduling: true
+
+# 모니터링
+monitoring:
+  # 진행 상황 추적
+  track_parallel_progress: true
+
+  # 병목 감지
+  detect_bottlenecks: true
+
+  # 완료 알림
+  notify_on_group_complete: true

package/template/stages/05-task-management/templates/task_schema.yaml

@@ -0,0 +1,154 @@
+# Task Schema Definition
+# ax-templates-3 태스크 관리 스키마 (Issue #4, #6, #8, #16 해결)
+
+schema:
+  name: "Project Tasks"
+  version: "1.0.0"
+
+# 필수 필드 정의
+fields:
+  # 태스크 이름 (Title)
+  - name: "Task Name"
+    type: "title"
+    required: true
+    description: "태스크 제목"
+
+  # 상태 필드 (Issue #16: Status 필드 필수!)
+  - name: "Status"
+    type: "select"
+    required: true
+    default: "To Do"
+    options:
+      - name: "To Do"
+        color: "gray"
+      - name: "In Progress"
+        color: "blue"
+      - name: "Review"
+        color: "yellow"
+      - name: "Done"
+        color: "green"
+      - name: "Blocked"
+        color: "red"
+
+  # 우선순위
+  - name: "Priority"
+    type: "select"
+    required: false
+    default: "Medium"
+    options:
+      - name: "High"
+        color: "red"
+      - name: "Medium"
+        color: "yellow"
+      - name: "Low"
+        color: "green"
+
+  # 정렬용 순서 (Issue #5, #6, #8 해결)
+  - name: "Order"
+    type: "number"
+    required: true
+    description: "태스크 순서 (정렬용)"
+    auto_increment: true
+
+  # 스프린트
+  - name: "Sprint"
+    type: "select"
+    required: false
+    options:
+      - name: "Sprint 1"
+      - name: "Sprint 2"
+      - name: "Sprint 3"
+
+  # 담당자
+  - name: "Assignee"
+    type: "text"
+    required: false
+
+  # 예상 시간
+  - name: "Estimate"
+    type: "text"
+    required: false
+    description: "예상 소요 시간 (예: 2h, 1d)"
+
+  # 마감일
+  - name: "Due Date"
+    type: "date"
+    required: false
+
+  # 의존성
+  - name: "Depends On"
+    type: "text"
+    required: false
+    description: "선행 태스크 ID (콤마로 구분)"
+
+  # 스테이지
+  - name: "Stage"
+    type: "select"
+    required: false
+    options:
+      - name: "06-implementation"
+      - name: "07-refactoring"
+      - name: "08-qa"
+      - name: "09-testing"
+
+# 태스크 생성 규칙 (Issue #6, #8 해결: 순차 생성!)
+creation_rules:
+  # 병렬 생성 금지 - 순서 보장
+  mode: "sequential"
+  batch_size: 1
+
+  # 순차 생성 절차
+  procedure:
+    - step: 1
+      action: "create_single_task"
+      description: "단일 태스크 생성"
+    - step: 2
+      action: "verify_order_field"
+      description: "Order 필드 확인"
+    - step: 3
+      action: "create_next_task"
+      description: "다음 태스크 생성 (Order + 1)"
+
+  # 금지 사항
+  prohibited:
+    - "batch_create"      # 일괄 생성 금지
+    - "parallel_create"   # 병렬 생성 금지
+
+  # 권장 사항
+  recommended:
+    - "explicit_order"    # 명시적 Order 값 지정
+    - "status_to_do"      # Status = "To Do"로 생성
+    - "sequential_naming" # 순차적 이름 부여
+
+# Notion 데이터베이스 생성 템플릿
+notion_template:
+  database_name: "{{PROJECT_NAME}} Tasks"
+
+  properties:
+    - "Task Name"    # title
+    - "Status"       # select (필수!)
+    - "Priority"     # select
+    - "Order"        # number (정렬용!)
+    - "Sprint"       # select
+    - "Assignee"     # text
+    - "Estimate"     # text
+    - "Due Date"     # date
+    - "Depends On"   # text
+    - "Stage"        # select
+
+  # 기본 뷰 설정
+  views:
+    - name: "Board View"
+      type: "board"
+      group_by: "Status"
+
+    - name: "List View"
+      type: "table"
+      sort_by: "Order"
+      sort_direction: "ascending"
+
+    - name: "Sprint View"
+      type: "board"
+      group_by: "Sprint"
+      filter:
+        - "Status != Done"

package/template/stages/06-implementation/CLAUDE.md

@@ -0,0 +1,163 @@
+# Stage 06: Implementation
+
+핵심 기능 구현 단계
+
+## 🎭 페르소나: Precise Builder
+
+> 당신은 Precise Builder입니다.
+> 정확하고 유지보수 가능한 코드를 작성하세요.
+> 에러를 미리 예방하고, 테스트하기 쉬운 구조를 만드세요.
+
+### 특성
+- 정확한 구현
+- 에러 방지
+- 테스트 가능한 코드
+- 클린 코드
+
+### 권장 행동
+- 명확하고 읽기 쉬운 코드
+- 에러 핸들링
+- 타입 안전성
+- 테스트 용이성
+
+### 지양 행동
+- 오버 엔지니어링
+- 매직 넘버/문자열
+- 에러 무시
+- 복잡한 로직
+
+### AI 설정
+- **Temperature**: 0.3 (높은 정밀도)
+- **정밀도**: High
+
+## 실행 모델
+- **Primary**: ClaudeCode (코드 생성)
+- **Mode**: Plan + Sandbox - 안전한 코드 실행
+
+## 목표
+1. 프로젝트 스캐폴딩
+2. 핵심 기능 구현
+3. 데이터베이스 연동
+4. API 구현
+
+## 입력 파일
+- `../05-task-management/outputs/tasks.md`
+- `../03-planning/outputs/architecture.md`
+- `../03-planning/outputs/implementation.yaml` - **구현 규칙 (필수 참조!)**
+- `../04-ui-ux/outputs/design_system.md`
+- `../05-task-management/HANDOFF.md`
+
+### ⚠️ implementation.yaml 준수 필수
+구현 전 `implementation.yaml` 파일을 읽고 다음 규칙을 확인하세요:
+- 컴포넌트 타입/export 방식
+- 스타일링 접근 방식
+- 상태 관리 패턴
+- 네이밍 규칙
+- 폴더 구조
+- 금지/권장 사항
+
+## 출력 파일
+- `outputs/source_code/` - 소스 코드 디렉토리
+- `outputs/implementation_log.md` - 구현 로그
+- `HANDOFF.md` - 다음 스테이지 인계 문서
+
+## 워크플로우
+
+### 1. 프로젝트 초기화
+```bash
+# 예: Next.js 프로젝트
+npx create-next-app@latest project-name
+cd project-name
+```
+
+### 2. 공통 컴포넌트 구현
+- 디자인 시스템 기반 UI 컴포넌트
+- 레이아웃 컴포넌트
+- 유틸리티 함수
+
+### 3. 기능 구현
+- 스프린트 1 태스크 순차 구현
+- 각 태스크 완료 시 커밋
+- 구현 로그 업데이트
+
+### 4. 통합
+- API 연동
+- 데이터베이스 연결
+- 인증/인가 구현
+
+## 체크포인트 규칙
+- **필수**: 이 스테이지는 체크포인트가 필수입니다
+- 스프린트 완료마다 체크포인트 생성
+- 주요 기능 완료 시 체크포인트 생성
+
+## 구현 원칙
+1. 작은 단위로 커밋
+2. 테스트 가능한 코드 작성
+3. 에러 핸들링 포함
+4. 타입 안전성 확보 (TypeScript)
+
+---
+
+## ⚠️ Test-First 플로우 (필수)
+
+> **중요**: 버그 조기 발견을 위해 구현 완료 후 반드시 스모크 테스트를 실행하세요.
+> Snake Game 프로젝트에서 이 단계를 건너뛰어 버그가 2개 스테이지를 통과한 사례가 있습니다.
+
+### 구현 완료 후 필수 테스트
+
+```bash
+# 1. 개발 서버 실행 확인
+npm run dev
+# 브라우저에서 기본 동작 확인
+
+# 2. 정적 분석
+npm run lint
+
+# 3. 타입 체크
+npm run typecheck
+
+# 4. Playwright 스모크 테스트 (설정되어 있다면)
+npx playwright test --grep @smoke
+```
+
+### 테스트 실패 시 조치
+1. **lint 오류**: 즉시 수정
+2. **typecheck 오류**: 타입 정의 수정
+3. **런타임 오류**: 버그로 기록하고 수정
+4. **UI 동작 이상**: 버그 ID 부여 (예: BUG-001)
+
+### 버그 기록 형식
+```markdown
+### BUG-001: [버그 제목]
+- **발견 시점**: 06-implementation 스모크 테스트
+- **증상**: [증상 설명]
+- **원인**: [원인 분석]
+- **수정 파일**: [파일 경로]
+- **상태**: 수정됨 / 미수정
+```
+
+### HANDOFF.md 테스트 섹션 필수
+HANDOFF.md에 반드시 테스트 결과 섹션을 포함하세요:
+- 실행한 테스트 목록
+- 테스트 결과 (통과/실패)
+- 발견된 버그 (있다면)
+- 버그 수정 상태
+
+---
+
+## 완료 조건
+- [ ] 프로젝트 스캐폴딩 완료
+- [ ] 공통 컴포넌트 구현
+- [ ] 핵심 기능 구현 (스프린트 1-2)
+- [ ] API 엔드포인트 구현
+- [ ] **스모크 테스트 실행** (Test-First)
+- [ ] **lint/typecheck 통과**
+- [ ] 체크포인트 생성
+- [ ] HANDOFF.md 생성 (테스트 결과 포함)
+
+## 다음 스테이지
+→ **07-refactoring**: 코드 품질 개선 및 최적화
+
+
+
+

package/template/stages/06-implementation/HANDOFF.md

@@ -0,0 +1,184 @@
+# HANDOFF: 06-implementation → 07-refactoring
+
+> 생성일: 2026-01-21
+> 프로젝트: snake-game
+> 현재 스테이지: 06-implementation (완료)
+> 다음 스테이지: 07-refactoring
+
+---
+
+## ✅ 완료된 작업
+
+### Sprint 1: 프로젝트 설정 + 코어 로직
+- [x] TASK-001: Vite + React + TS 프로젝트 초기화
+- [x] TASK-002: 타입 정의 (types/index.ts)
+- [x] TASK-003: 상수 정의 (constants/config.ts)
+- [x] TASK-004: 글로벌 스타일 (styles/index.css)
+- [x] TASK-005: useGameLoop 훅
+- [x] TASK-006: gameReducer
+- [x] TASK-007: collision.ts
+- [x] TASK-008: renderer.ts
+- [x] TASK-009: random.ts
+- [x] TASK-016: useKeyboard 훅
+
+### Sprint 2: UI 컴포넌트 + 통합
+- [x] TASK-010: GameEngine 통합
+- [x] TASK-011: CanvasLayer 컴포넌트
+- [x] TASK-012: ScoreBoard 컴포넌트
+- [x] TASK-013: StartScreen 컴포넌트
+- [x] TASK-014: GameOverModal 컴포넌트
+- [x] TASK-020: useHighScore 훅
+- [x] TASK-021: 일시정지 기능
+
+---
+
+## 📁 생성된 파일
+
+### 타입 및 상수
+| 파일 | 설명 |
+|------|------|
+| `src/types/index.ts` | 모든 게임 타입 정의 |
+| `src/constants/config.ts` | 게임 설정, 키 매핑, 색상 등 |
+
+### 엔진
+| 파일 | 설명 |
+|------|------|
+| `src/engine/gameReducer.ts` | 게임 상태 관리 리듀서 |
+| `src/engine/collision.ts` | 충돌 감지 함수 |
+| `src/engine/renderer.ts` | Canvas 렌더링 함수 |
+
+### 훅
+| 파일 | 설명 |
+|------|------|
+| `src/hooks/useGameLoop.ts` | requestAnimationFrame 기반 게임 루프 |
+| `src/hooks/useKeyboard.ts` | 키보드 입력 처리 |
+| `src/hooks/useHighScore.ts` | 최고 점수 localStorage 관리 |
+
+### 유틸리티
+| 파일 | 설명 |
+|------|------|
+| `src/utils/random.ts` | 랜덤 위치 생성 함수 |
+
+### 컴포넌트
+| 파일 | 설명 |
+|------|------|
+| `src/components/CanvasLayer.tsx` | Canvas 래퍼 컴포넌트 |
+| `src/components/ScoreBoard.tsx` | 점수판 컴포넌트 |
+| `src/components/StartScreen.tsx` | 시작 화면 오버레이 |
+| `src/components/GameOverModal.tsx` | 게임 오버 모달 |
+| `src/GameEngine.tsx` | 메인 게임 통합 컴포넌트 |
+
+### 스타일
+| 파일 | 설명 |
+|------|------|
+| `src/styles/index.css` | 글로벌 스타일 (Neon Arcade 테마) |
+| `src/components/*.module.css` | 컴포넌트별 CSS Modules |
+
+---
+
+## 🎮 구현된 기능
+
+### 핵심 기능
+- ✅ 방향키/WASD로 뱀 조작
+- ✅ 먹이 먹으면 뱀 성장 + 점수 증가
+- ✅ 벽/자기 몸 충돌 시 게임 오버
+- ✅ 점수 표시 (현재 점수, 레벨, 최고 점수)
+- ✅ 게임 재시작 기능
+
+### 추가 기능
+- ✅ 레벨 시스템 (점수에 따른 속도 증가)
+- ✅ 최고 점수 localStorage 저장
+- ✅ 일시정지/재개 (Space 키)
+- ✅ Neon Arcade 테마 UI
+
+---
+
+## 🏗️ 아키텍처
+
+```
+App.tsx
+└── GameEngine.tsx (메인 컨트롤러)
+    ├── useReducer(gameReducer) - 상태 관리
+    ├── useGameLoop() - 게임 루프
+    ├── useKeyboard() - 입력 처리
+    ├── useHighScore() - 점수 저장
+    │
+    ├── ScoreBoard - 점수 표시
+    ├── CanvasLayer - 게임 렌더링
+    │   └── renderer.ts - Canvas 그리기
+    ├── StartScreen - 시작 화면
+    └── GameOverModal - 게임 오버
+```
+
+---
+
+## 🧪 검증 결과
+
+| 항목 | 상태 | 비고 |
+|------|------|------|
+| TypeScript 컴파일 | ✅ 통과 | `npm run build` |
+| 번들 크기 | ✅ 204KB | 목표 200KB 근접 |
+| 게임 플레이 | ✅ 동작 | 모든 기능 정상 |
+| 키보드 입력 | ✅ 동작 | Arrow, WASD, Space |
+| 충돌 감지 | ✅ 동작 | 벽, 자기 몸, 먹이 |
+| 점수 저장 | ✅ 동작 | localStorage |
+
+---
+
+## 🔧 07-refactoring 권장 작업
+
+### 1. 코드 최적화
+- [ ] `renderer.ts`: 불필요한 재렌더링 방지
+- [ ] `gameReducer.ts`: 상태 업데이트 최적화
+- [ ] 컴포넌트 메모이제이션 (React.memo)
+
+### 2. 코드 품질
+- [ ] ESLint 경고 해결
+- [ ] 미사용 import 제거
+- [ ] 상수 매직 넘버 추출
+
+### 3. 성능 개선
+- [ ] Canvas 더블 버퍼링 고려
+- [ ] 게임 루프 최적화 (프레임 스킵 방지)
+
+### 4. 모바일 지원 (Sprint 3)
+- [ ] useSwipe 훅 구현
+- [ ] MobileControls 컴포넌트 추가
+- [ ] 터치 이벤트 처리
+
+---
+
+## 🎯 마일스톤 상태
+
+| 마일스톤 | 상태 | 체크포인트 |
+|---------|------|-----------|
+| M1: MVP 기반 | ✅ 완료 | - |
+| M2: MVP 완성 | ✅ 완료 | `checkpoint_m2_mvp` |
+| M3: 품질 개선 | ⏳ 진행 전 | - |
+| M4: 배포 | ⏳ 진행 전 | - |
+
+---
+
+## 🚀 다음 단계
+
+```bash
+# 07-refactoring 스테이지 실행
+/run-stage 07-refactoring
+
+# 또는
+/refactor
+```
+
+---
+
+## 📊 AI 호출 기록
+
+| AI | 호출 시간 | 작업 | 결과 |
+|----|----------|------|------|
+| ClaudeCode | 13:10~14:30 | Sprint 1+2 구현 | 성공 |
+
+---
+
+**생성자**: ClaudeCode
+**검토자**: -
+**승인**: 대기