Feat/#248 리팩토링

.claude/skills/create/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: create
+description: 스펙 문서를 읽고 지정한 경로에 코드를 생성한다. FSD 레이어 책임 범위, conventions, code-quality 4원칙을 준수하며 테스트까지 작성한다.
+arguments: [path, spec]
+---
+
+# create
+
+스펙 문서와 대상 경로를 바탕으로 코드를 생성하고, 테스트까지 작성한다.
+
+**참조 문서:**
+
+- @docs/architecture.md — FSD 레이어별 책임 범위 및 의존성 방향
+- @docs/conventions.md — 파일 네이밍 및 코드 컨벤션
+- @docs/code-quality.md — 코드 품질 기준 (가독성 / 예측 가능성 / 응집도 / 결합도)
+- @docs/testing-guide.md — 테스트 도구 선택 기준
+
+---
+
+## 실행 절차
+
+### 1단계 — 스펙 파악
+
+`$spec` 경로의 문서를 읽고 다음을 파악한다.
+
+- 구현해야 할 기능과 동작 조건
+- 필요한 props / 인터페이스 / 상태
+- 예외 처리 및 에러 케이스
+- 스펙에 명시되지 않은 부분은 architecture.md와 conventions.md를 기준으로 합리적으로 판단하고, 가정한 내용을 결과 보고에 명시한다.
+
+### 2단계 — FSD 레이어 판단
+
+`$path`에서 레이어를 확인하고 `docs/architecture.md` 기준으로 책임 범위를 파악한다.
+
+- 생성할 코드가 해당 레이어의 책임에 맞는가?
+- 의존성 방향이 올바른가? (상위 레이어 → 하위 레이어만 허용)
+- 이미 존재하는 인접 파일이 있으면 함께 읽어 패턴을 맞춘다.
+
+### 3단계 — 코드 생성
+
+`docs/conventions.md`의 네이밍 규칙과 `docs/code-quality.md`의 4원칙을 준수하며 코드를 작성한다.
+
+**가독성:**
+
+- 동시에 실행되지 않는 분기는 컴포넌트/함수로 분리한다.
+- 구현 세부사항은 적절히 추상화한다.
+- 복잡한 조건과 매직 넘버에는 이름을 붙인다.
+- 중첩 삼항 연산자 대신 if 문을 사용한다.
+- 비교 연산은 왼쪽에서 오른쪽으로 읽히도록 작성한다. (`minPrice <= price && price <= maxPrice`)
+
+**예측 가능성:**
+
+- 같은 유형의 함수는 반환 타입을 통일한다. (API 훅은 Query 객체, validation 함수는 `{ ok, reason }`)
+- 함수 이름·파라미터·반환값으로 예측할 수 없는 로직은 함수 밖으로 분리한다.
+- 기존 코드베이스의 이름과 충돌하지 않도록 명확한 이름을 사용한다.
+
+**응집도:**
+
+- 함께 수정될 파일은 같은 디렉터리에 둔다.
+- 매직 넘버는 상수로 선언해 변경 지점을 하나로 모은다.
+- 폼 검증은 필드 레벨/폼 레벨 중 스펙에 맞는 방식을 선택한다.
+
+**결합도:**
+
+- 하나의 함수/훅이 하나의 책임만 가지도록 설계한다.
+- Props Drilling이 발생하면 Composition 패턴으로 해소한다.
+- 공통 추출보다 중복 허용이 나은 경우를 판단한다. (페이지마다 동작이 달라질 가능성이 있으면 중복 허용)
+
+### 4단계 — 테스트 작성
+
+`docs/testing-guide.md`의 레이어별 기준에 따라 테스트를 작성한다.
+
+**테스트 작성 판단 기준:**
+
+- 버그가 생기면 치명적인가?
+- 이 코드가 바뀔 가능성이 높은가?
+- 로직이 복잡한가?
+
+→ 하나라도 해당되면 Jest + RTL 테스트를 작성한다.
+
+**레이어별 테스트 도구:**
+
+| 경로 패턴                             | Jest + RTL            | Storybook Chromatic | Storybook play() |
+| ------------------------------------- | --------------------- | ------------------- | ---------------- |
+| `shared/lib`, `shared/utils`          | 반드시                | —                   | —                |
+| `shared/hooks`, `shared/store`        | 반드시 (`renderHook`) | —                   | —                |
+| `shared/ui`                           | 내부 로직이 있을 때만 | 항상                | 검토             |
+| `entities/model`, `entities/api`      | 반드시                | —                   | —                |
+| `entities/ui`                         | 검토                  | 항상                | 항상             |
+| `entities/query`                      | **작성 금지**         | —                   | —                |
+| `features/ui`                         | 반드시                | 검토                | 검토             |
+| `features/mutation`, `features/hooks` | 반드시 (MSW 모킹)     | —                   | —                |
+| `widgets/`                            | 핵심 인터랙션만       | 검토                | 검토             |
+
+### 5단계 — 검증
+
+```bash
+# 타입 체크
+pnpm tsc --noEmit
+
+# lint
+pnpm lint {생성한 파일 경로}
+
+# 테스트 실행
+pnpm test -- {생성한 테스트 파일 경로}
+```
+
+실패하면 에러를 읽고 수정한다. 모든 항목이 통과할 때까지 반복한다.
+
+### 6단계 — 결과 보고
+
+- 생성한 파일 목록
+- 파일별 역할 요약
+- 스펙에 명시되지 않아 가정한 내용
+- 원칙 간 트레이드오프가 있었던 경우 판단 이유
+- Storybook / Chromatic이 추가로 필요하다 판단되면 언급

