chore(docs): add codex greenfield prompts and Gemini review guide

.codex/prompt/new_preparation_checklist.md

@@ -0,0 +1,167 @@
+# Role
+당신은 소규모~중규모 백엔드 시스템의 그린필드 재구축 경험이 풍부한 시니어 백엔드 아키텍트입니다.
+"레거시 코드를 옮기는 것"이 아니라 **"레거시에서 명세(spec)를 추출한 뒤 코드는 폐기하고, 신규 레포에서 처음부터 DDD/MSA로 다시 만드는"** 전략을 다뤄본 경험이 있다고 가정하고 응답해주세요.
+
+# Context
+
+## 프로젝트 개요
+저는 현재 운영 중인 백엔드 프로젝트를 **완전히 새로운 Git 레포지토리, 새로운 프로젝트**에서 처음부터 다시 구축합니다.
+
+## 규모
+- **API 약 30개** 수준의 소규모 백엔드
+- 사용자 본인이 코드베이스 대부분을 파악 가능한 규모
+
+## 현재 상태 (Legacy)
+- 아키텍처: DDD 기반 아님, 도메인 경계 불명확
+- 단일 프로젝트 / 결합도 높음
+- 기술 스택: Java 21, Spring Boot 3.5.15, MySQL, Redis, Kafka
+
+## 목표 상태 (New)
+- 신규 Git 레포 + 신규 프로젝트 (그린필드)
+- 도메인별 MSA + DDD 적용
+- AI 에이전트를 적극 활용한 단계별 구축
+
+## 핵심 전략 (반드시 이 전략을 전제로 답변)
+이번 프로젝트는 일반적인 "점진적 마이그레이션(Strangler Fig)"을 **채택하지 않습니다.** 이유:
+1. API가 30개 수준으로 작아 점진적 이관의 오버헤드가 비효율적
+2. 그린필드의 가치는 "레거시 구조에서 자유로워지는 것"인데, 코드를 계속 참고하면 legacy gravity로 의사결정이 오염됨
+3. 검증 단계의 diff testing으로 누락 리스크를 흡수 가능
+
+따라서 **다음 3단계 전략**을 따릅니다.
+
+### Phase 0 — Spec Mining (레거시 정독 단계)
+- 기존 레포를 **이 단계에서만** 깊게 분석
+- 각 API의 명시적 로직뿐 아니라 **암묵적 로직(implicit logic)** 까지 추출
+    - 분기 조건, 예외 처리, null/empty 처리
+    - 외부 호출 순서, DB 트랜잭션 경계, 이벤트 발행 시점
+    - 코드 주석/변수명에서 추론 가능한 비즈니스 룰
+- 산출물: API별 상세 PRD (1 API = 1 markdown 파일)
+
+### Phase 0.5 — Spec 검증 및 분류
+- 추출된 PRD를 사람이 검토하여 항목별로 태깅:
+    - `@KEEP` — 의도된 로직, 신규에서도 유지
+    - `@DROP` — 우발적 로직(accidental complexity)/구버그/임시방편, 신규에서 제거
+    - `@FIX` — 버그였거나 개선 필요, 신규에서 수정
+- 산출물: 검증된 PRD (태그 포함)
+
+### Phase 1 이후 — 그린필드 구축
+- **기존 레포는 닫는다.** 이후 단계에서 절대 참조하지 않음
+- 검증된 PRD만 참고하여 DDD/MSA로 처음부터 구축
+- 에이전트에게도 "기존 코드 참고 금지, PRD만 참고" 명시
+
+### 검증 단계 — Diff Testing
+- 기존 시스템과 신규 시스템에 동일 입력을 주고 출력 비교
+- 차이점은 (a) 의도된 개선 / (b) 누락된 암묵적 로직 으로 분류하여 후자만 보완
+- 이 장치가 "기존 레포를 일찍 닫는" 전략의 안전망
+
+# Task
+이 그린필드 전략에 맞춰 **무엇을 어떤 순서로 준비해야 하는지** 상세한 준비 리스트(체크리스트)를 작성해주세요.
+
+단순 나열이 아니라, **"왜 필요한지"** 와 **"어떤 산출물이 나와야 하는지"** 를 함께 적어주세요.
+특히 위에 명시한 **3단계 전략(Spec Mining → 검증 → 그린필드 + Diff Testing)** 이 각 영역의 작업 항목에 어떻게 반영되는지를 명확히 해주세요.
+
+# 준비 리스트에 반드시 포함되어야 하는 영역
+
+1. **Spec Mining: 레거시 명세 추출** ⭐ (이 프로젝트의 핵심)
+    - "코드를 옮기는 게 아니라 명세를 추출한다"는 원칙을 어떻게 실현할지
+    - API별로 추출해야 할 항목 (분기, 예외, null 처리, 트랜잭션 경계, 이벤트 발행, 외부 호출 순서, 암묵적 비즈니스 룰)
+    - 추출 결과를 어떻게 문서화할지 (예: `legacy-specs/{domain}/{api-name}.md` 템플릿)
+    - 에이전트를 활용한 자동 추출 방법과 사람이 직접 봐야 하는 부분의 경계
+    - 30개 API 규모에서의 현실적 작업 순서와 공수 산정
+
+2. **Spec 검증 및 KEEP/DROP/FIX 분류** ⭐
+    - PRD 항목별로 의도된 로직/우발적 로직/버그를 어떻게 구분할지
+    - 태깅 컨벤션과 검토 프로세스
+    - 사용자 본인이 판단하기 어려운 항목(예: 외부 시스템 연동의 의도)을 어떻게 처리할지
+    - 산출물: 검증 완료된 PRD, `@DROP` 항목의 폐기 사유 기록
+
+3. **도메인 모델링 (DDD)**
+    - 검증된 PRD를 기반으로 한 Event Storming
+    - Bounded Context 도출, Context Map, Aggregate 식별
+    - Ubiquitous Language 정의 (이후 모든 에이전트 작업의 기준)
+
+4. **MSA 분리 전략 (소규모 맞춤)**
+    - **API 30개 규모에서 서비스를 몇 개로 쪼갤지에 대한 가이드** (과분할 경계 주의)
+    - 서비스 간 통신 방식 (동기 REST/gRPC vs 비동기 Kafka)
+    - 공유 데이터 처리 정책 (Saga/Outbox 등 — 정말 필요한가에 대한 검토 포함)
+    - 인증/인가 분리 전략
+
+5. **신규 레포지토리 및 프로젝트 초기 설계**
+    - **모노레포 vs 멀티레포** (소규모에서는 모노레포가 유리한 경우가 많음 — 판단 기준 제시)
+    - 디렉토리/모듈 구조 (DDD 레이어: domain / application / infrastructure / interfaces)
+    - 공통 모듈 전략 (common-core, common-event 등)
+    - 브랜치 전략, 커밋 컨벤션, PR 템플릿
+    - 코딩 컨벤션, 패키지 네이밍, Lint/Formatter
+    - **레퍼런스 서비스(reference service)** 를 1개 먼저 구축할지 여부와 그 이점
+
+6. **PRD 및 ADR 작성**
+    - 각 도메인별 To-Be PRD (Spec Mining 결과 + 개선사항)
+    - 주요 결정에 대한 ADR (예: "왜 모노레포인가", "왜 서비스를 N개로 쪼갰는가")
+
+7. **데이터 및 인프라 구성 (그린필드)**
+    - 신규 DB/Redis/Kafka를 **별도 구축**하는 것을 기본 전제로 (병행 운영 없음)
+    - DB 스키마 신규 설계 (레거시 스키마는 참고만, 답습하지 않음)
+    - 초기 데이터 이관이 필요한 경우의 일회성 마이그레이션 스크립트 전략
+    - Kafka 토픽 네이밍, Redis 키 네임스페이스 신규 설계
+
+8. **인프라 및 배포 준비**
+    - 신규 CI/CD 파이프라인
+    - 컨테이너/오케스트레이션, 환경 분리(dev/stg/prod)
+    - 관측성(OpenTelemetry, 로깅/메트릭/트레이싱) — 처음부터 표준 적용
+    - 시크릿/환경변수 관리
+
+9. **테스트 및 Diff Testing 검증 전략** ⭐
+    - 단위/통합/E2E 테스트 표준
+    - **Diff Testing 환경 구축**: 동일 입력을 레거시와 신규에 보내고 응답을 비교하는 방법
+        - 어떤 도구/프레임워크를 쓸 수 있는지 (예: 자체 비교 스크립트, Diffy류 도구)
+        - 어떤 차이는 무시하고 어떤 차이는 잡을지 (timestamp, 정렬 순서 등)
+        - 운영 트래픽 미러링 방식 vs 테스트 시나리오 기반 방식
+    - 신규 시스템 컷오버 전 검증 통과 기준
+
+10. **컷오버 전략 (Big Bang에 가까운 전환)**
+    - 점진적 이관이 아니므로 컷오버 시점을 어떻게 잡을지
+    - 사전 검증 통과 기준
+    - 컷오버 직전 데이터 동기화 (한 번만 수행)
+    - 롤백 시나리오 (단방향 진행이 위험할 경우의 안전장치)
+    - 클라이언트(프론트/외부 시스템) 호환성 확보 전략
+
+11. **AI 에이전트 활용 계획** ⭐
+    - 단계별 에이전트 역할 분리:
+        - **Spec Mining 에이전트** — 레거시 레포 읽기 전용, PRD 추출
+        - **검증 보조 에이전트** — KEEP/DROP/FIX 후보 제안
+        - **도메인 모델링 에이전트** — Event Storming 결과를 DDD 구조로 변환
+        - **코드 생성 에이전트** — 신규 레포 쓰기, 레거시 접근 차단
+        - **테스트 작성 에이전트** — Diff Testing 시나리오 생성
+    - 에이전트가 일관된 결과를 내도록 사전 준비할 자산:
+        - `.agent/PROJECT_CONTEXT.md`, `ARCHITECTURE.md`, `UBIQUITOUS_LANGUAGE.md`, `CODING_CONVENTIONS.md`
+        - 레퍼런스 서비스 코드
+        - 도메인별 코드 생성 프롬프트 템플릿
+    - **레거시 레포 접근 권한 분리**: Spec Mining 단계 이후에는 신규 작업 에이전트가 레거시 레포를 보지 못하도록 차단하여 legacy gravity 방지
+
+12. **리스크 및 마일스톤**
+    - 이 전략 특유의 리스크: 암묵적 로직 누락, Big Bang 컷오버 실패, 도메인 과분할
+    - 대응 방안: Spec Mining 깊이 확보, Diff Testing 충실도, MSA 분리 보수적 접근
+    - Phase별 마일스톤 (Phase 0 / 0.5 / 1 / ... / 컷오버)
+
+# Output Format
+아래 형식으로 작성해주세요.
+
+## [영역 번호]. [영역 이름]
+- **목적**: 이 단계가 왜 필요한가 (특히 그린필드 + Spec Mining 전략 맥락에서)
+- **세부 작업 항목**: 체크리스트 형태 (`- [ ]` 사용)
+- **산출물(Deliverables)**: 이 단계 종료 시 나와야 하는 문서/파일 (파일 경로까지 제시)
+- **권장 도구 또는 에이전트 활용 포인트**
+- **예상 소요 및 우선순위**: High / Medium / Low
+
+마지막에 다음 세 가지를 추가해주세요:
+1. **전체 진행 순서 (Phase별 로드맵)** — Phase 0 (Spec Mining) ~ 컷오버까지, 각 Phase의 입력/출력/완료 기준
+2. **신규 레포 초기 디렉토리 구조 예시** — Java 21 / Spring Boot 3.1.5 / DDD / MSA 기준의 폴더 트리 (`.agent/` 디렉토리 포함)
+3. **Spec Mining용 API 문서 템플릿** — 각 API당 추출해야 할 항목을 표준화한 markdown 템플릿
+
+# Constraints
+- Java 21 / Spring Boot 3.5.15 / MySQL / Redis / Kafka 기술 스택 전제로 구체적인 예시
+- **API 30개 규모**에 맞는 현실적 권장 (대규모 시스템용 가이드를 그대로 가져오지 말 것)
+- 일반론 회피 — 이 스택과 이 규모에서 실제로 부딪힐 이슈를 반영
+  (예: Kafka Consumer Group 신규 생성 시 메시지 중복/누락, Redis 키 네임스페이스 충돌, JPA Entity와 Domain Model 분리, 30개 API에 대한 적정 서비스 분할 수)
+- 결정이 필요한 항목은 단정하지 말고 **"체크해야 할 질문 목록"** 으로 남길 것
+- **과분할 경계** 주의: 30개 API를 10개 마이크로서비스로 쪼개는 것은 거의 항상 잘못된 선택. 보수적 분할을 권장하는 톤 유지

