[volume-3] 도메인 구현 - 김진수

.claude/CLAUDE.md

@@ -0,0 +1,115 @@
+## 프로젝트 개요
+
+Spring Boot 기반 멀티모듈 Java 프로젝트. TDD 방식으로 개발하며, 테스트 가능한 구조를 목표로 한다.
+
+---
+
+## 기술 스택
+
+- **Java 21**, **Spring Boot 3.4.4**, **Gradle Kotlin DSL**
+- Spring Web, Spring Data JPA, Spring Data Redis, QueryDSL, Kafka, Spring Batch
+- Lombok, Jackson, SpringDoc OpenAPI
+- JUnit 5 + AssertJ + Mockito, Testcontainers (MySQL, Redis)
+
+---
+
+## 모듈 구조
+
+```
+apps/
+├── commerce-api          # REST API 서버
+├── commerce-streamer     # Kafka 스트리밍 처리
+└── commerce-batch        # 배치 작업
+
+modules/
+├── jpa                   # BaseEntity, QueryDSL/JPA/DataSource Config
+├── redis                 # Redis 설정 및 Repository
+└── kafka                 # Kafka 설정 및 Producer/Consumer
+
+supports/
+├── jackson               # JSON 직렬화 설정
+├── logging               # 로깅 설정
+└── monitoring            # 모니터링 설정
+```
+
+---
+
+## 아키텍처
+
+계층 우선 패키지: `interfaces → application → domain ← infrastructure`
+
+### 컨벤션
+
+- 코딩 컨벤션: `.claude/skills/project-convention/` 참조 (코드 작성 시 해당 스킬의 references/ 하위 문서를 반드시 Read 도구로 읽을 것)
+- 커밋 규칙: `.claude/skills/commit-convention/` 참조
+
+### 코드 스타일 핵심 (매 작업 시 준수)
+
+- 1회용 변수는 인라인 (2회 이상 참조 시에만 변수 추출)
+- 메서드 체이닝 줄바꿈: 8-space continuation indent
+- 닫는 괄호: 마지막 인자에 붙임 (별도 줄 금지)
+- 컨텍스트가 길어질수록 컨벤션 누락 가능성 증가 → 코드 작성 전 관련 컨벤션 문서를 반드시 다시 Read할 것
+- **기능 완료 후 커밋 전**: `.claude/agents/convention-review/AGENT.md`를 읽고 서브 에이전트(Sonnet) 리뷰를 실행할 것
+
+### 설계 문서
+
+기능 개발 시 해당 도메인의 설계 문서를 **먼저 읽고** 시작한다.
+
+| 문서 | 경로 | 용도 |
+|------|------|------|
+| 공통 원칙 | `docs/spec/shared/CONVENTIONS.md` | 참조 방식, Soft Delete, 용어집 등 |
+| 전체 구조 | `docs/spec/shared/OVERVIEW.md` | 전체 ERD + 클래스 다이어그램 |
+| 도메인 스펙 | `docs/spec/{domain}/DESIGN.md` | 요구사항 + 유즈케이스 + 시퀀스 + ERD + 클래스 |
+
+도메인: `brand`, `product`, `like`, `cart`, `order`
+
+**참조 규칙:**
+1. 해당 도메인의 `DESIGN.md`를 읽는다
+2. 다른 도메인과 연동이 필요하면 그 도메인의 `DESIGN.md`도 읽는다
+3. 전체 관계 확인이 필요하면 `OVERVIEW.md`를 읽는다
+4. 구현 완료 후 `DESIGN.md`의 **'예외 및 정책'** 섹션과 **유즈케이스 기능 흐름**을 재확인하여, 각 항목이 코드에 반영되었는지 대조한다
+
+---
+
+## TDD 개발 모드
+
+"TDD로 개발" 트리거 시 `.claude/skills/tdd/SKILL.md`를 읽고 시작한다. 아래 규칙은 **Round 진행 중 매 턴 적용**.
+
+### 핵심 규칙
+
+- Red 1개 → Green → Refactor → 다음 Red. **한 번에 여러 테스트 작성 금지**
+- Red를 반드시 실행하여 **실패를 확인**한 후 Green 진행
+- Green은 **통과할 최소 코드만**. 다음 시나리오까지 미리 구현 금지
+- 기능 수직 슬라이스: 기능 하나를 Domain → Application 관통 후 다음 기능
+- 매 Round 후 진행 문서(`docs/tdd/{domain}/{feature}.md`) 갱신
+
+### 계층별 전략
+
+| 계층 | 테스트 더블 | TDD 방식 |
+|------|-----------|---------|
+| Domain Entity/VO | 더블 불필요 | TFD |
+| Domain Service | **Fake 우선** | TFD |
+| Application Facade | Mockito mock() | TFD |
+| Controller / Repository | - | TLD (별도 진행) |
+
+### 테스트 실행
+
+- Round 중: `./gradlew :apps:commerce-api:test --tests "{패키지}.{클래스}"`
+- 전체 완료 후: `./gradlew :apps:commerce-api:test`
+
+### 코드 작성
+
+- 실제 동작하는 코드만. 불필요한 Mock 데이터 금지
+- null-safety (Optional 활용), `println` 금지
+- 기존 코드 패턴 분석 후 일관성 유지
+
+---
+
+## 프로젝트 실행
+
+```bash
+./gradlew :apps:commerce-api:bootRun    # 개발 환경
+./gradlew :apps:commerce-api:test       # 특정 모듈 테스트
+./gradlew test jacocoTestReport         # 커버리지
+docker compose up -d                    # 인프라
+```

