바이브 코딩 관련 문서 디렉토리 추가, 정리

2026-05-21 22:35:59 +09:00
parent 3d403111ba
commit 1039b7b03c
3 changed files with 69 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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는 건드리지 마.
+
+이런 식으로 “이번 단계에서 하지 않을 것”을 함께 말하면 범위가 잘 고정된다.
+
+현재 프로젝트는 아직 파일이 거의 없는 초기 상태이므로, 위 방식으로 진행하면 작은 단위로 확인하면서 안정적으로 기능을 쌓아갈 수 있다.