create-ax-project 1.0.0

package/template/stages/01-brainstorm/HANDOFF.md

@@ -0,0 +1,110 @@
+# HANDOFF: 01-brainstorm → 02-research
+
+> 생성일: 2026-01-21
+> 프로젝트: snake-game
+> 현재 스테이지: 01-brainstorm (완료)
+> 다음 스테이지: 02-research
+
+---
+
+## ✅ 완료된 작업
+
+- [x] 프로젝트 브리프 작성 (`inputs/project_brief.md`)
+- [x] 핵심 기능 아이디어 12개 브레인스토밍
+- [x] 사용자 페르소나 3개 정의
+- [x] 유사 프로젝트 사례 조사
+- [x] 장단점 분석 완료
+- [x] MVP 범위 제안
+
+---
+
+## 📋 핵심 결정사항
+
+### 1. 기술 스택 방향
+- **렌더링**: Canvas (성능 우선, 모바일 지원)
+- **상태관리**: useReducer + Custom Hook
+- **게임 루프**: requestAnimationFrame
+
+### 2. MVP 기능 범위
+| 우선순위 | 기능 |
+|---------|------|
+| 🔴 필수 | 기본 조작, 먹이 시스템, 충돌 감지, 점수, 재시작 |
+| 🟡 중요 | 레벨 시스템, 하이스코어 저장, 일시정지, 모바일 터치 |
+| 🟢 선택 | Combo System, Portal Edges, Different Food |
+
+### 3. 타겟 사용자 (우선순위)
+1. **Persona A**: 캐주얼 게이머 (모바일, 5-10분 플레이)
+2. **Persona B**: 경쟁적 게이머 (데스크톱, 하이스코어 추구)
+3. **Persona C**: 레트로 팬 (클래식 스타일 선호)
+
+---
+
+## 📁 생성된 산출물
+
+| 파일 | 설명 |
+|------|------|
+| `inputs/project_brief.md` | 프로젝트 개요 및 요구사항 |
+| `outputs/ideas.md` | 브레인스토밍 아이디어 (12개) |
+| `outputs/requirements_analysis.md` | 요구사항 분석 |
+| `HANDOFF.md` | 이 문서 |
+
+---
+
+## 🔜 다음 스테이지 즉시 실행 작업
+
+### 02-research에서 조사할 항목
+
+1. **Canvas 게임 루프 구현 방법**
+   - requestAnimationFrame vs setInterval
+   - 최적화 기법 (더블 버퍼링)
+
+2. **React + Canvas 통합 패턴**
+   - useRef로 Canvas 접근
+   - Canvas 리렌더링 최소화
+
+3. **모바일 터치 이벤트 처리**
+   - touchstart/touchmove/touchend
+   - 스와이프 방향 감지 로직
+
+4. **localStorage 하이스코어 저장**
+   - 데이터 구조 설계
+   - 보안 고려사항
+
+5. **충돌 감지 알고리즘**
+   - O(n) 자기 몸 충돌
+   - 최적화 방안
+
+---
+
+## ⚠️ 주의사항
+
+1. **외부 게임 엔진 미사용**: Phaser, PixiJS 등 금지
+2. **순수 React 구현**: jQuery 미사용
+3. **정적 배포 가능**: 백엔드 서버 없음
+
+---
+
+## 📊 AI 호출 기록
+
+| AI | 시간 | 프롬프트 | 결과 | 상태 |
+|----|------|---------|------|------|
+| Gemini | 11:58 | Snake Game 브레인스토밍 | 12개 아이디어, 3 페르소나 | ✅ |
+| ClaudeCode | 11:57 | 결과 구조화 | ideas.md, HANDOFF.md | ✅ |
+
+---
+
+## 🚀 다음 단계
+
+```bash
+# 다음 스테이지 실행
+/run-stage 02-research
+
+# 또는
+/research
+```
+
+---
+
+**생성자**: ClaudeCode
+**검토자**: -
+**승인**: 대기

package/template/stages/01-brainstorm/HANDOFF.md.template

