diff --git a/.codex/prompt/new_preparation_checklist.md b/.codex/prompt/new_preparation_checklist.md new file mode 100644 index 0000000..600b5cc --- /dev/null +++ b/.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개 마이크로서비스로 쪼개는 것은 거의 항상 잘못된 선택. 보수적 분할을 권장하는 톤 유지 \ No newline at end of file diff --git a/.codex/prompt/preparation_checklist.md b/.codex/prompt/preparation_checklist.md new file mode 100644 index 0000000..6630445 --- /dev/null +++ b/.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 클러스터를 재사용할 것인가, 신규 클러스터를 구축할 것인가?") \ No newline at end of file diff --git a/.github/gemini-instructions.md b/.github/gemini-instructions.md new file mode 100644 index 0000000..c4076e8 --- /dev/null +++ b/.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 +