uniare.sori.studio/docs/codex-handoff.md

작업 인계 가이드

Handoff(핸드오프)란?

다른 개발자나 운영 담당자가 지금 작업을 이어받을 때 빠르게 상황을 이해하도록 정리한 문서입니다. 비개발자에게는 '작업 인수인계 노트'라고 생각하면 됩니다.

우선 확인

1. 프로젝트 루트 AGENTS.md
2. docs/spec.md
3. docs/todo.md
4. docs/history.md
5. docs/convention.md
6. docs/map.md
7. docs/deploy.md

현재 버전은 루트 VERSION을 기준으로 확인한다.

프로젝트 핵심

• 정적 HTML·JavaScript 프론트와 Express·SQLite API를 함께 사용한다.
• 운영은 docker-compose.prod.yml의 uniare-web, uniare-api 구성이 기본이다.
• 덱 공유는 /d/<shareCode>와 GET /api/v1/decks/:shareCode를 사용한다.
• ?cards=<JSON> 공유 방식은 사용하지 않는다.
• 표시 브랜드는 UNIARE지만 UaDeckApi, uadeck_token, uadeck.db 등 내부 식별자는 호환을 위해 유지한다.

카드 데이터 작업

신규 시리즈 또는 카드는 아래 항목을 한 세트로 확인한다.

datas/<series>.js
images/<series>/
i18n/translations.ko.json
i18n/translations.ja.json
i18n/translations.en.json

• imgSrc와 실제 이미지 파일명이 일치해야 한다.
• 동일 카드의 패러렐 판본은 같은 Number를 사용한다.
• images/**는 Git LFS 대상이다.
• datas/ 변경 후 API 카드 캐시를 갱신하려면 uniare-api를 재시작한다.

변경 후 문서

• 현재 구현 변경: spec.md
• 이번 작업 기록: update.md
• 결정 이유: history.md
• 남은 작업: todo.md
• 사용자 공개 변경: changelog.md
• 파일 역할 변경: map.md
• 배포 절차 변경: deploy.md

검증

git diff --check
git status --short

변경 성격에 따라 다음도 확인한다.

• HTML·정적 자산: 브라우저 새로고침
• datas/: API 재시작 후 카드 목록과 저장 덱 조회
• API 코드: Docker 재빌드와 /api/v1/health
• Tailwind 클래스: npm run build:css

커밋

• 커밋 메시지는 한국어로 작성한다.
• 커밋하는 완료 작업은 VERSION을 증가시킨다.
• 민감 정보와 api/data/ 운영 파일을 커밋하지 않는다.