create-ax-project 1.0.0

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

@@ -0,0 +1,192 @@
+# Stage Handoff: 06-implementation → 07-refactoring
+
+**생성일**: {{TIMESTAMP}}
+**생성자**: ClaudeCode
+**소요 시간**: {{DURATION}}
+
+---
+
+## AI 사용 기록
+
+> 이 섹션은 의도된 AI 설정과 실제 사용을 비교하여 협업 효율성을 추적합니다.
+
+### 의도 vs 실제 비교
+
+| 항목 | 의도 | 실제 | 일치 |
+|------|------|------|------|
+| Primary AI | ClaudeCode | {{ACTUAL_PRIMARY_AI}} | {{PRIMARY_MATCH}} |
+| Secondary AI | - | {{ACTUAL_SECONDARY_AI}} | - |
+| 협업 모드 | none (단일 AI) | {{ACTUAL_COLLABORATION_MODE}} | {{MODE_MATCH}} |
+| 외부 AI 호출 | 아니오 | {{ACTUAL_EXTERNAL_CALL}} | {{EXTERNAL_MATCH}} |
+
+### AI 호출 로그
+
+| AI | 호출 시간 | 역할 | 프롬프트 | 결과 | 상태 |
+|----|----------|------|---------|------|------|
+| {{AI_1}} | {{TIME_1}} | {{ROLE_1}} | {{PROMPT_1}} | {{OUTPUT_1}} | {{STATUS_1}} |
+| {{AI_2}} | {{TIME_2}} | {{ROLE_2}} | {{PROMPT_2}} | {{OUTPUT_2}} | {{STATUS_2}} |
+
+### 폴백 기록
+
+| 시도한 AI | 실패 시간 | 오류 | 폴백 AI | 결과 |
+|----------|----------|------|---------|------|
+| {{FALLBACK_ATTEMPTED}} | {{FALLBACK_TIME}} | {{FALLBACK_ERROR}} | {{FALLBACK_TO}} | {{FALLBACK_RESULT}} |
+
+> 설정: `config/ai_collaboration.yaml`, `config/mcp_fallbacks.yaml`
+
+---
+
+## 완료된 작업
+
+- [ ] 프로젝트 스캐폴딩
+- [ ] 공통 컴포넌트 ({{COMPONENT_COUNT}}개)
+- [ ] 핵심 기능 구현
+- [ ] API 엔드포인트 ({{API_COUNT}}개)
+- [ ] **스모크 테스트 실행** (Test-First)
+- [ ] 체크포인트 생성
+- [ ] HANDOFF.md 생성
+
+---
+
+## 테스트 상태 (Test-First 플로우)
+
+> ⚠️ **필수**: 구현 완료 후 스모크 테스트를 실행하여 기본 동작을 확인하세요.
+
+### 실행된 테스트
+
+| 테스트 유형 | 실행 시간 | 결과 | 비고 |
+|-----------|----------|------|------|
+| `npm run dev` | {{DEV_TIME}} | {{DEV_RESULT}} | 개발 서버 실행 |
+| ESLint | {{LINT_TIME}} | {{LINT_RESULT}} | 정적 분석 |
+| TypeScript | {{TS_TIME}} | {{TS_RESULT}} | 타입 체크 |
+| Playwright 스모크 | {{PLAYWRIGHT_TIME}} | {{PLAYWRIGHT_RESULT}} | UI 기본 동작 |
+
+### 발견된 버그
+
+| ID | 설명 | 발견 시점 | 상태 | 수정 파일 |
+|----|------|----------|------|----------|
+| {{BUG_ID}} | {{BUG_DESC}} | {{BUG_FOUND}} | {{BUG_STATUS}} | {{BUG_FILE}} |
+
+### 테스트 미실행 사유
+
+- **미실행 시**: {{TEST_SKIP_REASON}}
+- **권장 조치**: 07-refactoring 전에 기본 테스트 실행 권장
+
+---
+
+## 다음 에이전트를 위한 컨텍스트
+
+### 프로젝트 구조
+```
+source_code/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   ├── api/
+│   ├── lib/
+│   └── styles/
+├── package.json
+└── ...
+```
+
+### 기술 스택 확정
+
+| 영역 | 기술 | 버전 |
+|------|------|------|
+| Framework | {{FRAMEWORK}} | {{VERSION}} |
+| UI Library | {{UI_LIB}} | |
+| State | {{STATE_MGMT}} | |
+| API | {{API_STYLE}} | |
+
+### 구현 완료 기능
+
+| 기능 | 상태 | 파일 | 테스트 상태 |
+|------|------|------|-----------|
+| {{FEATURE_1}} | 완료 | {{FILE_1}} | {{TEST_1}} |
+| {{FEATURE_2}} | 완료 | {{FILE_2}} | {{TEST_2}} |
+| {{FEATURE_3}} | 완료 | {{FILE_3}} | {{TEST_3}} |
+
+### 알려진 이슈 / 기술 부채
+1. {{TECH_DEBT_1}}
+2. {{TECH_DEBT_2}}
+
+### 리팩토링 필요 영역
+- {{REFACTOR_AREA_1}}: {{REASON_1}}
+- {{REFACTOR_AREA_2}}: {{REASON_2}}
+
+---
+
+## 체크포인트 정보
+
+| ID | 생성일 | 설명 | 자동/수동 |
+|----|--------|------|----------|
+| {{CP_ID}} | {{CP_DATE}} | 스프린트 1 완료 | {{CP_TYPE}} |
+
+복구 명령:
+```bash
+scripts/restore-checkpoint.sh {{CP_ID}}
+```
+
+---
+
+## 생성된 산출물
+
+| 파일 | 설명 | 검증 상태 |
+|------|------|----------|
+| source_code/ | 구현된 소스 코드 | {{CODE_VALIDATED}} |
+| implementation_log.md | 구현 로그 | - |
+
+---
+
+## 07-refactoring 스테이지 가이드
+
+### 즉시 실행할 작업
+1. **회귀 테스트 실행** (Test-First)
+2. 코드 품질 분석 (ESLint, TypeScript)
+3. 중복 코드 식별
+4. 성능 병목 지점 분석
+
+### 리팩토링 우선순위
+1. {{REFACTOR_PRIORITY_1}}
+2. {{REFACTOR_PRIORITY_2}}
+3. {{REFACTOR_PRIORITY_3}}
+
+### 주의사항
+- ⚠️ **Codex CLI 사용 필수** - 깊이 있는 분석을 위해 `/codex` 명령어 활용
+- 기존 기능 깨뜨리지 않도록 주의
+- 리팩토링 전/후 동작 동일 확인
+- 체크포인트 활용
+
+---
+
+## 메타데이터
+
+```yaml
+stage: "06-implementation"
+status: "completed"
+next_stage: "07-refactoring"
+timestamp: "{{TIMESTAMP}}"
+
+ai_usage:
+  intended:
+    primary: "claudecode"
+    secondary: null
+    collaboration_mode: "none"
+  actual:
+    primary: "{{ACTUAL_PRIMARY_AI}}"
+    secondary: "{{ACTUAL_SECONDARY_AI}}"
+    collaboration_mode: "{{ACTUAL_COLLABORATION_MODE}}"
+  fallbacks: {{FALLBACK_COUNT}}
+  match_rate: "{{MATCH_RATE}}"
+
+testing:
+  smoke_test_run: {{SMOKE_TEST_RUN}}
+  lint_passed: {{LINT_PASSED}}
+  typecheck_passed: {{TYPECHECK_PASSED}}
+  bugs_found: {{BUGS_FOUND_COUNT}}
+  bugs_fixed: {{BUGS_FIXED_COUNT}}
+
+checkpoint_id: "{{CP_ID}}"
+files_created: {{FILE_COUNT}}
+lines_of_code: {{LOC}}
+```

