기술 의사결정 기록 (ADR)
raw 설계·운영 문서에서 확인되는 주요 의사결정을 “결정 — 배경/근거” 형식으로 정리합니다.
ADR-001. 백엔드 런타임으로 Java 21 + Amazon Corretto 채택
결정 — Spring Boot 3.4를 Java 21, Amazon Corretto 배포판으로 운영.
배경/근거 — AWS에 배포하므로 AWS가 장기 업데이트를 지원하는 Corretto 배포판을 채택. Jenkins 실행용/프로젝트 빌드용 두 종류 JDK를 운영 서버에 구성.
ADR-002. 프론트엔드 스택 — Next.js 15 + Tailwind + shadcn/ui
결정 — Next.js 15(React 19) + Tailwind CSS + shadcn/ui, 상태관리는 Zustand(클라이언트) / TanStack Query(서버).
배경/근거 — SEO·오픈그래프·서버 컴포넌트가 필요해 React helmet 대신 Next 선택. CSS-in-JS는 Next 환경 부적합이라 제외하고 Tailwind 기반 headless UI인 shadcn/ui로 작업 효율을 높임. Zustand는 보일러플레이트 최소화, TanStack Query는 클라이언트/서버 상태 분리·캐시·선언적 에러 처리를 위해 채택.
ADR-003. 공통 응답에 Envelope 패턴 적용
결정 — 모든 API 응답을 BaseResponse/ErrorResponse Envelope로 감싸고, 에러 코드는 도메인별 enum(ErrorCodeSpec)으로 관리.
배경/근거 — 프론트엔드가 일관된 형식으로 응답·에러를 처리할 수 있게 함. HTTP 상태코드만으로 표현 못 하는 서비스 고유 에러를 errorCode로 식별. 단일 enum은 라인 수 폭증·머지 충돌을 유발하므로 도메인별로 분산.
ADR-004. 매칭 상태와 결과 테이블 분리, 동적 규칙 시스템 설계
결정 — MatchingRequest(현재 상태)와 MatchingRequestPartner(과거 결과 로그)를 분리하고, MatchingTemplate 기반 가중치 규칙 시스템을 설계.
배경/근거 — 재매칭 시나리오에서 ‘현재 상태’는 초기화되어도 ‘과거 기록’은 유지해 데이터 정합성·히스토리 추적을 확보. 단일 매칭 로직은 사용자 선호(“시간 우선”·“기술 우선”)를 반영 못 하므로, 규칙을 데이터화해 동적 적용하는 Rule-Based 시스템으로 개인화 확장 여지를 마련.
ADR-005. Docker 컨테이너 기반 배포로 전환
결정 — 운영 서버에서 직접 yarn build/pm2 실행하던 방식을 Docker 컨테이너 + docker-compose(멀티스테이지 빌드)로 전환.
배경/근거 — 인스턴스 안정성·장애 격리 향상. .env를 빌드/런타임 모두에 반영. 향후 이미지 레지스트리에 push 후 운영 서버는 docker pull만 하도록 개선해 배포 속도·버전 태그 롤백 관리를 강화할 계획.
ADR-006. Monorepo 통합
결정 — study-platform-client(FE)와 study-platform-mvp(BE)를 study-platform-mono로 통합하고, 루트에 공통 문서(product-ssot)·규칙·CI 레이어를 추가.
배경/근거 — 문서·규칙·CI를 한곳에서 관리하고 AI 에이전트 하네스(Claude Code/Codex)를 SSOT 하나 + 포인터/자동 동기화로 운영해 규칙 drift를 차단. 내부 구조는 보존, 브랜치는 main/develop로 단순화. DB는 기존 그대로 연결(변경 없음).
ADR-007. CI/CD를 Jenkins에서 GitHub Actions로 이관
결정 — Jenkins 파이프라인을 GitHub Actions로 재작성, 반복 부분은 composite action으로 추출, 환경변수는 ENVS_QA/ENVS_PROD 단일 secret으로 통일.
배경/근거 — monorepo 통합에 맞춰 CI를 일원화. zeroone 서버(WSL2)에 docker-compose 러너 6개(CI 4 + 배포 2)를 persistent로 구성. QA 실배포는 운영 컨테이너를 건드리지 않고 임시 포트·격리 DB 카나리로 검증.
ADR-008. release intent 라벨 기반 버전 관리 + 릴리스 기록 일원화
결정 — 운영 버전을 배포 환경변수가 아닌 PR의 release:patch|minor|major 라벨에서 계산하고, 최종 운영 조합을 releases/prod-*.yaml에 기록. hotfix 라벨 폐지.
배경/근거 — 운영 제품은 단일 컴포넌트가 아닌 Frontend+Backend+DB 조합으로 동작하므로, 장애 시 “지금 운영 조합과 롤백 대상”을 한 기록으로 알 수 있어야 함. 롤백은 pointer 태그가 아닌 고정 이미지 태그 기준. (monorepo 통합 직후 기록 위치 이원화·문서 갱신·라벨 규칙 재정의가 후속 과제로 남음.)
ADR-009. BDD 테스트 + 요구사항 추적성 검사 도입
결정 — 백엔드에 Cucumber(인수) + Karate(API) + Testcontainers(격리 DB)를 도입하고, requirements.yaml의 요구사항이 실제 .feature와 연결됐는지 strict 검사(verifyAuthTraceability).
배경/근거 — “문서에만 있고 테스트 없는” 요구사항을 막기 위해 대응 시나리오가 없으면 CI를 FAIL시켜 product-ssot↔테스트 추적성을 강제.
원문: