Imported from Sungw0o/HighFivebooks-V2 (AGENTS.md). Install upstream with npx skills add Sungw0o/HighFivebooks-V2. Copyright stays with the author.

HighFiveBooks V2 - Root Agent Harness

Claude Code, Codex, 기타 AI 에이전트는 작업 전에 이 파일을 먼저 읽는다. 이 저장소는 monorepo지만 monolith가 아니다. 서비스는 독립 실행/독립 배포되는 MSA로 유지한다. 프론트는 단순 데모가 아니라 기존 Thymeleaf front_server를 React로 대체하는 실제 사용자 쇼핑몰 프론트다.

0. 프로젝트 정의

HighFiveBooks V2는 기존 HighFiveBooks 팀 프로젝트를 개인 포트폴리오용으로 재정리하는 저장소다.

목표:

• MSA 유지
• order-server 중심 백엔드 리팩토링
• 기존 Spring Cloud 기반 MSA 구조와 단일 EC2 배포 기준 유지
• 기존 Thymeleaf 프론트를 React/Vite storefront로 대체

핵심 문장:

리팩토링 관리를 위해 monorepo로 통합했지만, 각 도메인 서버는 독립 실행/독립 배포 가능한 MSA로 유지한다.

1. 저장소 구조

HighFivebooks-V2/
  apps/
    storefront/           React/Vite 사용자 쇼핑몰 프론트

  services/
    order-server/         메인 리팩토링 대상
    book-server/          책 정보, 검색, 재고
    member-server/        회원, 등급, 포인트, 장바구니
    coupon-server/        쿠폰, 메시징/멱등성 참고
    payment-server/       결제 확인, 결제 성공 이벤트

  docs/                   계획서, 로드맵, 분석 문서

apps/storefront가 Claude의 주 작업 위치다.

2. 에이전트 역할

Claude Code

주 담당:

• apps/storefront React/Vite 프론트 구현
• 기존 Thymeleaf front_server의 사용자 플로우를 React로 대체
• 도서 탐색, 도서 상세, 장바구니, 주문서, 결제, 마이페이지 구현
• 백엔드 controller/dto/client를 읽고 API 계약 정리
• 필요한 API가 없거나 불명확하면 임의 구현하지 말고 계약 초안 작성

보조 가능:

• services/order-server controller/dto 흐름 분석
• order/book/member/coupon/payment API 연동 범위 정리
• 백엔드 수정 계획 작성

주의:

• Claude가 백엔드를 읽는 것은 허용한다.
• Claude가 백엔드를 수정할 수도 있지만, 큰 변경은 먼저 계획을 보고한다.
• 특히 트랜잭션, Feign, RabbitMQ, Scheduler, pom.xml, application.yml, workflow 변경은 사용자 확인 후 진행한다.

Codex

주 담당:

• services/order-server 리팩토링
• 테스트 베이스라인 유지
• Feign boundary test
• transaction boundary
• RabbitMQ DLQ/Retry
• scheduler lock
• Docker Compose와 단일 EC2 배포 구성
• 문서/Notion 진행 로그

3. 절대 원칙

1. MSA를 monolith로 합치지 않는다.
2. monorepo는 저장소 관리 방식일 뿐이고, 배포 단위는 여러 서비스다.
3. 기존 front_server는 직접 고치지 않는다. React apps/storefront로 대체한다.
4. storefront는 실제 사용자 쇼핑몰 프론트다.
5. 별도 운영 콘솔은 만들지 않는다. 필요한 관리자 기능은 실제 서비스 요구에 맞는 화면으로만 추가한다.
6. Eureka, Config Server, Gateway를 포함한 기존 Spring Cloud 계약을 변경할 때는 서비스 호환성을 먼저 확인한다.
7. Secret, API key, DB password, JWT secret을 코드에 직접 쓰지 않는다.
8. node_modules, dist, target, .env는 커밋하지 않는다.

4. Frontend Scope

작업 위치:

apps/storefront

기술:

• React
• TypeScript
• Vite

구현 목표:

Home
  - 추천/신간/베스트 도서

Book
  - 도서 목록
  - 검색
  - 카테고리
  - 도서 상세
  - 리뷰

Cart
  - 장바구니 조회
  - 수량 변경
  - 선택 삭제

Order
  - 주문서
  - 배송지
  - 포장
  - 쿠폰 적용
  - 포인트 사용
  - 최종 금액 계산

Payment
  - 결제 요청
  - 결제 성공/실패 처리
  - 주문 상태 확인

My Page
  - 회원 정보
  - 주소
  - 쿠폰
  - 포인트
  - 주문 내역
  - 주문 상세
  - 취소/반품

프론트 규칙:

• API base URL은 환경변수로 둔다.
• mock과 real API adapter를 분리한다.
• 실제 백엔드 endpoint를 확인하지 않고 임의 API를 확정하지 않는다.
• API가 없으면 필요한 endpoint/request/response를 문서화한다.
• any를 남발하지 않는다.
• marketing landing page를 만들지 않는다.
• 첫 화면은 실제 쇼핑몰 홈 또는 도서 탐색 화면이어야 한다.
• 기존 front_server 코드는 참고할 수 있지만 그대로 이식하지 않는다.

API 후보:

GET    /api/books
GET    /api/books/{bookId}
GET    /api/books/search
GET    /api/categories
GET    /api/cart
POST   /api/cart/items
PATCH  /api/cart/items/{itemId}
DELETE /api/cart/items/{itemId}
GET    /api/members/me
GET    /api/members/me/addresses
GET    /api/members/me/coupons
GET    /api/members/me/points
POST   /api/orders
GET    /api/orders/{orderId}
GET    /api/orders/recent
POST   /api/orders/{orderId}/cancel
POST   /api/payments/confirm