@@ -0,0 +1,112 @@
+# Stage Handoff: 01-brainstorm → 02-research
+
+**생성일**: {{TIMESTAMP}}
+**생성자**: {{MODEL}}
+**소요 시간**: {{DURATION}}
+
+---
+
+## 완료된 작업
+
+- [ ] 프로젝트 브리프 분석
+- [ ] 브레인스토밍 ({{IDEA_COUNT}}개 아이디어)
+- [ ] 사용자 페르소나 생성 ({{PERSONA_COUNT}}개)
+- [ ] 요구사항 분석
+- [ ] MVP 범위 정의
+- [ ] HANDOFF.md 생성
+
+---
+
+## 다음 에이전트를 위한 컨텍스트
+
+### 핵심 결정사항
+
+| 결정 | 이유 | 되돌릴 수 있음 |
+|------|------|----------------|
+| {{DECISION_1}} | {{REASON_1}} | Yes/No |
+| {{DECISION_2}} | {{REASON_2}} | Yes/No |
+
+### 성공한 접근법
+- {{SUCCESSFUL_APPROACH_1}}
+- {{SUCCESSFUL_APPROACH_2}}
+
+### 실패한 접근법
+- {{FAILED_APPROACH_1}}: {{FAILURE_REASON_1}}
+
+### 우선순위 아이디어 (Top 5)
+1. **{{IDEA_1}}** - {{IDEA_1_VALUE}}
+2. **{{IDEA_2}}** - {{IDEA_2_VALUE}}
+3. **{{IDEA_3}}** - {{IDEA_3_VALUE}}
+4. **{{IDEA_4}}** - {{IDEA_4_VALUE}}
+5. **{{IDEA_5}}** - {{IDEA_5_VALUE}}
+
+### MVP 핵심 기능
+1. {{MVP_FEATURE_1}}
+2. {{MVP_FEATURE_2}}
+3. {{MVP_FEATURE_3}}
+
+---
+
+## 생성된 산출물
+
+| 파일 | 설명 | 위치 |
+|------|------|------|
+| ideas.md | 브레인스토밍 아이디어 | `outputs/ideas.md` |
+| requirements_analysis.md | 요구사항 분석 | `outputs/requirements_analysis.md` |
+| personas.md | 사용자 페르소나 | `outputs/personas.md` (선택) |
+
+---
+
+## 02-research 스테이지 가이드
+
+### 즉시 실행할 작업
+1. `outputs/requirements_analysis.md` 읽고 MVP 범위 확인
+2. 우선순위 아이디어 기술 스택 리서치
+3. 경쟁사 심층 분석
+
+### 리서치 우선순위
+1. {{RESEARCH_PRIORITY_1}}
+2. {{RESEARCH_PRIORITY_2}}
+3. {{RESEARCH_PRIORITY_3}}
+
+### 검증 필요 가정
+- {{ASSUMPTION_1}}
+- {{ASSUMPTION_2}}
+
+### 권장 MCP 서버
+- `firecrawl`: 웹 크롤링
+- `exa`: AI 검색
+- `context7`: 문서 검색
+
+---
+
+## 체크포인트 참조
+> 이 스테이지는 체크포인트가 필요하지 않습니다.
+
+---
+
+## AI 호출 기록
+
+| AI | 호출 시간 | 프롬프트 | 결과 | 상태 |
+|----|----------|---------|------|------|
+| {{AI_1}} | {{TIME_1}} | {{PROMPT_1}} | {{OUTPUT_1}} | {{STATUS_1}} |
+| {{AI_2}} | {{TIME_2}} | {{PROMPT_2}} | {{OUTPUT_2}} | {{STATUS_2}} |
+
+> 설정: `config/ai_logging.yaml`
+
+---
+
+## 메타데이터
+
+```yaml
+stage: "01-brainstorm"
+status: "completed"
+next_stage: "02-research"
+models_used:
+  - gemini
+  - claudecode
+tokens_used: {{TOKENS_USED}}
+outputs_generated:
+  - ideas.md
+  - requirements_analysis.md
+```

