요구사항 분석 → 시스템 설계 → 구현 → 통합/테스팅 → 운영/유지보수

요구사항 분석 ────────────── 인수 테스트
  시스템 설계 ──────────── 시스템 테스트
    아키텍처 설계 ──────── 통합 테스트
      상세 설계 ────────── 단위 테스트
            구현 (코딩)

Backlog | Ready | In Progress (WIP: 3) | Review | Done
--------|-------|----------------------|--------|------
Task 5  |Task 4 |  Task 3              |Task 2  |Task 1
Task 6  |       |  Task 7              |        |
        |       |  Task 8              |        |

As a [role], I want [feature], so that [benefit].

다음 비즈니스 요구사항에서 User Story를 작성해줘:
"온라인 쇼핑몰에서 고객이 구매 이력을 기반으로 추천 상품을 받고 싶어한다"

다음 형식으로 작성해:
- User Story (As/I want/So that)
- Acceptance Criteria (Given/When/Then)
- Story Points 추정
- 잠재적 엣지 케이스 5개

User Story: 맞춤형 상품 추천
As a 반복 구매 고객,
I want 내 구매 이력을 기반한 상품 추천을 홈 화면에서 보고 싶다,
So that 관심 있는 상품을 빠르게 발견할 수 있다.

Acceptance Criteria:
- Given 3회 이상 구매한 고객이
- When 홈 화면에 접속하면
- Then 구매 이력 기반 상위 10개 추천 상품이 표시된다
- And 각 추천에는 "왜 추천되었는지" 이유가 표시된다
- And 관심 없음 버튼으로 해당 추천을 숨길 수 있다

1단계: 도메인 이벤트 식별 (오렌지 포스트잇)
→ Claude에게 "이커머스 주문 도메인에서 발생하는 모든 도메인 이벤트를 나열해줘"

2단계: 커맨드 식별 (파란 포스트잇)
→ "각 이벤트를 발생시키는 커맨드는 무엇인가?"

3단계: 액터 식별 (노란 포스트잇)
→ "각 커맨드를 실행하는 액터(사용자/시스템)는?"

4단계: 집합체(Aggregate) 식별 (노란 큰 포스트잇)
→ "관련 이벤트와 커맨드를 묶는 집합체는?"

5단계: 경계 컨텍스트(Bounded Context) 정의
→ "집합체들을 논리적 경계로 그룹화"

이커머스 플랫폼의 주문 처리 도메인에 대한 Event Storming을 진행해줘.
다음 형식으로 출력해:

도메인 이벤트 (과거형):
- OrderPlaced (주문됨)
- PaymentProcessed (결제처리됨)
...

각 이벤트에 대해:
1. 트리거 커맨드
2. 선행 조건
3. 후행 결과
4. 관련 집합체

# 프로젝트 컨텍스트

## 프로젝트 개요

이커머스 플랫폼 백엔드 서비스 (Node.js + TypeScript)

## 기술 스택

- Runtime: Node.js 20, TypeScript 5.3
- Framework: NestJS 10
- Database: PostgreSQL 16 (TypeORM), Redis 7
- Message Queue: RabbitMQ
- Testing: Jest, Supertest

## 아키텍처 결정

- DDD (Domain-Driven Design) 적용
- CQRS 패턴 사용
- 이벤트 소싱 적용 (주문 집합체)

## 코딩 컨벤션

- 함수형 프로그래밍 선호
- 불변 데이터 구조 사용
- 에러 처리: Result 타입 패턴 (neverthrow 라이브러리)

## 금지 사항

- any 타입 사용 금지
- console.log 대신 winston logger 사용
- 직접 DB 쿼리 금지 (Repository 패턴 사용)

## 테스트 요구사항

- 단위 테스트 커버리지 90% 이상
- 모든 public API에 통합 테스트 필수
- E2E 테스트: 핵심 결제 플로우