package/template/stages/06-implementation/config.yaml

@@ -0,0 +1,62 @@
+# Stage 06: Implementation Configuration
+
+stage:
+  id: "06-implementation"
+  name: "Implementation"
+  description: "핵심 기능 구현"
+
+models:
+  primary: "claudecode"
+  secondary: null
+  collaboration: null
+
+execution:
+  mode: "plan_sandbox"
+  container: false
+  sandbox: true
+  timeout: 14400  # 4 hours
+
+inputs:
+  required:
+    - name: "../05-task-management/outputs/tasks.md"
+    - name: "../03-planning/outputs/architecture.md"
+    - name: "../03-planning/outputs/implementation.yaml"
+      description: "구현 규칙 (Issue #10)"
+    - name: "../05-task-management/HANDOFF.md"
+  optional:
+    - name: "../04-ui-ux/outputs/design_system.md"
+    - name: "../03-planning/outputs/tech_stack.md"
+
+outputs:
+  required:
+    - name: "source_code/"
+      description: "구현된 소스 코드"
+    - name: "implementation_log.md"
+      description: "구현 로그"
+    - name: "HANDOFF.md"
+
+prompts:
+  - name: "scaffolding"
+    file: "prompts/scaffolding.md"
+    model: "claudecode"
+  - name: "component_impl"
+    file: "prompts/component_impl.md"
+    model: "claudecode"
+  - name: "api_impl"
+    file: "prompts/api_impl.md"
+    model: "claudecode"
+
+completion:
+  checklist:
+    - "프로젝트 스캐폴딩 완료"
+    - "공통 컴포넌트 구현"
+    - "핵심 기능 구현"
+    - "API 엔드포인트 구현"
+    - "체크포인트 생성"
+
+transition:
+  next_stage: "07-refactoring"
+  prerequisites:
+    - "05-task-management"
+  handoff_required: true
+  checkpoint_required: true  # 필수!

