[3팀 김대현] Chapter3-2. 디자인 패턴과 함수형 프로그래밍 그리고 상태 관리 설계

.claude/agents/code-writer.md

@@ -0,0 +1,30 @@
+---
+name: code-writer
+description: 코드 구현을 담당합니다. 새로운 기능 개발, 파일 생성, 코드 수정이 필요할 때 호출됩니다.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+당신은 코드 작성 전문가입니다.
+
+## 역할
+
+- 기능 요구사항에 따른 코드 구현
+- 타입 안전성 확보 (TypeScript)
+- 에러 핸들링 포함
+
+## 작업 전 확인
+
+1. 요구사항 명확히 이해
+2. 기존 코드 스타일 파악
+3. 관련 파일 구조 확인
+
+## 코드 작성 원칙
+
+- 기존 패턴 따르기
+- 주석은 필요한 곳에만
+- 작은 단위로 커밋 가능하게
+
+## 완료 후
+
+- 작성한 파일 목록 보고
+- 테스트 필요 여부 안내

.claude/agents/orchestrator.md

@@ -0,0 +1,30 @@
+---
+name: orchestrator
+description: 프로젝트 전체 진행을 조율하고 적절한 에이전트에게 태스크를 위임합니다. 복잡한 기능 구현이나 여러 단계가 필요한 작업 시 호출됩니다.
+tools: Read, Write, Glob, Grep
+---
+
+당신은 프로젝트 오케스트레이터입니다.
+
+## 역할
+
+- 프로젝트 목표와 현재 상태 파악
+- 적절한 서브에이전트에게 태스크 위임
+- 진행 상황 추적 및 로그 관리
+
+## 작업 시작 전 필수
+
+1. `.claude/state/goals.md` 읽어 현재 목표 확인
+2. `.claude/state/progress.json` 읽어 현재 페이즈 확인
+3. 이전 로그 확인 (`.claude/state/logs/`)
+
+## 작업 완료 시 필수
+
+1. `.claude/state/logs/phase-[n].md` 작성
+2. `.claude/state/progress.json` 업데이트
+3. 다음 단계 안내
+
+## 금지사항
+
+- 직접 코드 작성 금지 (code-writer에게 위임)
+- 로그 없이 페이즈 종료 금지

.claude/agents/reviewer.md

@@ -0,0 +1,34 @@
+---
+name: reviewer
+description: 코드 리뷰를 담당합니다. PR 리뷰, 코드 품질 검토, 리팩토링 제안이 필요할 때 호출됩니다.
+tools: Read, Grep, Glob
+---
+
+당신은 시니어 코드 리뷰어입니다.
+
+## 역할
+
+- 코드 품질 검토
+- 잠재적 버그 발견
+- 개선 제안
+
+## 리뷰 체크리스트
+
+- [ ] 타입 안전성
+- [ ] 에러 핸들링
+- [ ] 성능 이슈
+- [ ] 보안 취약점
+- [ ] 코드 스타일 일관성
+
+## 리뷰 형식
+
+각 이슈에 대해:
+
+- 위치 (파일:라인)
+- 심각도 (critical/major/minor/suggestion)
+- 설명
+- 개선 제안
+
+## 금지사항
+
+- 직접 코드 수정 금지 (리뷰만)

.claude/agents/test-writer.md

@@ -0,0 +1,29 @@
+---
+name: test-writer
+description: 테스트 코드 작성을 담당합니다. TDD 방식 개발이나 테스트 추가가 필요할 때 호출됩니다.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+당신은 테스트 작성 전문가입니다.
+
+## 역할
+
+- 단위 테스트 작성
+- 통합 테스트 작성
+- 엣지 케이스 커버
+
+## 테스트 원칙
+
+- 각 함수당 최소 3개 테스트
+- 정상 케이스 + 엣지 케이스 + 에러 케이스
+- 테스트 이름은 명확하게
+
+## 사용 프레임워크
+
+- Vitest (프로젝트 기본)
+- React Testing Library (React 컴포넌트)
+
+## 완료 후
+
+- 테스트 실행 결과 보고
+- 커버리지 안내

.claude/commands/phase-complete.md

@@ -0,0 +1,32 @@
+---
+description: 현재 페이즈를 완료하고 로그를 작성합니다
+---
+
+현재 페이즈를 완료 처리합니다.
+
+## 필수 수행 작업
+
+1. **로그 작성**
+   `.claude/state/logs/phase-[현재번호].md` 생성:
+
+   - 완료된 작업 목록
+   - 생성/수정된 파일
+   - 발생한 이슈와 해결
+   - 다음 단계
+
+2. **progress.json 업데이트**
+
+   - 현재 페이즈 status: "completed"
+   - currentPhase 증가
+   - lastUpdated 갱신
+
+3. **완료 메시지 출력**
+
+```
+✅ Phase [N] 완료
+📝 로그: .claude/state/logs/phase-[n].md
+📊 진행률: [X/Y] 페이즈 완료
+➡️ 다음: Phase [N+1] - [이름]
+```
+
+$ARGUMENTS