.claude/agents/convention-review/AGENT.md

@@ -0,0 +1,127 @@
+# Convention Review Agent
+
+작업 완료 후 **서브 에이전트(Sonnet 4.6)**를 띄워 컨벤션 위반을 검출한다.
+
+## 왜 서브 에이전트인가
+
+메인 에이전트는 컨텍스트가 커질수록 스킬/컨벤션 문서의 attention이 약해져 위반을 놓친다.
+서브 에이전트는 **매번 새 컨텍스트**로 시작하므로 컨벤션 문서에 대한 attention이 100%에 가깝다.
+
+---
+
+## 실행 절차
+
+### Step 0: 사용자에게 알림
+
+서브 에이전트를 실행하기 전에 **반드시** 사용자에게 알린다:
+
+```
+🔍 컨벤션 리뷰 에이전트(Sonnet)를 실행합니다. (~47초 소요)
+   대상: {변경 파일 수}개 Java 파일
+   검증: {적용할 컨벤션 문서 목록}
+```
+
+### Step 1: 변경 파일 파악
+
+```bash
+git diff --name-only HEAD
+```
+
+커밋 전이면 `git diff --name-only`와 `git diff --cached --name-only`로 변경 파일을 파악한다.
+`.java` 파일만 필터링한다.
+
+### Step 2: 변경 파일의 계층 분류
+
+변경 파일을 계층별로 분류하고, 각 계층에 해당하는 컨벤션 문서를 결정한다.
+
+| 파일 경로 패턴 | 계층 | 필수 컨벤션 문서 |
+|--------------|------|----------------|
+| `interfaces/` | Interface | `inline-variable-convention.md` |
+| `application/` | Application | `inline-variable-convention.md`, `service-layer-convention.md` |
+| `domain/` | Domain | `inline-variable-convention.md`, `entity-vo-convention.md` |
+| `infrastructure/` | Infrastructure | `infrastructure-convention.md` |
+| `*Dto*.java`, `*Request*.java`, `*Response*.java`, `*Result*.java`, `*Criteria*.java`, `*Command*.java`, `*Info*.java` | DTO | `inline-variable-convention.md`, `dto-convention.md` |
+
+`inline-variable-convention.md`는 **모든 계층**에서 필수로 포함한다.
+
+### Step 3: 서브 에이전트 실행
+
+Task 도구로 서브 에이전트를 생성한다.
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "sonnet",
+  prompt: <아래 프롬프트 템플릿>
+)
+```
+
+### Step 4: 결과 보고
+
+서브 에이전트의 결과를 사용자에게 보여준다.
+
+- 위반 있음 → 파일:라인 — 위반 내용 — 수정 제안 형식으로 보고
+- 위반 없음 → "컨벤션 위반 없음" 보고
+- 오탐 가능성이 있는 항목은 별도 표시
+
+---
+
+## 서브 에이전트 프롬프트 템플릿
+
+```
+당신은 Java Spring 프로젝트의 코드 컨벤션 리뷰어입니다.
+
+## 절차
+
+1. 아래 컨벤션 문서를 Read로 읽으세요:
+   {계층별로 필요한 컨벤션 문서 절대경로 목록}
+
+2. 아래 코드 파일을 Read로 읽으세요:
+   {변경된 .java 파일 절대경로 목록}
+
+3. 컨벤션 문서의 규칙을 기준으로 코드를 검토하세요.
+
+## 검토 항목
+
+### 인라인 변수 (inline-variable-convention.md)
+- 1회 참조 변수가 인라인되지 않고 남아있는가
+- 2회 이상 참조 변수를 불필요하게 인라인하지 않았는가
+- 메서드 호출 인자의 줄바꿈이 8-space continuation indent를 따르는가
+- 닫는 괄호가 마지막 인자에 붙어 있는가 (별도 줄 X)
+- Align-to-parenthesis를 사용하지 않았는가
+
+### 계층별 규칙 (해당 계층의 컨벤션 문서)
+- 컨벤션 문서에 명시된 규칙 위반이 있는가
+
+## 검토 제외 (오탐 방지)
+
+- **메서드 선언부 파라미터**의 들여쓰기는 검토하지 마세요.
+  8-space continuation indent는 **메서드 호출 인자**, **변수 할당의 우변**,
+  **return 문의 값** 등에 적용됩니다.
+  메서드 선언부 `public void foo(` 뒤의 파라미터 들여쓰기는 이 규칙의 대상이 아닙니다.
+- **테스트 코드**는 프로덕션 코드와 다른 스타일을 허용합니다.
+  테스트의 가독성을 위한 변수 추출은 위반으로 보지 마세요.
+
+## 보고 형식
+
+위반이 있으면:
+```
+[위반] 파일명:라인번호 — 위반 규칙 — 설명
+  현재: (현재 코드)
+  수정: (수정 제안)
+```
+
+위반이 없으면:
+```
+컨벤션 위반 없음
+```
+```
+
+---
+
+## 주의사항
+
+- 리뷰 모델은 **Sonnet 4.6** 사용 (비용 ~$0.05/회, 속도 ~47초)
+- 컨벤션 문서는 **서브 에이전트가 직접 Read** — 메인 에이전트 컨텍스트에서 복사하지 않음
+- 변경 파일이 많으면 계층별로 서브 에이전트를 **병렬** 실행 가능
+- 오탐이 발견되면 이 문서의 "검토 제외" 섹션에 추가할 것