## 현재 작업 컨텍스트

Sprint 3: 추천 시스템 구현

- User Story: US-123 구매 이력 기반 추천
- 기술 부채: 레거시 ProductService 리팩토링 필요

# ADR-001: 데이터베이스 선택

## 상태

승인됨 (2026-03-17)

## 컨텍스트

추천 시스템을 위한 데이터베이스가 필요함.
요구사항:

- 초당 10,000 읽기 요청 처리
- 상품 간 관계 그래프 쿼리
- 실시간 업데이트

## 결정

PostgreSQL + pgvector 확장을 선택

## 대안들

1. MongoDB: 유연한 스키마이나 복잡한 관계 쿼리 약함
2. Neo4j: 그래프 DB이나 팀 경험 부족, 운영 복잡성
3. Redis + PostgreSQL: 캐싱 레이어 추가로 성능 보완

## 결과

- 긍정: pgvector로 벡터 유사도 검색 가능
- 긍정: 팀의 PostgreSQL 경험 활용
- 부정: 초대형 그래프 쿼리 시 성능 한계
- 부정: pgvector 설정 및 인덱싱 학습 필요

우리 시스템의 메시지 큐 선택에 대한 ADR을 작성해줘.
요구사항:
- 초당 50,000 메시지 처리
- At-least-once 전달 보장
- 메시지 재처리 기능
- 팀 규모: 5명

후보: Kafka, RabbitMQ, AWS SQS
각 대안의 장단점과 우리 상황에 맞는 최적 선택을 추천해줘.

다음 클래스 다이어그램을 리뷰해줘:
[다이어그램 붙여넣기]

확인 사항:

1. SOLID 원칙 위반 여부
2. 순환 의존성
3. 인터페이스 분리 기회
4. DDD 관점에서 집합체 경계 적절성
5. 개선 제안

1. 요구사항을 Claude에게 설명
2. Claude가 실패하는 테스트 코드 생성
3. 개발자가 테스트 검증 및 수정
4. Claude가 테스트를 통과하는 최소 구현 생성
5. 개발자와 Claude가 함께 리팩토링

// 1단계: Claude가 생성한 실패 테스트
describe('RecommendationService', () => {
  describe('getPersonalizedRecommendations', () => {
    it('should return top 10 recommendations based on purchase history', async () => {
      // Arrange
      const userId = 'user-123'
      const purchaseHistory = [
        { productId: 'prod-1', category: 'Electronics', purchasedAt: new Date() },
        { productId: 'prod-2', category: 'Electronics', purchasedAt: new Date() },
      ]
      mockPurchaseRepository.findByUserId.mockResolvedValue(purchaseHistory)
      mockProductRepository.findSimilar.mockResolvedValue(generateMockProducts(15))

      // Act
      const result = await service.getPersonalizedRecommendations(userId)

      // Assert
      expect(result).toHaveLength(10)
      expect(result[0]).toMatchObject({
        productId: expect.any(String),
        score: expect.any(Number),
        reason: expect.any(String),
      })
      expect(mockPurchaseRepository.findByUserId).toHaveBeenCalledWith(userId)
    })

    it('should return popular products when no purchase history exists', async () => {
      mockPurchaseRepository.findByUserId.mockResolvedValue([])
      mockProductRepository.findPopular.mockResolvedValue(generateMockProducts(10))

      const result = await service.getPersonalizedRecommendations('new-user')

      expect(result).toHaveLength(10)
      expect(mockProductRepository.findPopular).toHaveBeenCalled()
    })

    it('should exclude already purchased products from recommendations', async () => {
      const purchasedProductId = 'prod-already-bought'
      mockPurchaseRepository.findByUserId.mockResolvedValue([
        { productId: purchasedProductId, category: 'Books' },
      ])
      const recommendations = generateMockProducts(12)
      recommendations[0].productId = purchasedProductId
      mockProductRepository.findSimilar.mockResolvedValue(recommendations)

      const result = await service.getPersonalizedRecommendations('user-123')

      expect(result.map((r) => r.productId)).not.toContain(purchasedProductId)
    })
  })
})