package/template/stages/06-implementation/prompts/collaboration.md

@@ -0,0 +1,64 @@
+# AI 협업 프롬프트 - Implementation
+
+## 협업 모드: Sequential Handoff
+
+이 스테이지에서는 **순차적 전달** 모드를 사용하여 구현 → 리뷰 → 개선 사이클을 진행합니다.
+
+### 참여 모델
+- **ClaudeCode**: 코드 생성, 구현
+
+### 협업 프롬프트
+
+```
+# 구현 → 셀프 리뷰 → 개선
+/collaborate --mode sequential --chain "claudecode:implement -> claudecode:review -> claudecode:improve"
+```
+
+### AI 벤치마킹 (선택적)
+
+복잡한 알고리즘 구현 시:
+```
+/benchmark --task "sorting_algorithm" --models "claude,codex"
+```
+
+### 작업 흐름
+
+1. **스캐폴딩**: 프로젝트 초기화
+2. **공통 컴포넌트**: 디자인 시스템 기반
+3. **기능 구현**: 스프린트 태스크 순차 구현
+4. **통합**: API/DB 연동
+
+### 체크포인트 트리거
+
+- 스프린트 완료 시
+- 주요 기능 완료 시
+- 100줄 이상 변경 시
+
+```
+/checkpoint --reason "스프린트 1 완료"
+```
+
+### implementation.yaml 준수
+
+구현 전 반드시 확인:
+```yaml
+# 예시 규칙
+component_type: functional
+styling: tailwind
+state_management: zustand
+naming: camelCase
+```
+
+### 출력 형식
+
+```markdown
+## 구현 로그
+
+### [날짜] - [태스크]
+- 구현 내용
+- 변경된 파일
+- 테스트 결과
+
+### 체크포인트
+- checkpoint_YYYYMMDD_HHMMSS
+```

package/template/stages/06-implementation/prompts/validation.md

@@ -0,0 +1,65 @@
+# 산출물 검증 프롬프트 - Implementation
+
+## 검증 대상
+
+| 산출물 | 필수 조건 | 검증 방법 |
+|--------|----------|----------|
+| `source_code/` | Lint 통과 | `npm run lint` |
+| `source_code/` | Type 체크 통과 | `npm run typecheck` |
+| `implementation_log.md` | 변경 기록 | 구조 확인 |
+| `HANDOFF.md` | 체크포인트 참조 | 항목 확인 |
+
+## 검증 명령
+
+```bash
+/validate --stage 06-implementation
+```
+
+## 품질 기준
+
+### source_code/
+- [ ] ESLint 에러 없음
+- [ ] TypeScript 타입 에러 없음
+- [ ] 폴더 구조 준수 (implementation.yaml)
+- [ ] 네이밍 규칙 준수
+- [ ] 코드 포맷팅 적용
+
+### implementation_log.md
+- [ ] 구현된 태스크 목록
+- [ ] 변경된 파일 목록
+- [ ] 알려진 이슈/기술 부채
+
+### HANDOFF.md
+- [ ] 완료된 기능 체크리스트
+- [ ] 체크포인트 참조
+- [ ] 리팩토링 필요 항목
+
+## 자동 검증 스크립트
+
+```bash
+# Lint 검사
+npm run lint
+
+# Type 검사
+npm run typecheck
+
+# 빌드 검증
+npm run build
+
+# 기본 테스트
+npm run test -- --passWithNoTests
+```
+
+## 코드 품질 메트릭
+
+| 메트릭 | 기준 | 명령 |
+|--------|------|------|
+| Lint 에러 | 0 | `npm run lint` |
+| Type 에러 | 0 | `npm run typecheck` |
+| 빌드 성공 | Yes | `npm run build` |
+
+## 실패 시 조치
+
+1. Lint 에러 → `npm run lint --fix`
+2. Type 에러 → 타입 수정
+3. 빌드 실패 → 에러 로그 분석 후 수정

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

