4.1 KiB
4.1 KiB
Codex Handoff Guide
목적
- 이 문서는 다른 작업 환경이나 다른 Codex 세션에서 프로젝트를 이어받더라도 같은 품질 기준으로 작업하기 위한 운영 기준서다.
- 특히 이 저장소는 정적 HTML/JS 프로젝트이면서 카드 데이터와 이미지 자산 비중이 크기 때문에, "코드 수정"보다 "데이터-번역-이미지 일치"가 더 중요하다.
현재 기준 릴리즈
- 현재 작업 기준 버전:
v3.1.0 - 이번 릴리즈 핵심 반영:
ua51시리즈 추가ua49누락 병렬 이미지 보강- 다국어 시리즈명 추가
- 버전 표기 및 문서 체계 정리
다음 작업자에게 반드시 전달할 것
- 이 프로젝트는 빌드 시스템 중심 앱이 아니라
index.html,cardList.html,result.html3개 페이지가 직접 동작하는 정적 사이트다. - 신규 시리즈를 추가할 때는 항상 아래 3가지를 한 세트로 본다.
datas/<series>.jsimages/<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으로 변경 범위를 보고, 데이터/번역/이미지 중 빠진 축이 없는지 확인한다.
작업 절차
- 변경 요청이 신규 시리즈 추가인지, 기존 시리즈 수정인지 먼저 구분한다.
- 관련
datas/*.js와images/<series>/상태를 확인한다. i18n/translations.*.json에 시리즈명 또는 UI 문구 변경이 필요한지 확인한다.- 화면에서 버전 표기를 바꿔야 하는 성격의 변경인지 판단한다.
docs/update.md에 이번 반영 내용을 남긴다.- 릴리즈성 변경이면
docs/history.md또는 이 문서에도 기준 변화를 남긴다. - 커밋 전
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가 구조 명세 역할을 맡는다. - 후속 작업자가 빠르게 맥락을 잡게 하려면, "무엇을 바꿨는지"보다 "왜 같이 바꿔야 하는지"를 문서에 남기는 편이 더 중요하다.