위 경로는 후보일 뿐이다. 구현 전 실제 controller를 확인한다.

5. Backend Scope

메인 작업 위치:

services/order-server

보조 분석 위치:

services/book-server
services/member-server
services/coupon-server
services/payment-server

우선순위:

1. 주문 흐름 지도와 테스트 분류
2. Feign 경계 테스트
3. 트랜잭션 경계 리팩토링
4. RabbitMQ DLQ/Retry
5. 멀티 인스턴스 스케줄러 방어
6. Feign timeout/CircuitBreaker
7. 통합 환경
8. 단일 EC2 배포 재현
9. storefront API 연동

검증:

cd services/order-server
.\mvnw.cmd test

기대 결과:

132 tests, 0 failures, 0 errors, 1 skipped

RabbitMqDlqIntegrationTest는 RUN_RABBITMQ_INTEGRATION=true와 실제 RabbitMQ가 있을 때 실행되므로 기본 로컬 테스트에서는 1건 skip이 정상이다.

금지:

• 테스트 없이 주문 흐름을 크게 갈아엎기
• 외부 Feign I/O를 DB 트랜잭션 안에 새로 추가하기
• 재고/쿠폰/포인트 API에 무작정 retry 걸기
• poison message를 무한 requeue 상태로 방치하기

6. Order Flow

주문 생성:

React Storefront
  -> order-server
    -> member-server: 회원 등급 조회
    -> member-server: 포인트 예약
    -> book-server: 책 정보 조회
    -> book-server: 재고 선점
    -> coupon-server: 쿠폰 할인 계산
    -> order DB 저장

결제 성공:

payment-server 또는 RabbitMQ
  -> order-server
    -> 주문 상태/금액 검증
    -> coupon-server: 쿠폰 사용 확정
    -> book-server: 재고 차감 확정
    -> member-server: 포인트 확정
    -> order 상태 변경

취소/보상:

order-server
  -> book-server: 재고 복구
  -> member-server: 포인트 예약 취소/환불
  -> coupon-server: 쿠폰 사용 취소
  -> payment-server: 결제 취소

7. Deployment Direction

최종 배포 단위:

Ubuntu EC2
Nginx reverse proxy
storefront container
gateway/config/eureka containers
order/book/member/coupon/payment containers
MySQL, Redis, RabbitMQ, Elasticsearch

배포 규칙:

• 기존 Eureka/Config Server/Gateway 계약 유지
• Nginx와 로드밸런서를 통한 진입점 분리
• order-server 다중 인스턴스 가능성 고려
• scheduler 중복 실행 방지 고려

8. Branch Examples

frontend/storefront
frontend/storefront-api-contract
refactor/order-flow-map
refactor/order-transaction-boundary
refactor/payment-message-dlq
refactor/scheduler-lock
infra/ec2-deployment
docs/portfolio-evidence

9. Validation

Frontend:

cd apps/storefront
npm run build

Backend:

cd services/order-server
.\mvnw.cmd test

10. Commit Message Rules

이 저장소의 커밋 메시지는 깃모지와 한글 설명을 사용한다.

형식:

<gitmoji> <type>: <한글 요약>

예시:

✨ feat: React 스토어프론트 초기 구조 추가
🐛 fix: 주문 서버 RabbitMQ 큐 선언 누락 수정
📝 docs: 런타임 환경 설정 문서 추가
♻️ refactor: 주문 Feign 클라이언트 URL 설정 정리
✅ test: 주문 서버 컨텍스트 테스트 Rabbit 의존성 제거
🔧 chore: 로컬 Docker Compose 설정 추가
🚀 deploy: EC2 배포 구성 추가

허용 type:

feat      기능 추가
fix       버그 수정
docs      문서 변경
refactor  동작 변경 없는 구조 개선
test      테스트 추가/수정
chore     빌드, 설정, 의존성, 기타 작업
style     포맷팅, CSS, UI 스타일 변경
perf      성능 개선
deploy    배포/인프라 변경

규칙:

1. 요약은 한글로 쓴다.
2. 마침표로 끝내지 않는다.
3. 한 커밋은 하나의 의도를 가진다.
4. Secret, .env, API key, DB password는 커밋하지 않는다.
5. 프론트 작업은 가능하면 ✨ feat, 💄 style, 🐛 fix, 📝 docs 중 하나를 사용한다.
6. 백엔드 리팩토링은 가능하면 ♻️ refactor, 🐛 fix, ✅ test, 🔧 chore 중 하나를 사용한다.
7. 커밋 전 가능한 검증 명령을 실행하고, 실패했다면 커밋 메시지 본문이나 완료 보고에 명시한다.

11. Claude Prompt Template

HighFiveBooks V2 프론트 작업을 맡아줘.
먼저 루트 AGENTS.md와 CLAUDE.md를 읽고 따라줘.

이 프로젝트는 monorepo지만 monolith가 아니라 MSA야.
주 작업 위치는 apps/storefront야.
기존 Thymeleaf front_server를 직접 고치지 말고, React/Vite로 실제 사용자 쇼핑몰 프론트를 새로 구현해줘.

목표는 실제 서비스 플로우야.
도서 탐색, 상세, 장바구니, 주문서, 쿠폰/포인트, 결제, 마이페이지까지 구현 범위를 잡아줘.

필요하면 services/order-server, book-server, member-server, coupon-server, payment-server를 읽어서 API 계약을 정리해도 돼.
하지만 백엔드 코드 수정, 의존성 추가, application.yml/pom.xml/workflow 수정, Secret/.env 수정, 배포 실행은 먼저 계획을 보고하고 확인받아줘.

작업 후 apps/storefront에서 npm run build를 통과시켜줘.