.claude/skills/document-feature/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: document-feature
+description: 지정한 기능의 코드를 추적해 docs/features/{name}.md 스펙 문서를 생성한다. 이 문서는 이후 변경 요청의 기준점으로 사용된다.
+arguments: [feature-name, entry-path]
+---
+
+# document-feature
+
+기능 코드를 추적해 스펙 문서를 생성한다.  
+생성된 문서는 **스펙을 먼저 수정 → Claude에게 구현 요청** 워크플로의 기준점이 된다.
+
+---
+
+## 실행 절차
+
+### 1단계 — 진입점 파악
+
+`$entry-path`에서 시작해 이 기능이 어디서 호출되는지 찾는다.
+
+- 버튼 컴포넌트, 메뉴 항목, 페이지 마운트 등 사용자 행동과 연결된 모든 진입점을 찾는다.
+- `grep`으로 기능 핵심 훅/컴포넌트 이름을 역추적해 누락된 진입점이 없는지 확인한다.
+
+### 2단계 — 데이터 흐름 추적
+
+진입점에서 시작해 다음 순서로 관련 파일을 모두 읽는다.
+
+1. **훅** (`features/{domain}/hooks/`) — 모달/페이지 open 로직, 사전 데이터 조회
+2. **폼 훅** (`features/{domain}/hooks/use*Form.ts`) — 폼 상태, 유효성 검사, submit 핸들러
+3. **mutation 훅** (`features/{domain}/mutation/`) — API 호출, 캐시 무효화, 토스트
+4. **UI** (`features/{domain}/ui/`) — 폼 레이아웃, 필드 구성, 서브 컴포넌트
+5. **entity API** (`entities/{domain}/api/`) — 실제 HTTP 호출 함수
+6. **entity 타입** (`entities/{domain}/types/`) — Request / Response 타입
+7. **mock 핸들러** (`features/{domain}/mock/` 또는 `shared/mock/`) — API 스펙 보조 확인
+
+파일을 읽으며 다음을 기록한다.
+
+- 폼 필드 목록과 각 필드의 타입·필수 여부·제약
+- 유효성 검사 규칙과 처리 방식
+- 모달/페이지에 사전 주입되는 데이터와 그 출처
+- API endpoint, request body, response 타입, 캐시 무효화 키
+- 개인/팀 목표처럼 조건에 따라 동작이 달라지는 분기
+
+### 3단계 — 문서 생성
+
+`docs/features/$feature-name.md`를 아래 구조로 작성한다.  
+해당 기능에 없는 섹션(예: 폼이 없는 경우 "폼 필드 스펙")은 생략한다.
+
+```markdown
+# {기능명}
+
+---
+
+## 진입점
+
+| 위치 | 파일 | 조건 |
+| ... | ... | ... |
+
+진입점이 공통으로 호출하는 함수/훅을 한 줄로 서술한다.
+
+---
+
+## 폼 필드 스펙 ← 폼이 있을 때만
+
+| 필드 | 타입 | 필수 | 제약 | 비고 |
+| ... | ... | ... | ... | ... |
+
+조건에 따라 동작이 달라지는 필드(예: 개인/팀 목표)는 별도 표로 설명한다.
+
+---
+
+## 유효성 검사 ← 검사 규칙이 있을 때만
+
+| 검사 | 시점 | 처리 |
+| ... | ... | ... |
+
+---
+
+## 데이터 흐름
+
+텍스트 다이어그램으로 진입점 → 훅 → mutation → API → 후처리 순서를 표현한다.
+각 노드에 실제 파일명과 핵심 동작을 함께 기재한다.
+
+---
+
+## API
+
+엔드포인트, request body 타입(코드 블록), response 타입, 캐시 무효화 키를 기재한다.
+
+---
+
+## 모달/페이지에 사전 주입되는 데이터 ← 데이터 주입이 있을 때만
+
+| prop | 출처 |
+| ... | ... |
+
+---
+
+## 관련 파일 위치
+
+src/ 트리 형태로 관련 파일 경로와 각 파일의 역할을 한 줄로 기재한다.
+```
+
+**작성 원칙:**
+
+- 표(table)로 표현할 수 있는 정보는 표로 쓴다.
+- 데이터 흐름은 텍스트 다이어그램(`│`, `▼`, `←`)으로 표현한다.
+- 코드 스니펫은 타입 정의처럼 변경 시 반드시 함께 수정해야 하는 것만 포함한다.
+- 파일 위치 섹션은 "어디를 건드려야 하는가"를 빠르게 파악할 수 있게 작성한다.
+- Claude가 이 문서만 읽고 구현 변경을 수행할 수 있을 만큼 구체적으로 쓴다.
+
+### 4단계 — 결과 보고
+
+- 생성한 파일 경로
+- 추적한 파일 목록
+- 문서에 포함하지 못한 불확실한 부분이 있으면 명시