.claude/commands/setup.md

@@ -0,0 +1,43 @@
+---
+description: 프로젝트 초기 세팅을 시작합니다
+---
+
+SETTING.md 파일을 읽고 프로젝트 초기화를 진행합니다.
+
+## 수행할 작업
+
+1. **폴더 구조 생성**
+
+   - `.claude/agents/` 생성
+   - `.claude/commands/` 생성
+   - `.claude/state/` 생성
+   - `.claude/state/logs/` 생성
+
+2. **기본 에이전트 생성** (SETTING.md의 템플릿 참조)
+
+   - orchestrator.md
+   - code-writer.md
+   - test-writer.md (선택)
+   - reviewer.md (선택)
+
+3. **상태 파일 초기화**
+
+   - goals.md
+   - references.md
+   - progress.json
+
+4. **정보 수집**
+   사용자에게 다음을 질문:
+
+   - 프로젝트 목표
+   - 세부 태스크
+   - 참고 자료
+   - 기술 스택
+   - 필요한 에이전트
+
+5. **CLAUDE.md 업데이트**
+
+6. **초기화 로그 작성**
+   - `.claude/state/logs/phase-0.md`
+
+$ARGUMENTS

.claude/commands/status.md

@@ -0,0 +1,36 @@
+---
+description: 현재 프로젝트 진행 상황을 확인합니다
+---
+
+프로젝트의 현재 상태를 확인합니다.
+
+## 확인 항목
+
+1. **현재 페이즈**
+   - `.claude/state/progress.json` 읽기
+   - 현재 페이즈와 상태 출력
+
+2. **목표 확인**
+   - `.claude/state/goals.md` 읽기
+   - 남은 태스크 목록 출력
+
+3. **최근 로그**
+   - `.claude/state/logs/` 폴더의 최신 로그 확인
+
+## 출력 형식
+
+```
+📊 프로젝트 현황
+
+Phase: [현재 페이즈] / [전체 페이즈]
+상태: [in-progress / completed]
+
+📋 남은 태스크:
+- [ ] 태스크 1
+- [ ] 태스크 2
+
+📝 최근 활동:
+- ...
+```
+
+$ARGUMENTS

.claude/state/goals.md

@@ -0,0 +1,44 @@
+# 🎯 프로젝트 목표
+
+## 최종 목표
+React 쇼핑몰 앱의 비즈니스 로직을 분리하고 계층 구조를 이해하는 리팩토링
+
+## Phase 1: 기본과제 (basic)
+상태관리 없이 hook/function 분리
+
+### 세부 태스크
+
+#### 1) 계산 함수 분리 (순수함수)
+- [ ] `calculateItemTotal` - 아이템 총액 계산
+- [ ] `getMaxApplicableDiscount` - 최대 적용 가능 할인율
+- [ ] `calculateCartTotal` - 장바구니 총액 계산
+- [ ] `updateCartItemQuantity` - 장바구니 수량 업데이트
+
+#### 2) 커스텀 훅 분리
+- [ ] `useCart` - 장바구니 상태 관리
+- [ ] `useCoupons` - 쿠폰 상태 관리
+- [ ] `useProducts` - 상품 상태 관리
+- [ ] `useLocalStorage` - 로컬 스토리지 유틸리티
+
+#### 3) 컴포넌트 계층 구조
+- [ ] 엔티티 컴포넌트와 UI 컴포넌트 분리
+- [ ] ProductCard, Cart 등 컴포넌트 분리
+
+#### 4) 테스트 통과
+- [ ] `pnpm test:basic` 통과
+
+## Phase 2: 심화과제 (advanced)
+Context 또는 Jotai로 Props drilling 제거
+
+### 세부 태스크
+- [ ] 전역 상태관리 구축 (Context/Jotai/Zustand 중 선택)
+- [ ] 도메인 커스텀 훅 리팩토링
+- [ ] 불필요한 props 제거
+- [ ] `pnpm test:advanced` 통과
+
+## 성공 기준
+- [ ] 모든 테스트 통과 (`pnpm test`)
+- [ ] Component에서 비즈니스 로직 분리 완료
+- [ ] 계산함수는 순수함수로 작성
+- [ ] 특정 Entity만 다루는 함수/컴포넌트 분리
+- [ ] 데이터 흐름에 맞는 계층구조

.claude/state/progress.json

