# dev-step-01 계획 검토 및 단계별 진행 제안

`dev-step-01.md`의 방향은 전반적으로 좋다. 특히 첫 이터레이션에서 DB, 인증, Redis, 유형 선택, 모드 선택을 제외하고 **괄호 앞 음수 분배 문제 풀이 기능만 먼저 만든다**는 판단은 `AGENTS.md`의 프로젝트 방향과 잘 맞는다.

다만 첫 단계는 조금 더 작게 쪼개는 것이 좋다. 현재 계획의 “1단계: 프로젝트 초기화”는 적절하지만, 바로 Zustand, Framer Motion, react-katex까지 모두 설치하면 첫 확인 지점이 흐려질 수 있다.

## 추천 첫 단계

1. Next.js 프로젝트 초기화
2. Tailwind 기본 화면 정리
3. `/`에서 “괄호 음수 분배 연습 시작” 버튼만 보이게 만들기
4. `/play` 빈 페이지까지 라우팅 확인
5. `pnpm dev`로 브라우저에서 화면 이동 확인

첫 단계의 완료 기준은 “앱이 실행되고 시작 화면에서 풀이 화면으로 이동된다” 정도가 적당하다. 아직 문제 생성, KaTeX, 상태 관리는 넣지 않는다.

## 단계별 진행안

### 1차 이터레이션: 화면 뼈대

- `app/page.tsx`
- `app/(game)/play/page.tsx`
- 시작 버튼에서 `/play`로 이동
- 아직 문제 생성 없음
- 완료 기준: 브라우저에서 시작 화면에서 풀이 화면으로 이동 확인

### 2차 이터레이션: 문제 생성 엔진

- `lib/engine/parenthesis-sign.ts`
- `generateProblem`
- `gradeAnswer`
- Vitest 테스트
- UI는 건드리지 않고 순수 알고리즘만 검증
- 완료 기준: `pnpm test` 통과

### 3차 이터레이션: 수식 표시

- `components/math/KatexRenderer.tsx`
- KaTeX CSS import
- `/play`에 임시 문제 하나 표시
- 완료 기준: 브라우저에서 `-2(3 - 6)` 같은 수식이 KaTeX로 표시됨

### 4차 이터레이션: 한 문제 풀기

- 답 입력 UI
- 제출 버튼
- 채점 결과 표시
- 아직 Zustand 없이 `useState`만 사용해도 충분함
- 완료 기준: 한 문제를 풀고 정답/오답 피드백 확인

### 5차 이터레이션: 10문제 세션

- 이때 Zustand 도입
- `initSession`
- `submitAnswer`
- `nextProblem`
- `score`
- 완료 기준: 10문제 풀이 후 점수 화면 표시

### 6차 이터레이션: UX 다듬기

- ProgressBar
- FeedbackBanner
- ScoreSummary
- Framer Motion은 이 단계에서 도입해도 충분함

## Claude 계획에서 조정하면 좋은 점

Claude의 계획에서 가장 조정하면 좋은 부분은 **Zustand와 Framer Motion을 너무 빨리 넣지 않는 것**이다.

첫 기능의 핵심은 다음 세 가지다.

1. 문제를 정확히 만든다.
2. 문제를 화면에 보여준다.
3. 사용자의 답을 채점한다.

상태 관리와 애니메이션은 이 기본 동작이 확인된 뒤 붙이는 편이 단계별 바이브 코딩에 더 잘 맞는다.

## 단계별 바이브 코딩 진행 방식

매 단계마다 아래 순서를 따른다.

```text
1. 이번 단계 목표를 한 문장으로 정한다
2. 수정할 파일을 2~4개 이하로 제한한다
3. 완료 기준을 명확히 둔다
4. 실행해서 직접 확인한다
5. 다음 단계로 넘어가기 전에 짧게 회고한다
```

## 다음 요청 예시

첫 개발 요청은 이렇게 주면 좋다.

> 1차 이터레이션으로 Next.js 14 프로젝트를 초기화하고, 시작 화면과 `/play` 페이지 이동까지만 구현해줘. AGENTS.md 규칙을 따르고, 아직 문제 생성 엔진이나 DB/Auth/Redis는 만들지 마.

그 다음 요청은 이렇게 이어갈 수 있다.

> 2차 이터레이션으로 `lib/engine/`에 괄호 앞 음수 분배 문제 생성 엔진과 Vitest 단위 테스트를 추가해줘. UI는 건드리지 마.

이런 식으로 “이번 단계에서 하지 않을 것”을 함께 말하면 범위가 잘 고정된다.

현재 프로젝트는 아직 파일이 거의 없는 초기 상태이므로, 위 방식으로 진행하면 작은 단위로 확인하면서 안정적으로 기능을 쌓아갈 수 있다.