@@ -0,0 +1,180 @@
+# Stage 07: Refactoring
+
+> ⚠️ **필수 AI 모델: Codex**
+> 이 스테이지의 핵심 작업(코드 분석, 리팩토링, 최적화)은 `/codex` 명령어로 수행하세요.
+> ClaudeCode는 간단한 파일 조작 및 빌드/테스트 실행에만 사용합니다.
+
+코드 품질 개선 및 최적화 단계
+
+## 🎭 페르소나: Code Surgeon
+
+> 당신은 Code Surgeon입니다.
+> 코드의 본질을 유지하면서 품질을 개선하세요.
+> 성능, 가독성, 유지보수성을 균형있게 최적화하세요.
+
+### 특성
+- 깊이 있는 분석
+- 성능 최적화
+- 기술 부채 해소
+- 패턴 적용
+
+### 권장 행동
+- 코드 복잡도 감소
+- 성능 병목 해결
+- 디자인 패턴 적용
+- 중복 제거
+
+### 지양 행동
+- 불필요한 변경
+- 과도한 추상화
+- 동작 변경
+
+### AI 설정
+- **Temperature**: 0.5 (균형 잡힌 분석)
+- **분석 깊이**: Deep
+
+## 실행 모델
+- **Primary**: Codex (코드 분석 및 최적화)
+- **Secondary**: ClaudeCode (복잡한 리팩토링)
+- **Mode**: Deep Dive - 심층 코드 분석
+
+## 목표
+1. 코드 품질 개선
+2. 중복 제거
+3. 성능 최적화
+4. 아키텍처 개선
+
+## 입력 파일
+- `../06-implementation/outputs/source_code/`
+- `../06-implementation/outputs/implementation_log.md`
+- `../06-implementation/HANDOFF.md`
+
+## 출력 파일
+- `outputs/refactored_code/` - 리팩토링된 코드
+- `outputs/refactoring_report.md` - 리팩토링 보고서
+- `HANDOFF.md` - 다음 스테이지 인계 문서
+
+## Codex CLI 활용
+
+### 코드 분석
+```bash
+/codex "다음 코드의 개선점을 분석해주세요:
+- 중복 코드
+- 성능 병목
+- 디자인 패턴 위반
+- 타입 안전성 문제"
+```
+
+### 리팩토링 실행
+```bash
+/codex "다음 함수를 리팩토링해주세요:
+[코드 블록]
+목표: 가독성 향상, 성능 최적화"
+```
+
+## 워크플로우
+
+### 1. 코드 분석
+- 정적 분석 실행 (ESLint, TypeScript)
+- 복잡도 분석 (Cyclomatic complexity)
+- 의존성 분석
+
+### 2. 리팩토링 계획
+- 개선 영역 식별
+- 우선순위 결정
+- 영향 범위 평가
+
+### 3. 리팩토링 실행
+- 작은 단위로 수행
+- 각 변경 후 테스트
+- 커밋 메시지에 변경 사항 기록
+
+### 4. 최적화
+- 번들 사이즈 최적화
+- 렌더링 최적화
+- API 호출 최적화
+
+## 체크포인트 규칙
+- **필수**: 이 스테이지는 체크포인트가 필수입니다
+- 주요 리팩토링 전 체크포인트 생성
+- 롤백 가능 상태 유지
+
+---
+
+## ⚠️ AI 사용 기록 (필수)
+
+> **중요**: 이 스테이지는 Codex CLI를 사용해야 합니다.
+> Codex 호출 실패 시 ClaudeCode로 폴백되며, 이 경우 HANDOFF.md에 반드시 기록해야 합니다.
+
+### Codex 호출 전 확인
+```bash
+# 1. Codex CLI 설치 확인
+which codex
+
+# 2. tmux 세션 확인
+tmux ls
+
+# 3. 사전 점검 (권장)
+./scripts/pre-run-check.sh
+```
+
+### Codex 폴백 시 HANDOFF.md 기록
+Codex CLI 사용이 불가능하여 ClaudeCode로 폴백한 경우:
+
+```markdown
+### 폴백 기록
+
+| 시도한 AI | 실패 시간 | 오류 | 폴백 AI | 결과 |
+|----------|----------|------|---------|------|
+| Codex | HH:MM | [오류 내용] | ClaudeCode | 성공/실패 |
+
+**폴백 사유**: [상세 사유]
+**영향**: Codex의 깊이 있는 분석 미활용
+```
+
+---
+
+## ⚠️ Test-First 플로우 (필수)
+
+> **중요**: 리팩토링 후 기존 기능이 깨지지 않았는지 반드시 회귀 테스트를 실행하세요.
+
+### 리팩토링 완료 후 필수 테스트
+
+```bash
+# 1. 기존 테스트 실행 (회귀 방지)
+npm run test
+
+# 2. 정적 분석
+npm run lint
+
+# 3. 타입 체크
+npm run typecheck
+
+# 4. 개발 서버 실행 확인
+npm run dev
+```
+
+### 테스트 실패 시 조치
+1. **회귀 테스트 실패**: 리팩토링 롤백 또는 수정
+2. **lint 오류**: 리팩토링된 코드 수정
+3. **typecheck 오류**: 타입 정의 수정
+4. **동작 변경 발견**: 의도적 변경인지 확인, 아니면 롤백
+
+---
+
+## 완료 조건
+- [ ] 코드 품질 분석 완료
+- [ ] 중복 코드 제거
+- [ ] 성능 최적화 적용
+- [ ] **회귀 테스트 실행** (Test-First)
+- [ ] **lint/typecheck 통과**
+- [ ] 리팩토링 보고서 작성
+- [ ] 체크포인트 생성
+- [ ] HANDOFF.md 생성 (AI 사용/폴백 기록 포함)
+
+## 다음 스테이지
+→ **08-qa**: 품질 보증 및 코드 리뷰
+
+
+
+

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

