create-ax-project 1.0.0

package/template/stages/07-refactoring/HANDOFF.md.template

@@ -0,0 +1,97 @@
+# Stage Handoff: 07-refactoring → 08-qa
+
+**생성일**: {{TIMESTAMP}}
+**생성자**: Codex
+**소요 시간**: {{DURATION}}
+
+---
+
+## 완료된 작업
+
+- [ ] 코드 품질 분석
+- [ ] 중복 코드 제거 ({{DUP_REMOVED}}개)
+- [ ] 성능 최적화
+- [ ] 리팩토링 보고서 작성
+- [ ] 체크포인트 생성
+- [ ] HANDOFF.md 생성
+
+---
+
+## 다음 에이전트를 위한 컨텍스트
+
+### 리팩토링 요약
+
+| 영역 | 이전 | 이후 | 개선율 |
+|------|------|------|--------|
+| 코드 중복 | {{DUP_BEFORE}} | {{DUP_AFTER}} | {{DUP_IMPROVE}}% |
+| 번들 사이즈 | {{BUNDLE_BEFORE}} | {{BUNDLE_AFTER}} | {{BUNDLE_IMPROVE}}% |
+| 복잡도 | {{COMPLEX_BEFORE}} | {{COMPLEX_AFTER}} | {{COMPLEX_IMPROVE}}% |
+
+### 주요 변경 사항
+1. {{CHANGE_1}}
+2. {{CHANGE_2}}
+3. {{CHANGE_3}}
+
+### 남은 기술 부채
+- {{REMAINING_DEBT_1}}
+- {{REMAINING_DEBT_2}}
+
+### QA 중점 확인 필요 영역
+- {{QA_FOCUS_1}}: 리팩토링으로 인한 영향
+- {{QA_FOCUS_2}}: 최적화로 인한 동작 변화
+
+---
+
+## 체크포인트 정보
+
+| ID | 생성일 | 설명 |
+|----|--------|------|
+| {{CP_ID}} | {{CP_DATE}} | 리팩토링 완료 |
+
+---
+
+## 생성된 산출물
+
+| 파일 | 설명 |
+|------|------|
+| refactored_code/ | 리팩토링된 코드 |
+| refactoring_report.md | 리팩토링 보고서 |
+
+---
+
+## 08-qa 스테이지 가이드
+
+### 즉시 실행할 작업
+1. 리팩토링 영역 기능 테스트
+2. 회귀 테스트
+3. 성능 벤치마크
+
+### 테스트 우선순위
+1. {{TEST_PRIORITY_1}}
+2. {{TEST_PRIORITY_2}}
+3. {{TEST_PRIORITY_3}}
+
+---
+
+## 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: "07-refactoring"
+status: "completed"
+next_stage: "08-qa"
+models_used:
+  - codex
+  - claudecode
+checkpoint_id: "{{CP_ID}}"
+```

package/template/stages/07-refactoring/config.yaml

@@ -0,0 +1,68 @@
+# Stage 07: Refactoring Configuration
+
+stage:
+  id: "07-refactoring"
+  name: "Refactoring"
+  description: "코드 품질 개선 및 최적화"
+
+models:
+  primary: "codex"
+  secondary: "claudecode"
+  collaboration: "sequential"
+
+# AI 자동 호출 설정 (Issue #12, #14 해결)
+auto_invoke:
+  enabled: true
+  model: "codex"
+  trigger: "refactoring_start"
+  prompt_file: "prompts/code_analysis.md"
+  wrapper: "scripts/codex-wrapper.sh"
+  flags: "--full-auto"
+  required: true
+  message: "🤖 Codex 자동 호출: 코드 분석 및 리팩토링 시작"
+
+execution:
+  mode: "deep_dive"
+  container: false
+  sandbox: false
+  timeout: 7200  # 2 hours
+
+inputs:
+  required:
+    - name: "../06-implementation/outputs/source_code/"
+    - name: "../06-implementation/outputs/implementation_log.md"
+    - name: "../06-implementation/HANDOFF.md"
+
+outputs:
+  required:
+    - name: "refactored_code/"
+      description: "리팩토링된 코드"
+    - name: "refactoring_report.md"
+      description: "리팩토링 보고서"
+    - name: "HANDOFF.md"
+
+prompts:
+  - name: "code_analysis"
+    file: "prompts/code_analysis.md"
+    model: "codex"
+  - name: "refactoring"
+    file: "prompts/refactoring.md"
+    model: "codex"
+  - name: "optimization"
+    file: "prompts/optimization.md"
+    model: "codex"
+
+completion:
+  checklist:
+    - "코드 품질 분석 완료"
+    - "중복 코드 제거"
+    - "성능 최적화 적용"
+    - "리팩토링 보고서 작성"
+    - "체크포인트 생성"
+
+transition:
+  next_stage: "08-qa"
+  prerequisites:
+    - "06-implementation"
+  handoff_required: true
+  checkpoint_required: true  # 필수!

package/template/stages/07-refactoring/outputs/refactoring_report.md

@@ -0,0 +1,102 @@
+# 🔧 Refactoring Report - Snake Game
+
+> 생성일: 2026-01-21
+> 프로젝트: snake-game
+> 스테이지: 07-refactoring
+
+---
+
+## 개선 사항 요약
+
+| 영역 | 개선 전 | 개선 후 | 상태 |
+|------|--------|--------|------|
+| useGameLoop | ESLint 오류 | Ref 패턴으로 수정 | ✅ |
+| ESLint | 1 error | 0 errors | ✅ |
+| 빌드 | 성공 | 성공 | ✅ |
+| 번들 크기 | 204KB | 204KB | ✅ |
+
+---
+
+## 수행된 리팩토링
+
+### 1. useGameLoop 훅 개선
+
+**문제**: useCallback 내부에서 자기 자신을 참조하여 ESLint `react-hooks/immutability` 오류 발생
+
+**해결**: Ref 패턴을 사용하여 stale closure 문제 방지
+
+**변경 내용**:
+- `useCallback` 제거하고 `useEffect` 내부에서 직접 함수 정의
+- `onTick`, `speed`, `isRunning` 값을 Ref로 관리하여 최신 값 참조 보장
+- 게임 루프가 중단될 때 `cancelAnimationFrame` 정확히 호출
+
+```typescript
+// Before (ESLint Error)
+const gameLoop = useCallback((timestamp) => {
+  // ...
+  rafIdRef.current = requestAnimationFrame(gameLoop); // 자기 참조 오류
+}, [onTick, speed, isRunning]);
+
+// After (Fixed)
+useEffect(() => {
+  const gameLoop = (timestamp) => {
+    // Ref를 통해 최신 값 접근
+    onTickRef.current();
+    rafIdRef.current = requestAnimationFrame(gameLoop);
+  };
+  // ...
+}, [isRunning]);
+```
+
+---
+
+## 코드 품질 분석
+
+### ESLint 결과
+```
+✅ 0 errors, 0 warnings
+```
+
+### TypeScript 컴파일
+```
+✅ tsc -b 성공
+```
+
+### 번들 분석
+
+| 파일 | 크기 | Gzip |
+|------|------|------|
+| index.html | 0.46 KB | 0.29 KB |
+| index.css | 12.85 KB | 2.69 KB |
+| index.js | 204.52 KB | 64.51 KB |
+
+---
+
+## 추가 개선 권장사항
+
+### 성능 최적화 (향후)
+- [ ] `React.memo`로 불필요한 리렌더링 방지
+- [ ] Canvas 렌더링 최적화 (더티 영역만 갱신)
+- [ ] 뱀 몸통 렌더링 배치 처리
+
+### 코드 품질 (향후)
+- [ ] 테스트 커버리지 추가
+- [ ] JSDoc 주석 추가
+- [ ] 에러 바운더리 구현
+
+### 접근성 (향후)
+- [ ] 키보드 포커스 관리
+- [ ] 스크린 리더 지원
+- [ ] 감소된 모션 설정 지원
+
+---
+
+## 결론
+
+07-refactoring 스테이지에서 ESLint 오류를 수정하고 코드 품질을 개선했습니다.
+게임은 정상적으로 빌드되고 실행됩니다.
+
+---
+
+**작성자**: ClaudeCode
+**검토일**: 2026-01-21

package/template/stages/07-refactoring/prompts/collaboration.md

@@ -0,0 +1,71 @@
+# AI 협업 프롬프트 - Refactoring
+
+## 협업 모드: Sequential Review Chain
+
+이 스테이지에서는 **순차적 리뷰 체인**을 사용하여 리팩토링 품질을 보장합니다.
+
+### 참여 모델
+- **Codex**: 코드 분석, 최적화
+- **ClaudeCode**: 복잡한 리팩토링, 검증
+
+### 협업 프롬프트
+
+```
+# 리뷰 체인: Codex 분석 → Claude 검증
+/collaborate --mode sequential --chain "codex:analyze -> claude:review -> codex:refactor"
+```
+
+### AI 벤치마킹
+
+성능 최적화 비교:
+```
+/benchmark --task "performance_optimization" --models "codex,claude"
+```
+
+### 작업 흐름
+
+1. **분석**: 정적 분석, 복잡도 측정
+2. **계획**: 리팩토링 우선순위 결정
+3. **실행**: 작은 단위로 리팩토링
+4. **검증**: 테스트 통과 확인
+
+### 체크포인트 필수
+
+```bash
+# 리팩토링 전 체크포인트
+/checkpoint --reason "리팩토링 시작 전 상태"
+
+# 주요 리팩토링 후
+/checkpoint --reason "함수 X 리팩토링 완료"
+```
+
+### 롤백 준비
+
+```bash
+# 롤백 가능 상태 확인
+/restore --list
+
+# 필요시 부분 롤백
+/restore checkpoint_id --partial --files "src/utils/*"
+```
+
+### 출력 형식
+
+```markdown
+## AI 협업 결과
+
+### Codex 분석
+- 복잡도 높은 함수 목록
+- 중복 코드 위치
+- 성능 병목
+
+### Claude 검증
+- 리팩토링 영향 범위
+- 테스트 필요 영역
+- 위험 요소
+
+### 리팩토링 계획
+1. [우선순위 1 항목]
+2. [우선순위 2 항목]
+...
+```

package/template/stages/07-refactoring/prompts/validation.md

@@ -0,0 +1,76 @@
+# 산출물 검증 프롬프트 - Refactoring
+
+## 검증 대상
+
+| 산출물 | 필수 조건 | 검증 방법 |
+|--------|----------|----------|
+| `refactored_code/` | 동작 유지 | 테스트 통과 |
+| `refactored_code/` | 품질 개선 | 메트릭 비교 |
+| `refactoring_report.md` | 변경 내역 | 구조 확인 |
+| `HANDOFF.md` | 체크포인트 참조 | 항목 확인 |
+
+## 검증 명령
+
+```bash
+/validate --stage 07-refactoring
+```
+
+## 품질 기준
+
+### refactored_code/
+- [ ] 모든 기존 테스트 통과
+- [ ] Lint 에러 없음
+- [ ] 타입 에러 없음
+- [ ] 복잡도 감소 (목표: 20%↓)
+- [ ] 중복 코드 감소 (목표: 50%↓)
+
+### refactoring_report.md
+- [ ] 리팩토링된 함수/클래스 목록
+- [ ] 변경 전후 비교
+- [ ] 성능 개선 측정값
+- [ ] 남은 기술 부채
+
+### HANDOFF.md
+- [ ] 완료된 리팩토링 목록
+- [ ] 체크포인트 참조
+- [ ] QA 필요 영역
+
+## 자동 검증 스크립트
+
+```bash
+# 테스트 통과 확인
+npm run test
+
+# Lint 검사
+npm run lint
+
+# 번들 사이즈 비교
+npm run build && du -sh dist/
+
+# 복잡도 측정 (선택적)
+npx complexity-report src/**/*.ts
+```
+
+## 품질 메트릭 비교
+
+| 메트릭 | 이전 | 이후 | 개선율 |
+|--------|------|------|--------|
+| 평균 복잡도 | - | - | - |
+| 중복 코드 | - | - | - |
+| 번들 사이즈 | - | - | - |
+
+## 회귀 테스트
+
+```bash
+# 전체 테스트 실행
+npm run test
+
+# E2E 테스트 실행 (있는 경우)
+npm run test:e2e
+```
+
+## 실패 시 조치
+
+1. 테스트 실패 → 체크포인트로 롤백 후 재시도
+2. 성능 저하 → 변경 사항 검토 및 최적화
+3. 타입 에러 → 타입 수정 후 재검증

package/template/stages/08-qa/CLAUDE.md

@@ -0,0 +1,93 @@
+# Stage 08: QA
+
+품질 보증 및 코드 리뷰 단계
+
+## 🎭 페르소나: Quality Guardian
+
+> 당신은 Quality Guardian입니다.
+> 모든 가능한 문제를 찾아내고 품질을 보장하세요.
+> 엣지 케이스와 보안 취약점에 특히 주의하세요.
+
+### 특성
+- 꼼꼼한 검토
+- 엣지 케이스 발견
+- 보안 의식
+- 사용자 관점
+
+### 권장 행동
+- 엣지 케이스 탐색
+- 보안 취약점 검사
+- 성능 문제 식별
+- 사용성 검토
+
+### 지양 행동
+- 표면적 검토
+- 긍정적 가정
+- 버그 무시
+
+### AI 설정
+- **Temperature**: 0.3 (철저한 검토)
+- **철저함**: High
+- **회의적 태도**: Healthy
+
+## 실행 모델
+- **Primary**: ClaudeCode (코드 리뷰, 버그 수정)
+- **Mode**: Plan + Sandbox
+
+## 목표
+1. 코드 리뷰 수행
+2. 버그 식별 및 수정
+3. 보안 취약점 검사
+4. 품질 기준 준수 확인
+
+## 입력 파일
+- `../07-refactoring/outputs/refactored_code/`
+- `../07-refactoring/outputs/refactoring_report.md`
+- `../07-refactoring/HANDOFF.md`
+
+## 출력 파일
+- `outputs/qa_report.md` - QA 보고서
+- `outputs/bug_fixes.md` - 버그 수정 내역
+- `HANDOFF.md` - 다음 스테이지 인계 문서
+
+## 워크플로우
+
+### 1. 코드 리뷰
+- 코딩 표준 준수 확인
+- 베스트 프랙티스 적용 여부
+- 문서화 수준 검토
+
+### 2. 기능 테스트
+- 요구사항 대비 기능 검증
+- 엣지 케이스 테스트
+- 에러 핸들링 검증
+
+### 3. 보안 검사
+- OWASP Top 10 체크
+- 입력 검증
+- 인증/인가 검증
+- 민감 정보 노출 검사
+
+### 4. 성능 검토
+- 응답 시간 측정
+- 메모리 사용량
+- 불필요한 리렌더링
+
+### 5. 버그 수정
+- 식별된 버그 우선순위 지정
+- 수정 및 검증
+- 회귀 테스트
+
+## 완료 조건
+- [ ] 코드 리뷰 완료
+- [ ] 보안 검사 통과
+- [ ] 식별된 버그 수정
+- [ ] QA 보고서 작성
+- [ ] HANDOFF.md 생성
+
+## 다음 스테이지
+→ **09-testing**: 테스트 코드 작성 및 E2E 테스트
+
+
+
+

package/template/stages/08-qa/HANDOFF.md

@@ -0,0 +1,114 @@
+# HANDOFF: 08-qa → 09-testing
+
+> 생성일: 2026-01-21
+> 프로젝트: snake-game
+> 현재 스테이지: 08-qa (완료)
+> 다음 스테이지: 09-testing
+
+---
+
+## ✅ 완료된 작업
+
+- [x] 코드 품질 검증 (ESLint, TypeScript)
+- [x] 프로덕션 빌드 검증
+- [x] BUG-001 수정: useGameLoop 초기화 문제
+- [x] 기능 테스트 (Playwright MCP)
+  - [x] 게임 시작/재시작
+  - [x] 키보드 입력 (방향키)
+  - [x] 벽 충돌 게임 오버
+- [x] QA 보고서 작성
+
+---
+
+## 🐛 수정된 버그
+
+### BUG-001: 게임 시작 즉시 게임 오버
+- **파일**: `src/hooks/useGameLoop.ts`
+- **원인**: 첫 프레임에서 큰 deltaTime으로 인해 다수의 MOVE 호출
+- **수정**: 첫 프레임 스킵 + deltaTime 클램핑
+
+---
+
+## 📁 생성/수정된 파일
+
+| 파일 | 변경 유형 | 설명 |
+|------|----------|------|
+| `src/hooks/useGameLoop.ts` | 수정 | 버그 수정 |
+| `outputs/qa_report.md` | 생성 | QA 보고서 |
+| `HANDOFF.md` | 생성 | 인계 문서 |
+
+---
+
+## 🔍 코드 품질 상태
+
+| 항목 | 상태 |
+|------|------|
+| ESLint | ✅ 0 errors |
+| TypeScript | ✅ 컴파일 성공 |
+| 빌드 | ✅ 성공 |
+| 번들 크기 | ✅ 204.59KB |
+
+---
+
+## 🎯 09-testing 권장 작업
+
+### 1. 단위 테스트 (Vitest)
+
+```bash
+npm install -D vitest @testing-library/react
+```
+
+#### 테스트 대상
+- `collision.ts`
+  - `checkWallCollision()` - 경계 조건
+  - `checkSelfCollision()` - 자기 몸 충돌
+  - `checkFoodCollision()` - 먹이 충돌
+
+- `gameReducer.ts`
+  - START_GAME → PLAYING 상태 전이
+  - MOVE → 뱀 이동 검증
+  - CHANGE_DIRECTION → 반대 방향 차단
+
+- `useGameLoop.ts`
+  - 게임 루프 시작/정지
+  - 타이밍 정확도
+
+### 2. E2E 테스트 (Playwright)
+
+```bash
+npm install -D @playwright/test
+```
+
+#### 테스트 시나리오
+1. 전체 게임 플로우
+   - 페이지 로드 → 시작 버튼 → 게임 플레이 → 게임오버 → 재시작
+
+2. 점수 시스템
+   - 먹이 먹기 → 점수 증가 확인
+   - 레벨업 시 속도 변화 확인
+
+3. 최고 점수
+   - localStorage 저장 확인
+   - 새로고침 후 유지 확인
+
+### 3. 커버리지 목표
+- 단위 테스트: 80%+
+- E2E 테스트: 핵심 플로우 100%
+
+---
+
+## 🚀 다음 단계
+
+```bash
+# 09-testing 스테이지 실행
+/run-stage 09-testing
+
+# 또는
+/test
+```
+
+---
+
+**생성자**: ClaudeCode
+**검토자**: -
+**승인**: 대기