.claude/skills/refactor/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: refactor
+description: 지정한 경로의 코드를 docs/code-quality.md의 4원칙(가독성·예측 가능성·응집도·결합도) 기준으로 분석하고 개선한다. FSD 레이어와 conventions도 함께 준수한다.
+arguments: [path]
+---
+
+# refactor
+
+대상 코드를 읽고, 품질 기준에 맞게 개선한 뒤 lint와 테스트로 검증한다.
+
+**참조 문서:**
+
+- @docs/code-quality.md — 리팩터링 판단 기준 (가독성 / 예측 가능성 / 응집도 / 결합도)
+- @docs/architecture.md — FSD 레이어별 책임 범위
+- @docs/conventions.md — 파일 네이밍 및 코드 컨벤션
+
+---
+
+## 실행 절차
+
+### 1단계 — 대상 파일 파악
+
+`$path` 경로 아래의 모든 소스 파일을 읽는다.  
+연관된 파일(import 대상, 같은 레이어의 인접 파일)도 함께 읽어 전체 맥락을 파악한다.
+
+### 2단계 — 문제 분석
+
+`docs/code-quality.md`의 4원칙 기준으로 개선이 필요한 부분을 파악한다.  
+각 문제에 대해 **어떤 원칙을 위반하는지**, **왜 문제인지**를 명시한다.
+
+**가독성 체크리스트:**
+
+- 동시에 실행되지 않는 코드가 한 함수/컴포넌트에 혼재하는가?
+- 구현 세부사항이 불필요하게 노출되어 있는가?
+- 로직 유형(query param, state 등)으로 함수를 묶고 있는가?
+- 복잡한 조건이나 매직 넘버에 이름이 없는가?
+- 중첩 삼항 연산자가 있는가?
+- 코드를 위에서 아래로 읽을 때 눈의 이동이 많은가?
+
+**예측 가능성 체크리스트:**
+
+- 같은 이름을 가진 함수/변수가 다른 동작을 하는가?
+- 유사한 함수의 반환 타입이 일치하지 않는가?
+- 함수 이름·파라미터·반환값으로 예측할 수 없는 숨겨진 로직이 있는가?
+
+**응집도 체크리스트:**
+
+- 함께 수정될 파일이 서로 다른 디렉터리에 흩어져 있는가?
+- 매직 넘버가 하드코딩되어 변경 지점이 여러 곳에 분산되어 있는가?
+- 폼의 검증 로직이 적절한 레벨(필드/폼)에서 관리되고 있는가?
+
+**결합도 체크리스트:**
+
+- 하나의 함수/훅이 지나치게 넓은 책임을 가지고 있는가?
+- 중복을 제거하기 위해 공통 훅/컴포넌트로 묶었지만 페이지마다 동작이 달라질 가능성이 있는가?
+- Props Drilling이 발생하고 있는가?
+
+**FSD/conventions 체크리스트:**
+
+- 레이어 간 의존성 방향이 올바른가? (상위 레이어 → 하위 레이어)
+- 파일명·함수명이 conventions.md를 준수하는가?
+
+### 3단계 — 리팩터링 계획 수립
+
+분석 결과를 바탕으로 수정할 항목을 우선순위와 함께 나열한다.
+
+> 원칙 간 트레이드오프가 있을 때는 현재 코드의 맥락을 고려해 판단하고, 이유를 명시한다.  
+> 예: "응집도를 높이면 가독성이 낮아지지만, 이 값은 반드시 함께 수정되어야 하므로 응집도를 우선한다."
+
+### 4단계 — 리팩터링 실행
+
+계획한 순서대로 코드를 수정한다.
+
+- 한 번에 하나의 원칙씩 수정하고, 각 수정이 다른 원칙을 침해하지 않는지 확인한다.
+- import 경로는 **반드시 현재 실제 경로**를 사용한다. (구 경로 사용 금지)
+- 수정 범위가 넓다면 파일별로 나누어 단계적으로 진행한다.
+
+### 5단계 — 검증
+
+```bash
+# 타입 체크
+pnpm tsc --noEmit
+
+# lint
+pnpm lint {수정한 파일 경로}
+
+# 관련 테스트 실행
+pnpm test -- {관련 테스트 파일 경로}
+```
+
+실패하면 에러를 읽고 수정한다. 모든 항목이 통과할 때까지 반복한다.
+
+### 6단계 — 결과 보고
+
+- 수정한 파일 목록
+- 파일별 적용한 원칙과 변경 내용 요약
+- 트레이드오프가 있었던 경우 판단 이유 명시
+- 이번 리팩터링 범위에서 의도적으로 제외한 항목이 있다면 이유 명시
+- 테스트가 추가로 필요하다 판단되면 언급 (`/write-tests` 실행 제안)