게임 스터디용 CLAUDE.md 템플릿

처음 바이브코딩으로 게임을 만드는 스터디원을 위한 기본 세팅 — 폴더 구조, 모바일 대응, 칩튠 사운드, Vercel 배포, git 관리까지. 새 저장소의 CLAUDE.md로 붙여넣고 시작하세요.

# CLAUDE.md — 바이브코딩 게임 스터디 기본 세팅

이 저장소는 내가 만드는 웹게임 모음집입니다. 아래 지침에 따라 게임 제작을 도와주세요.

## 기본 원칙

- **언어**: 항상 한국어로 대화합니다.
- 사용자는 프로그래밍이 처음일 수 있습니다. **쉬운 말로 설명**하고, 전문용어는 꼭 필요할 때만 한 줄로 풀어서 씁니다.
- 사용자가 한 말이 틀리다고 생각하면 언제든지 틀리다고 말해주세요.
- **작게 만들고 자주 보여주기**: 한 번에 완성하지 말고 "움직이는 것 → 목표 → 점수 → 게임오버 → 꾸미기" 순서로, 단계마다 브라우저에서 확인시켜 주세요.
- 완성 후 개선은 **한 번에 한 가지씩** 진행합니다.

## 프로젝트 구조

루트의 index.html이 게임 목록(포털) 페이지이고, **게임 1개 = 폴더 1개**입니다.

```
my-games/
├── index.html          # 게임 목록 페이지 (썸네일 카드형)
├── thumbs/             # 목록용 썸네일 이미지 (게임이름.png)
├── snake-run/          # 게임 폴더 (영문 소문자-하이픈)
│   ├── index.html
│   ├── style.css
│   ├── game.js
│   └── sound.js        # 사운드 코드 (분리 권장)
└── ...
```

**새 게임을 만들 때마다, 별도 요청이 없어도 아래를 항상 완료합니다:**

1. 게임 이름으로 폴더 생성 (영문 소문자-하이픈, 예: snake-run)
2. 게임 제작 (아래 "게임 기본기" 기본 적용)
3. 썸네일 제작 → thumbs/에 저장
4. **목록 페이지(index.html)에 카드 추가** — 게임 링크 + 썸네일 + 제목 + 한 줄 설명
5. 링크와 썸네일 경로가 실제 파일과 일치하는지(데드링크 없는지) 확인

## 게임 기본기 (요청 없어도 모든 게임에 기본 적용)

- **양쪽 화면 대응**: 모바일과 데스크탑 양쪽에서 적절한 크기로 잘 보이고 플레이할 수 있어야 합니다. viewport 메타태그 필수, 캔버스는 화면 크기에 맞춰 리사이즈(내부 해상도와 CSS 크기 분리).
- **조작**: 터치와 마우스 조작을 기본으로 하되, 데스크탑을 위한 **기본 키보드 매핑**(화살표/WASD/스페이스 등)도 함께 넣습니다. 터치 버튼은 최소 44px, touchstart에 preventDefault로 화면 스크롤/확대 방지, 화살표 키도 preventDefault로 페이지 스크롤 방지.
- **게임 루프**: requestAnimationFrame + deltaTime 기반 이동(기기 속도와 무관하게 같은 속도). setInterval로 게임 루프를 만들지 않습니다.
- **키 입력**: keydown/keyup으로 눌림 상태(Set/객체)를 관리합니다. keydown만으로 이동하면 끊깁니다.
- **상태 흐름**: 시작 화면 → 플레이 → 게임오버/클리어 → **재시작 버튼** 한 사이클이 항상 완성돼야 하고, 새로고침 없이 다시 플레이할 수 있어야 합니다(재시작 시 변수 초기화 확인).
- **점수 기록**: 점수가 있는 게임은 **개발놀이터 오락실 랭킹 API로 서버에 저장하는 것을 기본**으로 합니다(아래 "오락실 랭킹 연동" 참고). 점수 저장처를 localStorage와 서버 두 곳으로 나누지 않습니다 — 기록은 한 곳에만 있어야 관리가 쉽습니다.
- **일시정지**: P 키 또는 버튼. 탭이 백그라운드로 가면 자동 일시정지(visibilitychange) — deltaTime 폭주로 인한 순간이동 방지.
- **성능**: 화면 밖 객체는 제거, 객체 수 상한, 이미지/오디오는 시작 전에 미리 로드.
- **한글**: meta charset은 utf-8 필수.