@@ -0,0 +1,82 @@
+# HANDOFF: 07-refactoring → 08-qa
+
+> 생성일: 2026-01-21
+> 프로젝트: snake-game
+> 현재 스테이지: 07-refactoring (완료)
+> 다음 스테이지: 08-qa
+
+---
+
+## ✅ 완료된 작업
+
+- [x] ESLint 오류 수정 (useGameLoop)
+- [x] Ref 패턴으로 stale closure 문제 해결
+- [x] 코드 품질 분석 완료
+- [x] 빌드 검증 완료
+- [x] 리팩토링 보고서 작성
+
+---
+
+## 📁 생성/수정된 파일
+
+| 파일 | 변경 유형 | 설명 |
+|------|----------|------|
+| `src/hooks/useGameLoop.ts` | 수정 | Ref 패턴으로 리팩토링 |
+| `outputs/refactoring_report.md` | 생성 | 리팩토링 보고서 |
+| `HANDOFF.md` | 생성 | 인계 문서 |
+
+---
+
+## 🔍 코드 품질 상태
+
+| 항목 | 상태 |
+|------|------|
+| ESLint | ✅ 0 errors |
+| TypeScript | ✅ 컴파일 성공 |
+| 빌드 | ✅ 성공 |
+| 번들 크기 | ✅ 204KB (목표 200KB 근접) |
+
+---
+
+## 🎯 08-qa 권장 테스트 항목
+
+### 기능 테스트
+- [ ] 게임 시작/재시작
+- [ ] 방향키 입력 (Arrow, WASD)
+- [ ] 먹이 먹기 및 성장
+- [ ] 벽 충돌 게임 오버
+- [ ] 자기 몸 충돌 게임 오버
+- [ ] 점수 증가 및 표시
+- [ ] 레벨업 및 속도 증가
+- [ ] 일시정지/재개
+- [ ] 최고 점수 저장/불러오기
+
+### 엣지 케이스
+- [ ] 빠른 연속 방향 전환
+- [ ] 벽 바로 앞에서 방향 전환
+- [ ] 게임 오버 직후 즉시 재시작
+- [ ] 탭 전환 후 게임 상태
+
+### 브라우저 호환성
+- [ ] Chrome
+- [ ] Firefox
+- [ ] Safari
+- [ ] Edge
+
+---
+
+## 🚀 다음 단계
+
+```bash
+# 08-qa 스테이지 실행
+/run-stage 08-qa
+
+# 또는
+/qa
+```
+
+---
+
+**생성자**: ClaudeCode
+**검토자**: -
+**승인**: 대기