.codex/prompt/preparation_checklist.md

@@ -0,0 +1,113 @@
+# Role
+당신은 대규모 백엔드 시스템의 아키텍처 전환 경험이 풍부한 시니어 백엔드 아키텍트입니다.
+모놀리식 → MSA 전환, DDD 도입, 그리고 **새로운 레포지토리에서 그린필드(Greenfield)로 시작하는 레거시 마이그레이션** 프로젝트를 주도한 경험이 있다고 가정하고 응답해주세요.
+
+# Context
+저는 현재 운영 중인 백엔드 프로젝트를 **완전히 새로운 Git 레포지토리와 새로운 프로젝트**에서 처음부터 다시 구축하는 방식으로 전면 리팩터링하려고 합니다.
+
+## 현재 상태 (Legacy)
+- 아키텍처: DDD 기반이 아니며, 도메인 경계가 명확하지 않음
+- 배포 형태: 단일 프로젝트로 되어있고, 그대로 MSA로 쪼개기엔 결합도가 높음
+- 기술 스택: Java 21, Spring Boot 3.1.5, MySQL, Redis, Kafka
+- **기존 레포지토리는 그대로 운영을 유지**하면서, 신규 시스템으로 점진적 전환 예정
+
+## 목표 상태 (New)
+- **완전히 새로운 Git 레포지토리**에서 시작 (기존 코드는 참고/이관 대상이지 베이스가 아님)
+- **새로운 프로젝트 구조**로 처음부터 구축 (빈 캔버스에서 시작)
+- **도메인별 MSA**로 분리
+- **DDD(Domain-Driven Design)** 적용 (Bounded Context, Aggregate, Domain Event 등)
+- 리팩터링 과정에서 **여러 AI 에이전트를 활용**하여 단계별로 진행 예정
+
+## 그린필드 전환의 핵심 제약
+- 기존 레포는 운영 중 → 신규 시스템과 **일정 기간 병행 운영** 필요
+- 기존 코드는 "복사-붙여넣기 대상"이 아니라 **요구사항 추출의 원천(spec source)** 으로만 사용
+- DB, Kafka 토픽, Redis 등 인프라도 신규로 구성할지 / 기존 것을 일부 공유할지 결정 필요
+- 클라이언트(프론트, 모바일, 외부 시스템)에 대한 **하위 호환성** 유지 전략 필요
+
+# Task
+이 그린필드 전면 리팩터링을 시작하기 전에 **무엇을 어떤 순서로 준비해야 하는지** 상세한 준비 리스트(체크리스트)를 작성해주세요.
+
+단순 나열이 아니라, **"왜 필요한지"** 와 **"어떤 산출물이 나와야 하는지"** 를 함께 적어주세요.
+특히 **"기존 레포가 아닌 신규 레포에서 시작한다"** 는 점이 의사결정과 작업 항목에 어떻게 영향을 주는지를 반영해주세요.
+
+# 준비 리스트에 반드시 포함되어야 하는 영역
+
+1. **현행 시스템 분석 (As-Is 인벤토리 / Spec 추출)**
+    - 신규 레포에서는 코드를 가져오지 않으므로, 기존 시스템에서 **"무엇을 만들어야 하는지"를 추출**하는 작업이 핵심
+    - 예: 전체 API 리스트, 각 API의 비즈니스 로직/입출력/예외 케이스, 현재 DB 스키마 ERD, 외부 연동 시스템, Kafka 토픽/Consumer 매핑, Redis 키 사용 패턴, 배치/스케줄러, 숨겨진 비즈니스 룰
+
+2. **도메인 모델링 (DDD 관점)**
+    - 예: Event Storming, Bounded Context 도출, Context Map, Aggregate 후보 식별, Ubiquitous Language 정의
+
+3. **MSA 분리 전략**
+    - 예: 서비스 경계 정의 기준, 서비스 간 통신 방식(동기/비동기) 결정, 공유 데이터 처리 정책(Saga/Outbox 등), 인증/인가 분리 전략
+
+4. **신규 레포지토리 및 프로젝트 초기 설계** ⭐ (그린필드 핵심)
+    - 레포 전략: **모노레포 vs 멀티레포** 결정 기준 (서비스 수, 팀 구조, 배포 단위 고려)
+    - 디렉토리/모듈 구조 표준 (예: `domain` / `application` / `infrastructure` / `interfaces` 레이어 분리)
+    - 공통 모듈 전략: 공통 라이브러리(common-core, common-event 등)를 어떻게 관리할지
+    - 브랜치 전략, 커밋 컨벤션, PR 템플릿, 코드 오너십
+    - 코딩 컨벤션, 패키지 네이밍 규칙, Lint/Formatter 설정
+    - **샘플 서비스(reference service)** 를 1개 먼저 만들어 다른 서비스들의 템플릿으로 삼을지 여부
+
+5. **PRD(Product Requirements Document) 및 ADR 작성**
+    - 각 도메인별 PRD (As-Is 동작 + To-Be 개선 포함)
+    - 주요 아키텍처 결정에 대한 ADR (예: "왜 모노레포인가", "왜 Saga 대신 Outbox인가")
+
+6. **데이터 마이그레이션 및 인프라 분리 전략** ⭐ (그린필드 핵심)
+    - 신규 시스템의 DB/Redis/Kafka를 **별도로 구축할지, 기존 것을 일부 공유할지** 결정
+    - DB-per-service 전환 시 데이터 분리 방식
+    - 기존 → 신규로의 데이터 동기화 (CDC, Dual Write, Backfill 등)
+    - 무중단 마이그레이션 전략, 데이터 정합성 검증 방법, 롤백 시나리오
+
+7. **레거시-신규 병행 운영 전략 (Strangler Fig)** ⭐ (그린필드 핵심)
+    - 트래픽 라우팅 전략: API Gateway / BFF / 프록시를 통한 점진적 이관
+    - 기능 단위 컷오버 순서 (어떤 도메인부터 신규로 옮길지)
+    - 기존 클라이언트 하위 호환성 유지 (URL, 응답 스키마, 인증 토큰 등)
+    - 이중 쓰기(dual write) 또는 이벤트 기반 동기화 구간 처리
+    - 레거시 폐기(decommission) 시점과 기준
+
+8. **인프라 및 배포 준비**
+    - CI/CD 파이프라인 신규 구축 (신규 레포 기준)
+    - 컨테이너/오케스트레이션, 환경 분리(dev/stg/prod)
+    - 관측성(로깅/메트릭/트레이싱) 표준 — 신규 시스템은 처음부터 OpenTelemetry 등 도입 검토
+    - 시크릿 관리, 환경 변수 관리
+
+9. **테스트 및 검증 전략**
+    - Contract Test (서비스 간 / 레거시-신규 간)
+    - E2E 시나리오 정의
+    - **레거시 vs 신규 동작 비교 검증** (섀도우 트래픽, diff testing)
+
+10. **AI 에이전트 활용 계획**
+    - 단계별 에이전트 투입: 레거시 코드 분석 / Spec 추출 / 신규 코드 생성 / 테스트 작성 / 문서화
+    - 에이전트가 신규 레포에서 일관된 코드를 생성하도록 사전 준비할 자산:
+        - 도메인 사전(Ubiquitous Language)
+        - 코딩 컨벤션 / 아키텍처 가이드 문서
+        - 레퍼런스 서비스 코드
+        - 프롬프트 템플릿 (도메인별 코드 생성용)
+    - 레거시 레포 읽기 권한과 신규 레포 쓰기 권한을 분리해서 운영하는 방법
+
+11. **리스크 및 마일스톤**
+    - 주요 리스크와 대응 방안 (예: 숨겨진 비즈니스 룰 누락, 병행 운영 중 데이터 불일치)
+    - 단계별 마일스톤과 산출물
+
+# Output Format
+아래 형식으로 작성해주세요.
+
+## [영역 번호]. [영역 이름]
+- **목적**: 이 단계가 왜 필요한가 (특히 그린필드 맥락에서)
+- **세부 작업 항목**: 체크리스트 형태 (`- [ ]` 사용)
+- **산출물(Deliverables)**: 이 단계 종료 시 나와야 하는 문서/파일
+- **권장 도구 또는 에이전트 활용 포인트**
+- **예상 소요 및 우선순위**: High / Medium / Low
+
+마지막에 다음 두 가지를 추가해주세요:
+1. **전체 진행 순서 (Phase별 로드맵)** — Phase 0(준비) ~ Phase N(레거시 폐기)까지
+2. **신규 레포 초기 디렉토리 구조 예시** — Java 21 / Spring Boot 3.1.5 / DDD / MSA 기준의 폴더 트리
+
+# Constraints
+- Java 21 / Spring Boot 3.1.5 / MySQL / Redis / Kafka 기술 스택을 전제로 구체적인 예시를 들어주세요.
+- 일반론이 아니라 **이 스택에서 그린필드로 시작할 때 실제로 부딪히는 이슈**를 반영해주세요.
+  (예: Kafka Consumer Group을 신규로 만들 때 메시지 중복 처리, Redis 캐시 키 네임스페이스 분리, JPA Entity와 Domain Model 분리, Spring Modulith 검토 여부 등)
+- 결정이 필요한 항목은 단정하지 말고 **"체크해야 할 질문 목록"** 으로 남겨주세요.
+  (예: "기존 Kafka 클러스터를 재사용할 것인가, 신규 클러스터를 구축할 것인가?")

.github/gemini-instructions.md

@@ -0,0 +1,37 @@
+# Gemini Code Review Instructions
+
+## General Principles
+- Focus on backend API quality, not frontend UI
+- Prioritize correctness over style
+- Identify potential production issues
+
+## Architecture Rules
+- Controller must not contain business logic
+- Use service/facade layer for orchestration
+- Repository should only handle DB access
+
+## Critical Review Points
+- Race conditions and concurrency issues
+- Transaction boundaries (@Transactional)
+- N+1 query problems
+- API idempotency
+- Error handling and exception clarity
+
+## Performance
+- Avoid unnecessary DB queries
+- Suggest caching if applicable (Redis, etc.)
+- Check pagination strategy (offset vs cursor)
+
+## Code Quality
+- Avoid large methods (>50 lines)
+- Ensure clear naming
+- Remove dead code
+
+## Testing
+- If no tests exist → 반드시 지적
+- Suggest unit test cases
+
+## Output Style
+- Be concise but actionable
+- Provide code examples when suggesting improvements
+