## 사운드 (요청 없어도 기본 포함)

- **기본은 칩튠(chiptune)**: Web Audio API로 8비트풍 효과음과 배경음악을 **코드로 생성**해 넣습니다. (AudioContext + OscillatorNode(square/triangle) + GainNode — 오디오 파일 없이 코드만으로.)
- 브라우저 정책상 오디오는 **사용자가 처음 클릭/터치한 뒤에만** 재생됩니다. 시작 버튼에서 audioCtx.resume()을 호출하세요.
- **음소거 버튼을 항상** 넣습니다 (효과음 + BGM 한꺼번에).
- 사운드 코드는 sound.js로 분리하면 다음 게임에서 재사용하기 좋습니다.

## 이미지

- 처음에는 **이모지/도형/CSS만으로도 충분**합니다. 그래픽보다 게임을 먼저 완성하세요.
- 그래픽을 업그레이드할 때: **Codex를 사용 중이라면 imggen 스킬로 이미지를 생성**하는 것을 고려해 진행합니다.
- 생성한 이미지는 게임 폴더 안에 저장하고 함께 커밋합니다.
- 썸네일은 게임의 대표 장면 캡처 또는 생성 이미지를 정사각형으로 만들어 thumbs/에 둡니다.

## 개발놀이터 오락실 랭킹 연동 (점수 기록의 기본)

점수가 있는 게임은 스터디 오락실 랭킹으로 점수를 기록합니다. 스터디원들과 랭킹으로 경쟁할 수 있고, 점수 저장·로그인·랭킹 UI를 SDK가 대신 처리해 줍니다.

- https://game.dev-play.kr/api-guide.php 의 지침을 읽고 그대로 적용하세요.
- 핵심은 두 가지: rank.js SDK 스크립트 추가 + 게임오버 시 DevplayRank.submitScore(점수) 호출. selfRegister 옵션으로 게임이 오락실 목록에 자동 등록됩니다.
- 로그인하지 않고 플레이해도 SDK가 점수를 잠시 보관했다가 로그인 시 자동 제출하므로, 게임 쪽에서 따로 처리할 것이 없습니다.
- 점수 개념이 없는 게임(방탈출 일회성 등)만 연동을 생략합니다.

## Vercel 배포

- 이 저장소는 **정적 사이트**로 Vercel에 배포합니다. 빌드 설정이 필요 없습니다(Framework Preset: Other).
- **최초 1회 연결**: GitHub에 저장소를 만들어 push → vercel.com에서 Add New Project → 저장소 import. 이후에는 **main 브랜치에 push할 때마다 자동 배포**됩니다.
- CLI를 쓰는 경우: npx vercel --prod
- 경로는 **상대 경로**를 사용합니다(./thumbs/snake-run.png 처럼). 서브 폴더에서 절대 경로(/)를 쓰면 배포 루트 기준이라 어긋날 수 있습니다.
- 배포 후에는 배포 URL에서 목록 페이지 → 새 게임까지 실제로 열리는지 확인합니다.

## Git 관리 (알아서 진행)

- 저장소가 git이 아니면 git init부터. .gitignore에 .DS_Store, node_modules 등을 넣습니다.
- **작업 단위마다 커밋**하고, 게임 하나를 완성하거나 수정을 마무리하면 커밋 → push까지 합니다. (push가 곧 배포입니다.)
- 커밋 메시지는 한국어로 간결하게: "스네이크 게임 추가", "점프 판정 버그 수정"
- API 키, 비밀번호, .env 파일은 **절대 커밋하지 않습니다.**

## 배포 전 테스트 (1분 체크)

1. 브라우저 콘솔에 빨간 에러가 없는가?
2. 시작 → 플레이 → 게임오버 → 재시작이 한 번에 되는가?
3. 소리가 나는가? 음소거 버튼이 동작하는가?
4. 휴대폰 크기로 줄여도 보이고 플레이 가능한가?
5. 목록 페이지의 링크·썸네일이 실제 파일과 일치하는가?
6. 점수 게임이라면: 게임오버 시 점수 제출이 호출되고 랭킹 버튼이 보이는가?