math-quiz/docs/vibe/01-project-start.md

01. 프로젝트 시작 화면과 라우팅

목표

Next.js 14 프로젝트를 초기화하고, 시작 화면에서 문제 풀이 화면(/play)으로 이동할 수 있는 가장 작은 앱 흐름을 만든다.

이번 단계에서 할 것

• Next.js 14 App Router 기반 프로젝트를 초기화한다.
• TypeScript, Tailwind CSS, ESLint를 함께 설정한다.
• 루트 시작 화면(/)을 만든다.
• 문제 풀이 화면(/play)을 만든다.
• 시작 화면의 버튼 또는 링크를 통해 /play로 이동할 수 있게 한다.
• pnpm dev로 앱 실행을 확인한다.

이번 단계에서 하지 않을 것

• 문제 생성 엔진 구현
• KaTeX 수식 렌더링
• 답 입력 및 채점 UI
• Zustand 상태 관리
• Framer Motion 애니메이션
• DB, Prisma, Redis, NextAuth 설정
• 유형 선택 화면
• 모드 선택 화면
• 테스트 환경 구성

수정 또는 생성 예상 파일

프로젝트 초기화 후 다음 파일들이 핵심 확인 대상이 된다.

• app/layout.tsx
• app/page.tsx
• app/(game)/play/page.tsx
• app/globals.css
• package.json
• tailwind.config.ts
• tsconfig.json

작업 순서

1. pnpm create next-app@14 . --typescript --tailwind --eslint --app --no-src-dir --import-alias "@/*"로 프로젝트를 초기화한다.
2. 생성된 기본 파일 구조를 확인한다.
3. app/page.tsx를 시작 화면으로 정리한다.
4. app/(game)/play/page.tsx를 추가해 빈 풀이 화면을 만든다.
5. 시작 화면에서 /play로 이동하는 링크를 추가한다.
6. pnpm dev를 실행해 브라우저에서 화면 이동을 확인한다.

화면 흐름

/ 시작 화면
  - 괄호 음수 분배 연습 시작
  - 시작 버튼 클릭

        ↓

/play 풀이 화면
  - 아직 실제 문제는 표시하지 않음
  - 다음 단계에서 문제 생성 엔진과 연결 예정

시작 화면 초안

시작 화면은 기능 소개보다 바로 연습을 시작할 수 있는 간단한 화면으로 만든다.

• 제목: 괄호 음수 분배 연습
• 보조 문구: 괄호 앞의 음수를 분배할 때 부호가 어떻게 바뀌는지 연습한다.
• 주요 액션: 연습 시작

풀이 화면 초안

/play 화면은 아직 실제 문제 풀이 기능을 넣지 않는다.

• 제목: 문제 풀이
• 보조 문구: 다음 단계에서 괄호 음수 분배 문제가 표시된다.
• 돌아가기 링크: 처음으로

완료 기준

• pnpm dev가 정상 실행된다.
• 브라우저에서 / 페이지가 열린다.
• 시작 화면에서 “연습 시작”을 누르면 /play로 이동한다.
• /play에서 “처음으로”를 누르면 /로 돌아온다.
• 콘솔에 명백한 런타임 오류가 없다.

확인 명령

pnpm dev

필요하면 초기화 직후 다음 명령으로 정적 검사를 확인한다.

pnpm lint

작업 결과

• Next.js 14 App Router 프로젝트를 초기화했다.
• TypeScript, Tailwind CSS, ESLint 설정을 추가했다.
• / 시작 화면을 만들었다.
• /play 풀이 화면을 만들었다.
• 시작 화면의 “연습 시작” 링크로 /play 이동을 확인했다.
• /play 화면의 “처음으로” 링크로 / 복귀를 확인했다.
• pnpm lint 통과를 확인했다.
• pnpm dev 실행 후 브라우저에서 화면 이동을 확인했다.

다음 단계

02-parenthesis-sign-engine.md에서 괄호 앞 음수 분배 문제 생성 엔진을 만든다.

다음 단계에서는 UI를 확장하지 않고, lib/engine/ 아래에 순수 TypeScript 함수와 단위 테스트를 먼저 추가한다.