package/template/stages/01-brainstorm/README.md

@@ -0,0 +1,97 @@
+# Stage 01: Brainstorming
+
+발산적 아이디어 생성 및 요구사항 탐색
+
+## 개요
+
+이 스테이지는 프로젝트의 시작점으로, 창의적 아이디어 발산과 초기 요구사항 분석을 수행합니다.
+
+## 실행 모델
+
+| 역할 | 모델 | 목적 |
+|------|------|------|
+| Primary | Gemini | 창의적 아이디어 생성, 웹 리서치 |
+| Secondary | ClaudeCode | 구조화, 실현 가능성 검토 |
+
+## 시작하기
+
+### 1. 입력 파일 준비
+
+```bash
+# 프로젝트 브리프 작성
+cp templates/project_brief.md inputs/project_brief.md
+# 편집 후 내용 채우기
+```
+
+### 2. 스테이지 실행
+
+```bash
+# 방법 1: 슬래시 커맨드
+/run-stage 01-brainstorm
+
+# 방법 2: 스크립트 직접 실행
+../../scripts/run-stage.sh 01-brainstorm
+```
+
+### 3. 수동 워크플로우
+
+```bash
+# Step 1: Gemini로 아이디어 발산
+/gemini "$(cat prompts/ideation.md)"
+
+# Step 2: 결과를 outputs/ideas.md에 저장
+
+# Step 3: 요구사항 분석
+# ClaudeCode가 자동 수행
+
+# Step 4: HANDOFF.md 생성
+/handoff
+```
+
+## 디렉토리 구조
+
+```
+01-brainstorm/
+├── README.md           # 이 파일
+├── CLAUDE.md           # AI 지침
+├── config.yaml         # 스테이지 설정
+├── prompts/
+│   ├── ideation.md     # 아이디어 발산 프롬프트
+│   ├── persona.md      # 페르소나 생성 프롬프트
+│   └── requirements.md # 요구사항 분석 프롬프트
+├── templates/
+│   ├── ideas.md        # 아이디어 출력 템플릿
+│   └── requirements_analysis.md  # 요구사항 출력 템플릿
+├── inputs/             # 입력 파일
+├── outputs/            # 출력 파일
+├── HANDOFF.md.template # 핸드오프 템플릿
+└── HANDOFF.md          # 생성된 핸드오프 (완료 시)
+```
+
+## 완료 조건
+
+- [ ] 최소 10개 아이디어 생성
+- [ ] 3개 이상 사용자 페르소나 정의
+- [ ] 요구사항 분석 문서 완성
+- [ ] MVP 범위 정의
+- [ ] HANDOFF.md 생성
+
+## 출력물
+
+| 파일 | 설명 |
+|------|------|
+| `outputs/ideas.md` | 브레인스토밍 아이디어 목록 |
+| `outputs/requirements_analysis.md` | 요구사항 분석 결과 |
+| `outputs/personas.md` | 사용자 페르소나 (선택) |
+| `HANDOFF.md` | 다음 스테이지 인계 문서 |
+
+## 다음 스테이지
+
+**→ 02-research**: 기술 리서치 및 시장 분석
+
+## 팁
+
+1. **발산적 사고**: 이 단계에서는 아이디어 제한 없이 자유롭게
+2. **모든 것을 기록**: 나중에 재검토할 수 있도록
+3. **Gemini 활용**: 웹 검색이 필요한 경쟁사 분석에 활용
+4. **구조화는 나중에**: ClaudeCode가 구조화 담당

package/template/stages/01-brainstorm/config.yaml

