union-arena-deck-builder/docs/history.md

# 의사결정 이력

## 2026-04-19 / v3.1.0 릴리즈 기준 확정
- 배경: 저장소의 마지막 명시 릴리즈 기록은 `v3.0.1`인데, 메인 화면은 이미 `v3.1`을 노출하고 있어 실제 릴리즈 이력과 화면 표기가 어긋나 있었다.
- 결정:
- 이번 반영분을 `v3.1.0`으로 정의하고, 화면 표기와 문서 표기를 같은 버전으로 통일한다.
- 이후 버전 증가는 `docs/update.md`에 먼저 기록한 뒤 화면 표기와 함께 반영한다.
- 이유:
- 외부 협업자나 후속 Codex 작업자가 "현재 배포 기준이 무엇인지" 즉시 판단할 수 있어야 한다.
- 자산 중심 정적 프로젝트 특성상 코드보다 데이터/이미지 변경이 잦기 때문에, 명시 릴리즈 기준이 없으면 누락 여부를 추적하기 어렵다.

## 2026-03-30 / 문서 체계 초기화
- 배경: 프로젝트 루트에 AI 작업 규칙은 있었지만 `docs/` 실체가 없어 규칙과 실제 운영 상태가 분리되어 있었다.
- 결정: 규칙 문서가 요구하는 핵심 문서 6종을 먼저 생성하고, 이후 변경 시 이 파일들을 기준 문서로 유지한다.
- 기대 효과: 작업 내역, 기술 구조, 화면-파일 연결, 향후 할 일을 한곳에서 추적할 수 있다.

## 2026-03-30 / 이미지 관리 방식 1차 판단
- 배경: `images/` 디렉터리 용량이 약 `1.7G`, 파일 수가 `9,370개` 수준으로 증가했다.
- 관찰:
- 개별 파일이 아주 크지 않아도 Git 일반 객체로 누적되면 clone 및 fetch 비용이 계속 증가한다.
- 이미지 추가가 잦은 프로젝트 특성상 저장소 히스토리 비대화가 반복될 가능성이 높다.
- 결정:
- 신규 이미지 유입 관리 목적이라면 `Git LFS` 도입을 권장한다.
- 단, 이미 커진 저장소를 즉시 가볍게 만드는 해결책으로 `Git LFS`만 기대해서는 안 된다.
- 히스토리 크기까지 줄여야 하면 `git lfs migrate` 또는 자산 저장소 분리/CDN 이전을 별도 의사결정으로 다룬다.
- 보류 사유:
- 원격 저장소의 LFS 지원 여부, 무료 용량, 대역폭 정책을 아직 확인하지 않았다.
- 기존 협업자들의 개발 환경에 `git lfs` 설치를 요구하게 되므로 도입 공지가 필요하다.

## 2026-03-30 / 이미지 히스토리 전체 LFS 마이그레이션 결정
- 배경: 목적이 "앞으로 예방"이 아니라 "기존 저장소 용량 절감"으로 명확해졌다.
- 확인:
- 로컬 환경에 `git lfs`가 설치되어 있다.
- 원격 저장소에 LFS 엔드포인트가 설정되어 있다.
- 결정:
- `images/**` 전체 히스토리를 `Git LFS`로 마이그레이션한다.
- 현재 작업 중인 `ua27` 데이터 및 이미지 추가분도 함께 반영한다.
- 영향:
- 기존 커밋 해시가 모두 재작성된다.
- 원격 반영 시 강제 푸시가 필요하다.
- 협업 중인 다른 클론은 재동기화 절차가 필요하다.

## 2026-03-30 / 새 루트 커밋 기준 저장소 재시작 결정
- 배경: `images/**`는 LFS 포인터로 전환됐지만, 저장소 자체는 과거 Git 객체 영향으로 여전히 비대했다.
- 결정:
- 현재 로컬 작업본을 단일 기준 스냅샷으로 보고 새 루트 커밋을 만든다.
- 원격 `main`은 새 루트 커밋으로 교체한다.
- 기존 히스토리는 로컬 백업 브랜치에서만 보존한다.
- 새 버전 체계는 `v3.0.0`부터 다시 시작한다.
- 이미지 자산은 새 시작 이후에도 `Git LFS` 정책을 유지한다.
- 이유:
- 가장 확실하게 Git 일반 히스토리 용량을 줄일 수 있다.
- 추가적인 서버 GC 상태나 숨은 과거 객체를 더 추적하지 않고도 정리 목적을 달성할 수 있다.