다음 PR을 리뷰해줘:
[코드 붙여넣기]

리뷰 기준:

1. 버그 및 엣지 케이스
2. 성능 이슈 (N+1 쿼리, 메모리 누수)
3. 보안 취약점 (SQL 인젝션, XSS, 인증/인가)
4. 코딩 컨벤션 (CLAUDE.md 기준)
5. 테스트 커버리지
6. 가독성 및 유지보수성

각 이슈에 대해:

- 심각도: Critical/Major/Minor
- 개선 코드 예시
- 이유 설명

다음 함수에 대한 포괄적인 테스트 케이스를 생성해줘:

function calculateShippingFee(weight: number, distance: number, isPremium: boolean): number

비즈니스 규칙:

- 무게 0~1kg: 기본 요금 3000원
- 무게 1~5kg: kg당 500원 추가
- 무게 5kg 초과: 전체 20% 추가
- 거리 100km 초과: 1000원 추가
- 프리미엄 회원: 10% 할인
- 무료 배송 조건: 프리미엄 + 10kg 미만

테스트 케이스 생성 시:

- 경계값 분석 적용
- 동등 분할 클래스 식별
- 음수, 0, 극단값 포함
- 복합 조건 테스트
- Jest 형식으로 작성

{
  "mutate": ["src/**/*.ts", "!src/**/*.spec.ts"],
  "testRunner": "jest",
  "reporters": ["html", "clear-text", "progress"],
  "thresholds": {
    "high": 80,
    "low": 60,
    "break": 50
  }
}

다음 뮤테이션 테스팅 결과를 분석하고 생존한 뮤턴트를 잡는 테스트를 추가해줘:

생존한 뮤턴트:
1. Line 45: `>` 를 `>=` 로 변경 → 테스트가 감지 못함
2. Line 72: `&&` 를 `||` 로 변경 → 테스트가 감지 못함

현재 테스트 코드:
[테스트 코드 붙여넣기]

import fc from 'fast-check'

describe('ShippingFee property-based tests', () => {
  it('premium members always pay less than or equal to regular members', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0.1, max: 100 }),
        fc.integer({ min: 1, max: 1000 }),
        (weight, distance) => {
          const regularFee = calculateShippingFee(weight, distance, false)
          const premiumFee = calculateShippingFee(weight, distance, true)
          return premiumFee <= regularFee
        }
      )
    )
  })

  it('shipping fee is always positive', () => {
    fc.assert(
      fc.property(
        fc.float({ min: 0, max: 1000 }),
        fc.integer({ min: 0, max: 10000 }),
        fc.boolean(),
        (weight, distance, isPremium) => {
          return calculateShippingFee(weight, distance, isPremium) >= 0
        }
      )
    )
  })
})

# 프로젝트명 - Claude 컨텍스트 파일

## 프로젝트 개요

- 목적: [한 문장 설명]
- 단계: [MVP/Beta/Production]
- 팀 규모: [n명]
- 주요 도메인: [이커머스/핀테크/헬스케어 등]

## 기술 스택

### Backend

- Language: TypeScript 5.3 (strict mode)
- Runtime: Node.js 20 LTS
- Framework: NestJS 10
- ORM: TypeORM 0.3
- Database: PostgreSQL 16

### Frontend

- Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS 3.4
- State: Zustand 4

### Infrastructure

- Container: Docker + Kubernetes
- CI/CD: GitHub Actions
- Cloud: AWS (EKS, RDS, ElastiCache)

## 아키텍처

- 패턴: DDD + CQRS + Event Sourcing
- 서비스 분리: 모놀리식 (모듈러 모놀리스)
- API: REST + WebSocket (실시간 알림)

## 코딩 규칙