@@ -0,0 +1,92 @@
+# Stage 01: Brainstorming Configuration
+
+stage:
+  id: "01-brainstorm"
+  name: "Brainstorming"
+  description: "발산적 아이디어 생성 및 요구사항 탐색"
+
+# Model Assignment
+models:
+  primary: "gemini"
+  secondary: "claudecode"
+  collaboration: "parallel"  # parallel | sequential | handoff
+
+# AI 자동 호출 설정 (Issue #12 해결)
+auto_invoke:
+  enabled: true
+  model: "gemini"
+  trigger: "stage_start"
+  prompt_file: "prompts/ideation.md"
+  wrapper: "scripts/gemini-wrapper.sh"
+  required: true
+  message: "🤖 Gemini 자동 호출: 발산적 아이디어 생성 시작"
+
+# Execution Mode
+execution:
+  mode: "yolo"
+  container: true
+  sandbox: false
+  timeout: 3600  # 1 hour
+
+# Input/Output Definitions
+inputs:
+  required:
+    - name: "project_brief.md"
+      description: "프로젝트 개요 및 목표"
+      schema: null
+  optional:
+    - name: "user_requirements.md"
+      description: "초기 사용자 요구사항"
+    - name: "reference_materials/"
+      description: "참고 자료 디렉토리"
+
+outputs:
+  required:
+    - name: "ideas.md"
+      description: "브레인스토밍 아이디어 목록"
+      template: "templates/ideas.md"
+    - name: "requirements_analysis.md"
+      description: "요구사항 분석 결과"
+      template: "templates/requirements_analysis.md"
+    - name: "HANDOFF.md"
+      description: "다음 스테이지 인계 문서"
+      template: "HANDOFF.md.template"
+  optional:
+    - name: "personas.md"
+      description: "사용자 페르소나"
+    - name: "competitive_analysis.md"
+      description: "경쟁사 분석"
+
+# Prompts
+prompts:
+  - name: "ideation"
+    file: "prompts/ideation.md"
+    model: "gemini"
+    description: "발산적 아이디어 생성"
+  - name: "persona"
+    file: "prompts/persona.md"
+    model: "gemini"
+    description: "사용자 페르소나 생성"
+  - name: "requirements"
+    file: "prompts/requirements.md"
+    model: "claudecode"
+    description: "요구사항 분석 및 구조화"
+
+# Completion Criteria
+completion:
+  checklist:
+    - "최소 10개 아이디어 생성"
+    - "3개 이상 사용자 페르소나 정의"
+    - "요구사항 분석 문서 완성"
+    - "HANDOFF.md 생성"
+  validation:
+    min_ideas: 10
+    min_personas: 3
+    require_handoff: true
+
+# Transition
+transition:
+  next_stage: "02-research"
+  prerequisites: []
+  handoff_required: true
+  checkpoint_required: false

package/template/stages/01-brainstorm/inputs/project_brief.md

@@ -0,0 +1,40 @@
+# Project Brief: Snake Game
+
+## 프로젝트 이름
+Snake Game
+
+## 한 줄 설명
+클래식 스네이크 게임의 현대적 웹 버전
+
+## 문제 정의
+간단하지만 중독성 있는 캐주얼 게임 필요
+
+## 타겟 사용자
+- 짧은 시간 게임을 즐기고 싶은 사용자
+- 레트로 게임 팬
+- 모바일/데스크톱 모두에서 게임을 원하는 사용자
+
+## 핵심 기능
+1. 방향키/터치로 뱀 조작
+2. 먹이 수집 및 성장
+3. 충돌 감지 (벽, 자기 몸)
+4. 점수 시스템
+
+## 기술 요구사항
+- React + TypeScript
+- Vite 빌드 도구
+- Canvas 또는 CSS Grid 기반 렌더링
+- 반응형 디자인 (모바일 지원)
+
+## 성공 지표
+- 게임 플레이 가능 (기본 기능 완성)
+- 모바일/데스크톱 모두 지원
+- 테스트 커버리지 80% 이상
+- 배포 완료 (GitHub Pages 또는 Vercel)
+
+## 타임라인
+- 전체 파이프라인 (01~10): 약 4시간
+
+## 제약사항
+- 외부 게임 엔진 미사용 (순수 React)
+- 복잡한 백엔드 없음 (프론트엔드 only)

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