@@ -0,0 +1,58 @@
+{
+  "project": "React 쇼핑몰 리팩토링",
+  "startedAt": "2025-12-02T00:00:00Z",
+  "currentPhase": 2,
+  "phases": [
+    {
+      "id": 0,
+      "name": "초기화",
+      "status": "completed",
+      "completedAt": "2025-12-02T00:00:00Z"
+    },
+    {
+      "id": 1,
+      "name": "기본과제 (basic)",
+      "status": "completed",
+      "startedAt": "2025-12-02T00:00:00Z",
+      "completedAt": "2025-12-05T00:15:00Z",
+      "tasks": {
+        "total": 11,
+        "completed": 11,
+        "details": [
+          { "name": "폴더 구조 scaffolding", "status": "completed" },
+          { "name": "storage.ts Pub/Sub 유틸리티", "status": "completed" },
+          { "name": "toast.ts Pub/Sub 시스템", "status": "completed" },
+          { "name": "useLocalStorage 훅 (빈 배열 자동 삭제)", "status": "completed" },
+          { "name": "useProducts 훅 (localStorage 통합)", "status": "completed" },
+          { "name": "useCoupons 훅 (localStorage 통합)", "status": "completed" },
+          { "name": "useCart 훅 (localStorage 통합)", "status": "completed" },
+          { "name": "cart.ts 순수 함수 완성", "status": "completed" },
+          { "name": "useDebounce 훅 개선", "status": "completed" },
+          { "name": "컴포넌트 계층 구조 분리", "status": "completed" },
+          { "name": "테스트 통과 (21/21)", "status": "completed" }
+        ]
+      }
+    },
+    {
+      "id": 2,
+      "name": "심화과제 (advanced)",
+      "status": "completed",
+      "startedAt": "2025-12-05T01:00:00Z",
+      "completedAt": "2025-12-05T02:00:00Z",
+      "tasks": {
+        "total": 7,
+        "completed": 7,
+        "details": [
+          { "name": "폴더 구조 scaffolding", "status": "completed" },
+          { "name": "Props drilling 분석 및 Jotai 전략 결정", "status": "completed" },
+          { "name": "uiAtoms.ts 구현 (isAdmin, searchTerm)", "status": "completed" },
+          { "name": "productAtoms.ts 구현 (CRUD actions)", "status": "completed" },
+          { "name": "couponAtoms.ts 구현 (add/delete)", "status": "completed" },
+          { "name": "cartAtoms.ts 구현 (cart, totals, actions)", "status": "completed" },
+          { "name": "테스트 통과 (21/21)", "status": "completed" }
+        ]
+      }
+    }
+  ],
+  "lastUpdated": "2025-12-05T02:00:00Z"
+}

.claude/state/references.md

@@ -0,0 +1,46 @@
+# 📚 참고 자료
+
+## 프로젝트 문서
+- `README.md` - 과제 요구사항 및 상세 설명
+- `.github/pull_request_template.md` - 체크리스트 및 회고 템플릿
+
+## 핵심 개념
+
+### 엔티티 vs 비엔티티 구분
+| 구분 | 엔티티 O | 엔티티 X |
+|------|---------|---------|
+| 상태 | cart, isCartFull | isShowPopup |
+| 컴포넌트/훅 | CartItemView, useCart() | Button, useRoute |
+| 함수 | calculateCartTotal(cart) | capitalize(str) |
+
+### 계층 구조
+```
+entities -> features -> UI
+```
+
+### 분리 기준
+- **순수함수**: 특정 엔티티만 다루는 계산 로직
+- **커스텀 훅**: 상태를 다루는 로직
+- **컴포넌트**: UI 렌더링
+
+## 체크리스트
+
+### 기본과제
+- [ ] Component에서 사용되는 Data가 아닌 로직들은 hook으로 옮겨졌나요?
+- [ ] 주어진 hook의 책임에 맞도록 코드가 분리가 되었나요?
+- [ ] 계산함수는 순수함수로 작성이 되었나요?
+- [ ] 특정 Entity만 다루는 함수는 분리되어 있나요?
+- [ ] 특정 Entity만 다루는 Component와 UI를 다루는 Component는 분리되어 있나요?
+- [ ] 데이터 흐름에 맞는 계층구조를 이루고 의존성이 맞게 작성이 되었나요?
+
+### 심화과제
+- [ ] Context나 Jotai를 사용해서 전역상태관리를 구축했나요?
+- [ ] 전역상태관리를 통해 domain custom hook을 적절하게 리팩토링 했나요?
+- [ ] 도메인 컴포넌트에 도메인 props는 남기고 props drilling을 유발하는 불필요한 props는 잘 제거했나요?
+- [ ] 전체적으로 분리와 재조립이 더 수월해진 결합도가 낮아진 코드가 되었나요?
+
+## 기술 스택
+- React 19
+- TypeScript 5.9
+- Vite 7
+- Vitest 3 + React Testing Library