### 필수 준수

- TypeScript strict 모드: any 타입 절대 금지
- 함수 길이: 30줄 이하 유지
- 중첩 깊이: 3단계 이하
- 에러 처리: Result 패턴 (neverthrow)
- 로깅: winston logger (console.log 금지)

### 명명 규칙

- 클래스: PascalCase
- 함수/변수: camelCase
- 상수: UPPER_SNAKE_CASE
- 파일: kebab-case.ts
- 테스트 파일: \*.spec.ts

### 디렉토리 구조

## 테스트 전략
- 단위 테스트: 도메인 로직 (커버리지 90%)
- 통합 테스트: API 엔드포인트 (커버리지 80%)
- E2E: 핵심 비즈니스 플로우 3개
- 뮤테이션 테스트: 뮤턴트 생존율 20% 이하

## 현재 Sprint 컨텍스트
Sprint 3 (2026-03-10 ~ 2026-03-24)
목표: 추천 시스템 v1 출시

진행 중:
- US-123: 구매 이력 기반 추천 API (담당: 김개발)
- US-124: 실시간 추천 업데이트 WebSocket (담당: 이개발)

완료:
- US-121: 추천 알고리즘 기초 구현
- US-122: 추천 데이터 파이프라인

기술 부채:
- ProductService 레거시 코드 리팩토링 필요
- 테스트 없는 UserRepository 커버리지 향상 필요

## 금지 사항
- 직접 SQL 쿼리 (Repository 패턴 사용)
- 동기 파일 I/O (fs.readFileSync 등)
- 하드코딩된 시크릿 (환경 변수 사용)
- 무분별한 try-catch (에러 타입 명시)

# 1단계: 프로젝트 생성
npx create-next-app@latest my-shop --typescript --tailwind --app

# 2단계: CLAUDE.md 생성 (첫 번째 Claude 프롬프트)

Next.js 14 App Router 기반 이커머스 프로젝트를 시작합니다.
다음 요구사항으로 CLAUDE.md를 생성해줘:

- 상품 목록, 상세, 장바구니, 결제 기능
- TypeScript strict 모드
- Tailwind CSS + shadcn/ui
- Zustand 상태관리
- React Query v5 서버 상태관리
- Prisma + PostgreSQL
- NextAuth.js 인증
- Vitest + Testing Library 테스트

팀 컨벤션:
- 컴포넌트: shadcn/ui 기반 원자적 설계
- 서버 컴포넌트 기본, 클라이언트 컴포넌트 최소화
- 에러 바운더리 + Suspense 패턴

US-001: 장바구니에 상품 추가
As a 쇼핑객
I want 상품 상세 페이지에서 장바구니에 상품을 추가하고 싶다
So that 나중에 한번에 구매할 수 있다

Acceptance Criteria:
- Given 상품 상세 페이지에서
- When "장바구니 담기" 버튼을 클릭하면
- Then 선택한 옵션(사이즈, 색상)과 수량이 장바구니에 추가된다
- And 장바구니 아이콘에 수량이 업데이트된다
- And 이미 담긴 상품은 수량이 증가한다

위 User Story를 구현해줘.

기술 요구사항:
- Zustand store에 cartSlice 추가
- Server Action으로 장바구니 서버 동기화
- Optimistic Update 적용
- 재고 체크 (useQuery로 실시간)
- 에러 처리: 재고 부족, 네트워크 오류
- 애니메이션: 장바구니 아이콘 bounce

파일 구조:
- store/cartStore.ts
- components/product/AddToCartButton.tsx
- app/actions/cart.ts
- hooks/useCart.ts

위 구현에 대한 테스트를 작성해줘:
1. cartStore 단위 테스트 (Vitest)
2. AddToCartButton 컴포넌트 테스트 (Testing Library)
3. cart Server Action 통합 테스트
4. 속성 기반 테스트 (재고 제약 조건)