@@ -0,0 +1,159 @@
+# 🐍 Snake Game - 브레인스토밍 아이디어
+
+> 생성일: 2026-01-21
+> 스테이지: 01-brainstorm
+> 프로젝트: snake-game
+> AI 도구: Gemini CLI + ClaudeCode
+
+---
+
+## 📋 핵심 기능 아이디어 (12개)
+
+### 🎮 기본 게임플레이 (필수)
+
+| # | 아이디어 | 설명 | 우선순위 |
+|---|---------|------|---------|
+| 1 | **기본 뱀 조작** | 방향키(↑↓←→)로 뱀 이동 | 🔴 필수 |
+| 2 | **먹이 시스템** | 먹이를 먹으면 뱀 길이 +1, 점수 +10 | 🔴 필수 |
+| 3 | **충돌 감지** | 벽/자기 몸 충돌 시 게임 오버 | 🔴 필수 |
+| 4 | **점수 시스템** | 실시간 점수 표시 | 🔴 필수 |
+| 5 | **게임 재시작** | 게임 오버 후 다시 시작 기능 | 🔴 필수 |
+
+### ⭐ Gemini 제안 기능
+
+| # | 아이디어 | 설명 | 우선순위 |
+|---|---------|------|---------|
+| 6 | **Dash / Sprint** | 제한된 스태미나로 2배속 이동 | 🟢 선택 |
+| 7 | **Ghost Mode** | 자기 몸 통과 파워업 (5초) | 🟢 선택 |
+| 8 | **Dynamic Obstacles** | 10초마다 위치 변경되는 장애물 | 🟢 선택 |
+| 9 | **Combo System** | 연속 먹이 획득 시 점수 배율 (x1→x2→x4) | 🟡 중요 |
+| 10 | **Portal Edges** | 벽 통과 시 반대편으로 이동 (팩맨 스타일) | 🟡 중요 |
+| 11 | **Different Food Types** | 사과(+1), 황금사과(점수만), 고추(속도↑), 얼음(속도↓) | 🟢 선택 |
+| 12 | **Puzzle Levels** | 미로 레벨에서 모든 먹이 수집 | 🟢 선택 |
+
+---
+
+## 📊 장단점 분석 (Gemini 분석)
+
+| 아이디어 | 장점 | 단점 |
+|:---------|:-----|:-----|
+| **Dash / Sprint** | 스킬 요소 추가, "클러치" 모멘트 | 속도로 인한 실수 충돌 가능 |
+| **Ghost Mode** | 초보자 친화적, 좌절감 감소 | 너무 쉬워질 수 있음 |
+| **Dynamic Obstacles** | 신선함 유지, 안전지대 캠핑 방지 | 불공정하게 느껴질 수 있음 |
+| **Combo System** | 공격적이고 위험한 플레이 유도 | UI 복잡해짐 (타이머 표시) |
+| **Portal Edges** | 클래식하고 만족스러운 플로우 | "코너 함정" 긴장감 감소 |
+| **Different Food** | 전략적 깊이 (위험 vs 보상) | 플레이어가 색상별 효과 기억 필요 |
+| **Puzzle Levels** | 명확한 진행감/완료감 | 무한 모드 대비 재플레이성 낮음 |
+
+---
+
+## 👥 사용자 페르소나 (Gemini 생성)
+
+### 페르소나 A: "The Commuter" (캐주얼)
+- **인구통계**: 28세 직장인
+- **행동**: 지하철에서 모바일로 5-10분 플레이
+- **니즈**:
+  - 한 손 조작 (스와이프)
+  - 빠른 시작 (로딩 없음)
+  - 오프라인 가능
+  - 브라우저 닫아도 자동 저장
+- **불만**: 복잡한 메뉴, 작은 버튼, 광고
+
+### 페르소나 B: "The High-Scorer" (경쟁적)
+- **인구통계**: 16세 학생
+- **행동**: 쉬는 시간에 데스크톱 PC로 플레이, 리더보드에 집착
+- **니즈**:
+  - 정밀한 키보드 조작 (입력 지연 제로)
+  - 고대비 시각 (장애물 명확히 보임)
+  - 즉시 재시작 기능 ("R" 키)
+  - 글로벌 리더보드
+- **불만**: 불공정한 RNG, 랙, 느린 애니메이션
+
+### 페르소나 C: "The Retro Fan" (향수)
+- **인구통계**: 40세 개발자
+- **행동**: 픽셀 아트와 칩튠 음악 선호, 휴식용 플레이
+- **니즈**:
+  - 클래식 CRT 필터 또는 픽셀아트 미학
+  - 단순하고 "순수한" 게임플레이
+  - 게임패드/컨트롤러 지원
+- **불만**: 과도하게 현대적인 "화려한" 효과, 소액결제
+
+---
+
+## 🔍 유사 프로젝트 사례 (Gemini 조사)
+
+### 1. Google Snake (검색 이스터에그)
+- **특징**: "접근 가능한" 스네이크의 표준
+- **핵심 기능**: 토글 가능한 모드 (속도, 포털, 평화 모드)
+
+### 2. Slither.io
+- **특징**: "현대 멀티플레이어" 시대 정의
+- **핵심 기능**: 마우스 따라가기 (아날로그), "차단" 메카닉
+
+### 3. Classic Nokia Snake (Snake II)
+- **특징**: 장르의 기초
+- **핵심 기능**: 단색, 그리드 기반, 벽 랩어라운드 옵션
+
+### 4. React-Snake (GitHub Topics)
+- **공통 기술 스택 패턴**:
+  - `useInterval` 훅으로 게임 루프
+  - 좌표 배열 `[{x,y}, {x,y}]`로 뱀 몸통
+  - CSS Grid (쉬움) vs HTML5 Canvas (성능 좋음)
+  - Redux/Zustand로 하이스코어 관리
+
+---
+
+## 🎯 MVP 권장사항 (Gemini 제안)
+
+**페르소나 A (The Commuter)**와 **페르소나 B (The Competitive)**를 염두에 두고:
+
+### 기술 스택
+- **렌더링**: React + Canvas (모바일 성능 우선)
+- **입력**: 키보드 (Arrow/WASD) + 모바일 스와이프
+
+### MVP 기능 세트
+- [x] 클래식 무한 모드
+- [x] LocalStorage에 하이스코어 저장
+- [x] 3단계 속도 (느림, 보통, 빠름)
+- [x] "즉시 재시작" (한 번 더 시도 루프)
+
+---
+
+## 📊 최종 우선순위 매트릭스
+
+```
+                    높은 가치
+                        │
+    ┌───────────────────┼───────────────────┐
+    │  Combo System     │  기본 조작        │
+    │  Portal Edges     │  먹이 시스템      │
+    │  레벨 시스템      │  충돌 감지        │
+    │                   │  점수 시스템      │
+적은 ─────────────────────────────────────── 많은
+노력  │                   │  게임 재시작      │ 노력
+    │  일시정지         │                   │
+    │  하이스코어 저장  │  Different Food   │
+    │                   │  Ghost Mode       │
+    └───────────────────┼───────────────────┘
+                        │
+                    낮은 가치
+```
+
+---
+
+## ✅ 브레인스토밍 완료 체크리스트
+
+- [x] 최소 10개 아이디어 생성 (12개 완료)
+- [x] 3개 이상 사용자 페르소나 정의 (3개 완료)
+- [x] 각 아이디어 장단점 분석
+- [x] 유사 프로젝트 조사
+- [x] MVP 범위 제안
+
+---
+
+## 📝 AI 호출 기록
+
+| AI | 호출 시간 | 프롬프트 | 결과 | 상태 |
+|----|----------|---------|------|------|
+| Gemini | 2026-01-21 11:58 | Snake Game 브레인스토밍 | 12개 아이디어, 3 페르소나, 사례 조사 | ✅ 성공 |
+| ClaudeCode | 2026-01-21 11:57 | 결과 구조화 | ideas.md 작성 | ✅ 성공 |