From 0f51d9762a2771b8b06f0e107f522e3f4cdb119b Mon Sep 17 00:00:00 2001
From: jisangs <jisangs@gmail.com>
Date: Thu, 21 May 2026 21:44:16 +0900
Subject: [PATCH] =?UTF-8?q?=ED=94=84=EB=A1=9C=EC=A0=9D=ED=8A=B8=20?=
 =?UTF-8?q?=ED=81=B0=20=EC=84=A4=EA=B3=84=EB=8F=84=20=EB=93=B1=EB=A1=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .idea/.gitignore |  10 +++
 AGENTS.md        | 157 +++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md        |   1 +
 3 files changed, 168 insertions(+)
 create mode 100644 .idea/.gitignore
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.idea/.gitignore b/.idea/.gitignore
new file mode 100644
index 0000000..93bca08
--- /dev/null
+++ b/.idea/.gitignore
@@ -0,0 +1,10 @@
+# 디폴트 무시된 파일
+/shelf/
+/workspace.xml
+# 에디터 기반 HTTP 클라이언트 요청
+/httpRequests/
+# 쿼리 파일을 포함한 무시된 디폴트 폴더
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..89e89ed
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,157 @@
+# AGENTS.md
+
+AI 에이전트(Claude Code 등)가 이 프로젝트에서 작업할 때 따라야 할 규칙과 맥락을 정의합니다.
+
+---
+
+## 프로젝트 개요
+
+중학교 2학년 대상 **수학 실수 유형 반복 연습** 교육용 게임 서비스.
+문제 생성은 AI 없이 자체 알고리즘 엔진으로 처리한다.
+
+---
+
+## 기술 스택 요약
+
+| 레이어 | 기술 |
+|---|---|
+| 프레임워크 | Next.js 14 (App Router) + TypeScript 5 |
+| 스타일 | Tailwind CSS 3 |
+| 상태 관리 | Zustand |
+| 수식 렌더링 | KaTeX |
+| 애니메이션 | Framer Motion |
+| 인증 | NextAuth.js 4 |
+| ORM | Prisma (MariaDB 11) |
+| 캐시 | Redis 7 |
+| 유효성 검증 | Zod |
+| 패키지 매니저 | pnpm |
+| 테스트 | Vitest (단위) / Playwright (E2E) |
+
+---
+
+## 디렉토리 구조 및 파일 위치 규칙
+
+```
+app/                        # Next.js App Router 루트
+  (game)/                   # 게임 화면 라우트 그룹
+    select-type/            # 문제 유형 선택
+    select-mode/            # 게임 모드 선택
+    play/                   # 문제 풀이
+  api/
+    auth/                   # NextAuth.js 핸들러
+    problem/                # 문제 생성 API
+    record/                 # 풀이 기록 저장 API
+  layout.tsx
+  page.tsx                  # 시작 화면
+components/
+  math/                     # KaTeX 수식 컴포넌트
+  game/                     # 게임 UI 컴포넌트
+lib/
+  engine/                   # 문제 생성 알고리즘 엔진
+  prisma.ts                 # Prisma Client 싱글턴
+  redis.ts                  # Redis Client 싱글턴
+store/
+  gameStore.ts              # Zustand 전역 게임 상태
+prisma/
+  schema.prisma             # MariaDB 모델 정의
+.gitea/workflows/deploy.yml # CI/CD 워크플로우
+```
+
+---
+
+## 코드 작성 규칙
+
+### Next.js / React
+
+- 페이지 컴포넌트는 반드시 `app/` 디렉토리에 위치한다.
+- 클라이언트 컴포넌트에는 `'use client'` 지시어를 파일 최상단에 명시한다.
+- 서버 컴포넌트가 기본값이므로, 클라이언트 기능(훅, 이벤트)이 필요할 때만 `'use client'`를 붙인다.
+
+### 수식 렌더링
+
+- 모든 수학 수식은 KaTeX로 렌더링한다. 일반 텍스트나 Unicode 수식 문자를 직접 사용하지 않는다.
+- KaTeX 컴포넌트는 `components/math/` 하위에 위치한다.
+
+### 상태 관리
+
+- 전역 게임 상태(점수, 진행도, 선택한 모드·유형)는 `store/gameStore.ts`의 Zustand store로 관리한다.
+- 컴포넌트 내부의 로컬 상태는 `useState`를 사용한다.
+
+### API / 백엔드
+
+- API는 `app/api/` 하위의 Route Handlers로만 구현한다. 별도의 백엔드 서버를 추가하지 않는다.
+- 모든 API 요청 입력값은 Zod 스키마로 검증한다.
+- DB 접근은 `lib/prisma.ts`의 Prisma Client 싱글턴을 통해서만 한다.
+- Redis 접근은 `lib/redis.ts`의 Redis Client 싱글턴을 통해서만 한다.
+
+### 문제 생성 엔진
+
+- 문제 생성 로직은 `lib/engine/` 하위에 위치한다.
+- 문제는 AI 호출 없이 알고리즘으로 생성한다. 외부 AI API를 문제 생성에 사용하지 않는다.
+- 미지수의 계수는 항상 정수이어야 한다.
+- 생성 파라미터: 숫자 자릿수, 괄호 깊이(`()` / `(){}` / `(){}[]`), 괄호 개수(1–3), 미지수(없음/x/x,y/x,y,z).
+
+---
+
+## 환경변수
+
+새로운 환경변수를 추가할 때는 `.env.example`에 키 이름만 추가하고 값은 비워둔다.
+`.env.local`은 절대 Git에 커밋하지 않는다.
+
+```
+DATABASE_URL=mysql://user:pass@mariadb:3306/mathgame
+REDIS_URL=redis://redis:6379
+NEXTAUTH_SECRET=your-secret
+```
+
+---
+
+## 보안 규칙
+
+- `.env.local`을 Git에 커밋하거나 코드에 하드코딩하지 않는다.
+- MariaDB, Redis 포트는 컨테이너 내부 통신 전용이다. 외부 노출 설정을 추가하지 않는다.
+- SQL 쿼리는 반드시 Prisma를 통해 실행한다. Raw query 사용 시 파라미터 바인딩을 반드시 사용한다.
+- 사용자 입력은 API 경계에서 Zod로 검증한다. 클라이언트 측 검증만으로 보안을 의존하지 않는다.
+
+---
+
+## 게임 도메인 컨텍스트
+
+### 문제 유형
+
+1. **괄호 음수 분배**: 괄호 앞 음수 곱셈 시 괄호 내 부호 변경 (예: `-2 × (3 - 6)`)
+2. **이항 부호 변경**: 등식의 항을 이항할 때 부호 반전 (예: `3x - 5y + 8 = -2x + 2y - 2`)
+
+### 게임 모드
+
+| 모드 | 설명 |
+|---|---|
+| 스피드 퀴즈 | 제한 시간 내 최대 문제 풀기, Redis Sorted Set 기반 실시간 점수판 |
+| 일반 풀이 | 시간 제한 없음, 틀린 유형 반복 출제 |
+
+### 화면 흐름
+
+```
+시작 화면 → 문제 유형 선택 → 게임 모드 선택 → 문제 풀이 → 결과 및 기록
+```
+
+---
+
+## CI/CD
+
+- `.gitea/workflows/deploy.yml`이 CI/CD 진입점이다. main 브랜치 push 시 자동으로 빌드·배포된다.
+- 패키지 설치는 반드시 `pnpm`을 사용한다. `npm` / `yarn` 명령을 사용하지 않는다.
+- 배포 환경: Synology NAS + Docker Compose + Nginx Proxy Manager.
+
+---
+
+## 작업 시 체크리스트
+
+새 기능 또는 수정 작업 전에 다음을 확인한다.
+
+- [ ] 클라이언트 컴포넌트에 `'use client'` 선언 여부
+- [ ] 수식이 KaTeX로 렌더링되는지 여부
+- [ ] API 입력값이 Zod로 검증되는지 여부
+- [ ] DB 접근이 Prisma 싱글턴을 통하는지 여부
+- [ ] 환경변수가 `.env.local`에만 존재하는지 여부 (`.env.example`에 키 이름 추가)
+- [ ] 문제 생성 로직이 `lib/engine/` 내에서 알고리즘으로만 처리되는지 여부
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..eef4bd2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
\ No newline at end of file