# Codex Handoff Guide

## 목적
- 이 문서는 다른 작업 환경이나 다른 Codex 세션에서 프로젝트를 이어받더라도 같은 품질 기준으로 작업하기 위한 운영 기준서다.
- 특히 이 저장소는 정적 HTML/JS 프로젝트이면서 카드 데이터와 이미지 자산 비중이 크기 때문에, "코드 수정"보다 "데이터-번역-이미지 일치"가 더 중요하다.

## 현재 기준 릴리즈
- 현재 작업 기준 버전: `v3.1.0`
- 이번 릴리즈 핵심 반영:
- `ua51` 시리즈 추가
- `ua49` 누락 병렬 이미지 보강
- 다국어 시리즈명 추가
- 버전 표기 및 문서 체계 정리

## 다음 작업자에게 반드시 전달할 것
- 이 프로젝트는 빌드 시스템 중심 앱이 아니라 `index.html`, `cardList.html`, `result.html` 3개 페이지가 직접 동작하는 정적 사이트다.
- 신규 시리즈를 추가할 때는 항상 아래 3가지를 한 세트로 본다.
- `datas/<series>.js`
- `images/<series>/`
- `i18n/translations.ko.json`, `i18n/translations.ja.json`, `i18n/translations.en.json`
- 이미지 자산은 `images/**` 전체가 `Git LFS` 대상이다. 대용량 이미지가 일반 Git 객체로 들어가지 않게 주의한다.
- `cardList.html`은 `?series=<seriesKey>` 값을 기준으로 `./datas/${seriesKey}.js`를 동적 import 한다. 즉, 시리즈 키 불일치가 있으면 화면에서 바로 깨진다.
- 카드 이미지 렌더링은 최종적으로 `images/${seriesKey}/${fileName}` 규칙을 사용하므로, `imgSrc`에는 파일명 기준 일관성이 중요하다.
- 릴리즈 버전이 바뀌면 최소한 아래 두 곳은 함께 맞춘다.
- `index.html`의 `<title>` 및 상단 배지
- `docs/spec.md`, `docs/update.md`, 필요 시 `docs/history.md`

## 품질 기준
- 신규 시리즈 반영 시 데이터 파일만 추가하고 번역 키를 빼먹지 않는다.
- 카드 번호(`Number`) 그룹과 실제 파일명 규칙이 시리즈 키와 일치해야 한다.
- 병렬 카드(`parallel: true`)는 일반 카드와 같은 카드 번호를 공유하되 이미지 파일만 다르게 유지한다.
- `trigger`는 `null`, `COLOR`, `FINAL`, `SPECIAL`만 사용한다.
- AP 카드의 `color`는 `AP`를 사용한다.
- 릴리즈 전에 `git diff --stat`으로 변경 범위를 보고, 데이터/번역/이미지 중 빠진 축이 없는지 확인한다.

## 작업 절차
1. 변경 요청이 신규 시리즈 추가인지, 기존 시리즈 수정인지 먼저 구분한다.
2. 관련 `datas/*.js`와 `images/<series>/` 상태를 확인한다.
3. `i18n/translations.*.json`에 시리즈명 또는 UI 문구 변경이 필요한지 확인한다.
4. 화면에서 버전 표기를 바꿔야 하는 성격의 변경인지 판단한다.
5. `docs/update.md`에 이번 반영 내용을 남긴다.
6. 릴리즈성 변경이면 `docs/history.md` 또는 이 문서에도 기준 변화를 남긴다.
7. 커밋 전 `git status`, `git diff --stat`, 필요한 경우 간단한 구문 체크를 수행한다.

## 릴리즈 전 체크리스트
- `datas/<series>.js`가 실제로 import 가능한 형식인지 확인
- `images/<series>/` 파일이 데이터의 `imgSrc`와 대응되는지 확인
- `translations.ko/ja/en`에 시리즈 키가 모두 존재하는지 확인
- 버전 표기가 문서와 UI에서 일치하는지 확인
- `images/**`가 계속 LFS로 잡히는지 확인
- 커밋 메시지에 릴리즈 의도가 드러나는지 확인

## 커밋 메시지 가이드
- 릴리즈 커밋 예시: `v3.1.0: add ua51 series and handoff docs`
- 수정 커밋 예시: `fix: add missing ua49 parallel images`
- 되돌림 커밋 예시: `revert: restore original card list interactions`

## 주의할 점
- 이 저장소는 이미지 비중이 매우 크다. 원격 업로드 전에 대용량 변경이 의도된 것인지 다시 확인한다.
- 현재 문서 체계는 `docs/update.md`가 작업 로그, `docs/history.md`가 의사결정, `docs/spec.md`가 구조 명세 역할을 맡는다.
- 후속 작업자가 빠르게 맥락을 잡게 하려면, "무엇을 바꿨는지"보다 "왜 같이 바꿔야 하는지"를 문서에 남기는 편이 더 중요하다.