[Chore] : Claude Code 워크플로우 커맨드 및 설정 구성 (#166)

.claude/commands/commit.md

@@ -0,0 +1,48 @@
+# /commit — Commit
+
+Git 커밋 규칙에 따라 커밋 메시지를 생성하고 커밋한다.
+
+## Steps
+
+1. 현재 브랜치 이름을 확인한다.
+
+   ```
+   git branch --show-current
+   ```
+
+2. 브랜치 이름에서 이슈 번호를 추출한다.
+   - 규칙: `<type>/` 이후 첫 번째 숫자
+   - 예: `feat/42-addSearchFilter` → `42`
+
+3. `gh issue view <번호> --json title,body,labels` 로 이슈를 조회해 맥락을 파악한다.
+
+4. `git diff --staged` 또는 `git diff HEAD` 로 변경 내용을 확인한다.
+   - 변경 내용을 기반으로 커밋 메시지를 한국어로 작성한다.
+   - 사용자에게 확인을 구하지 않는다.
+
+5. 커밋 메시지 포맷:
+
+   ```
+   <type> : 변경 내용 요약 (한국어) (#이슈번호)
+   ```
+
+   예: `feat : 검색 필터 API 연동 (#42)`
+
+6. 스테이징 및 커밋 실행:
+
+   ```
+   git add -A
+   git commit -m "<type> : 변경 내용 요약 (#이슈번호)"
+   ```
+
+7. 완료 후 출력:
+   ```
+   ✅ 커밋 완료: <type> : 변경 내용 요약 (#이슈번호)
+   ```
+
+## Notes
+
+- `git push` 는 명시적으로 요청받았을 때만 실행한다.
+- `commit all` 명령 시 이 플로우를 즉시 실행한다.
+- /verify 를 통과하지 않은 상태에서 커밋 요청 시
+  "/verify 를 먼저 실행하세요." 를 출력하고 중단한다.

.claude/commands/green.md

@@ -0,0 +1,40 @@
+# /green — Green Phase
+
+실패 중인 테스트를 통과시키는 최소한의 구현 코드를 작성한다.
+
+## Rules
+
+- **과도한 추상화 금지**: 지금 당장 필요한 것만 구현한다. 미래를 위한 설계는 /refactor 단계에서 한다.
+- **컴포넌트**: 함수형 컴포넌트 + hooks only. 클래스 컴포넌트 금지.
+- **서버 상태**: `useQuery` / `useMutation` 만 사용. 컴포넌트 내 axios 직접 호출 금지.
+- **타입**: `any` 사용 금지. 명시적 interface 또는 generic 사용.
+- **에러/로딩 처리**: skeleton 및 error boundary 상태를 항상 처리한다.
+
+## Steps
+
+1. 실패 중인 테스트 목록을 확인한다 (`pnpm vitest run {파일경로}`).
+2. 테스트를 통과시키는 구현 코드를 작성한다.
+3. `pnpm vitest run {파일경로}` 를 재실행해 모든 테스트가 통과하는지 확인한다.
+4. 통과 후 아래 형식으로 출력한다.
+
+---
+
+## ✅ Green Phase 완료
+
+**통과한 테스트**: N개
+**작성/수정한 파일**:
+
+- `경로/파일명` — (한 줄 설명)
+
+## 🎓 **Mentor note**: (이번 구현에서 적용한 패턴 또는 주니어가 놓치기 쉬운 포인트)
+
+5. 아래 다음 단계 안내를 출력한다.
+
+### 👉 다음 단계
+
+| 명령어      | 설명                          |
+| ----------- | ----------------------------- |
+| `/refactor` | 코드 품질 개선 (동작 변경 X, 생략 가능) |
+| `/verify`   | 품질에 문제 없으면 바로 검증 (필수)     |
+
+> `/refactor` 는 생략 가능. `/verify` → `/commit` 은 항상 실행.

.claude/commands/pr.md

@@ -0,0 +1,83 @@
+# /pr — Pull Request
+
+현재 브랜치의 PR을 생성하고 Qodo AI 코드 리뷰를 요청한다.
+
+## Steps
+
+1. 현재 브랜치 이름을 확인한다.
+
+   ```
+   git branch --show-current
+   ```
+
+2. 브랜치 이름에서 작업 유형과 이슈 번호를 추출한다.
+   - 규칙: `<type>/<issue-number>-<camelCaseName>`
+   - 예: `feat/42-addSearchFilter` → type=`feat`, issue=`42`
+
+3. `gh issue view <번호> --json title,body,labels` 로 이슈 정보를 조회한다.
+
+4. `git log develop..HEAD --oneline` 과 `git diff develop...HEAD` 로 변경 내용을 파악한다.
+
+5. `.github/pull_request_template.md` 양식에 맞춰 PR 본문을 작성한다.
+
+   ```markdown
+   ## 📌 PR 제목
+
+   ### [Type] : 작업 내용 요약
+
+   ## 📌 변경 사항
+
+   - 변경 1
+   - 변경 2
+
+   ## 💬 추가 참고 사항
+
+   - 관련 이슈: #<번호>
+   ```
+
+   - PR 제목: `[Type] : 작업 내용 요약 (#이슈번호)` (한국어)
+   - Type은 브랜치의 작업 유형을 대문자로 (feat → Feat, fix → Fix 등)
+   - 변경 사항은 커밋 내역과 diff를 기반으로 bullet 정리
+
+6. PR을 생성한다.
+
+   ```
+   gh pr create --base develop --title "<PR 제목>" --body "<PR 본문>"
+   ```
+
+   생성된 PR 번호를 추출한다.
+
+7. Qodo AI 코드 리뷰를 위해 댓글을 순서대로 작성한다.
+
+   ```
+   gh pr comment <PR번호> --body "/describe"
+   gh pr comment <PR번호> --body "/review"
+   gh pr comment <PR번호> --body "/improve"
+   ```
+
+8. 완료 후 아래 형식으로 출력한다.
+
+---
+
+## 📋 PR 생성 완료
+
+**PR**: #<PR번호> — <PR 제목>
+**Base**: `develop` ← `<현재 브랜치>`
+**이슈**: #<이슈번호>
+
+### 🤖 Qodo AI 리뷰 요청
+
+- [x] `/describe` — PR 설명 자동 생성
+- [x] `/review` — 코드 리뷰
+- [x] `/improve` — 개선 제안
+
+**PR 링크**: <PR URL>
+
+---
+
+## Notes
+
+- PR의 base 브랜치는 `develop` 이다.
+- 이슈 번호를 추출할 수 없는 경우 이슈 연결 없이 PR을 생성한다.
+- PR 생성 실패 시 에러 메시지를 출력하고 중단한다.
+- Qodo AI 댓글 실패 시 경고를 출력하되 PR 생성 자체는 성공으로 처리한다.

.claude/commands/red.md

@@ -0,0 +1,41 @@
+# /red — Red Phase
+
+현재 작업 범위에 대해 실패하는 테스트를 먼저 작성한다. 구현 코드는 작성하지 않는다.
+
+## Rules
+
+- 테스트 파일 위치: 구현 파일과 동일 경로에 `*.test.ts(x)` 생성
+- 테스트 러너: Vitest (`import { describe, it, expect } from 'vitest'`)
+- 아직 존재하지 않는 함수/컴포넌트를 import해도 된다.
+  테스트가 컴파일 에러 또는 실패 상태여야 정상이다.
+- 테스트 설명은 한국어로 작성한다. (`it('빈 배열이면 빈 문자열을 반환한다')`)
+- `any` 타입 사용 금지. 테스트에도 명시적 타입을 사용한다.
+
+## Test Coverage
+
+아래 케이스를 커버하는 테스트를 작성한다.
+
+1. **Happy path**: 정상 입력 → 예상 출력
+2. **Edge case**: 빈 값, null, undefined, 경계값
+3. **Error case**: 에러 발생 시 동작 (throw, error state 등)
+
+## Steps
+
+1. /spsc 에서 정의한 완료 기준을 기반으로 테스트 케이스 목록을 먼저 나열한다.
+2. 테스트 코드를 작성한다.
+3. `pnpm vitest run {파일경로}` 를 실행해 테스트가 실패하는지 확인한다.
+4. 실패 확인 후 아래를 출력한다.
+
+---
+
+## 🔴 Red Phase 완료
+
+**작성한 테스트 케이스**:
+
+- [ ] (케이스 목록)
+
+### 👉 다음 단계
+
+| 명령어    | 설명                     |
+| --------- | ------------------------ |
+| `/green`  | 테스트를 통과시키는 구현 |

.claude/commands/refactor.md

@@ -0,0 +1,58 @@
+# /refactor — Refactor Phase
+
+테스트를 통과한 코드의 품질을 개선한다. 동작은 변경하지 않는다.
+
+## Checklist
+
+아래 기준으로 코드를 검토하고, 문제가 있으면 수정한다.
+
+### 구조
+
+- [ ] SRP: 하나의 함수/컴포넌트가 너무 많은 일을 하지 않는가?
+      → 로직이 많으면 custom hook으로 분리
+- [ ] DRY: 중복 코드가 있는가?
+      → 공통 유틸 또는 shared 컴포넌트로 추출
+- [ ] 컴포넌트가 100줄을 넘는가?
+      → 하위 컴포넌트로 분리 검토
+
+### 타입
+
+- [ ] `any` 타입이 있는가? → 제거
+- [ ] 리터럴 유니온 타입으로 좁힐 수 있는 `string`/`number`가 있는가?
+- [ ] Props interface가 명시적으로 정의되어 있는가?
+
+### 성능
+
+- [ ] `useMemo`/`useCallback`이 증명 없이 남용되고 있지 않은가?
+- [ ] 불필요한 리렌더링을 유발하는 구조가 있는가?
+
+### 네이밍
+
+- [ ] 함수/변수명이 역할을 명확히 설명하는가?
+- [ ] 이벤트 핸들러는 `handle` 접두어를 사용하는가? (`handleSubmit`, `handleChange`)
+- [ ] boolean은 `is`/`has`/`can` 접두어를 사용하는가?
+
+## Steps
+
+1. 위 체크리스트를 순서대로 검토한다.
+2. 문제가 있는 항목만 수정한다 (diff 중심으로 출력).
+3. 수정 후 `pnpm vitest run {파일경로}` 를 실행해 테스트가 여전히 통과하는지 확인한다.
+4. 아래 형식으로 출력한다.
+
+---
+
+## 🔧 Refactor 완료
+
+**개선한 항목**:
+
+- (체크리스트 항목 + 간단한 이유)
+
+**변경 없는 항목**: (개선이 필요 없었던 항목)
+
+## 🎓 **Mentor note**: (이번 리팩토링의 핵심 포인트)
+
+### 👉 다음 단계
+
+| 명령어    | 설명               |
+| --------- | ------------------ |
+| `/verify` | 머지 전 전체 검증  |

.claude/commands/spsc.md

@@ -0,0 +1,53 @@
+# /spsc — Spec & Scope
+
+주어진 GitHub Issue 번호를 기반으로 작업 범위를 정의한다.
+
+## Steps
+
+1. `gh issue view <번호> --json title,body,labels,assignees,milestone` 로 이슈 상세를 조회한다.
+   - 체크리스트(task list)가 있으면 하위 작업 목록도 함께 확인한다.
+
+2. 아래 형식으로 작업 범위를 출력한다.
+
+---
+
+## 📋 Spec & Scope — #{ISSUE-NUMBER}
+
+**이슈 제목**: (원문)
+**작업 유형**: Feature | Bugfix | Refactor | Chore
+
+### 구현 범위
+
+- (구체적인 작업 항목 bullet)
+
+### 변경 예상 파일
+
+- `src/features/.../` — (이유)
+- `src/shared/.../` — (이유)
+
+### 범위 외 (이번 작업에서 하지 않는 것)
+
+- (명시적으로 제외할 항목)
+
+### 완료 기준
+
+- [ ] (체크리스트 형태)
+
+---
+
+3. 출력 후 "이 범위로 진행할까요?" 라고 확인을 구한다.
+   - 승인 시 작업 브랜치를 생성한다.
+     - 브랜치 형식: `<type>/<issue-number>-<camelCaseName>`
+     - type 매핑: Feature → `feat`, Bugfix → `fix`, Refactor → `refactor`, Chore → `chore`
+     - 예: `feat/42-addSearchFilter`
+     - develop 브랜치에서 분기한다.
+   - 이후 아래 다음 단계 안내를 출력한다.
+
+### 👉 다음 단계
+
+| 명령어    | 설명                         |
+| --------- | ---------------------------- |
+| `/red`    | 실패 테스트 먼저 작성 (TDD)  |
+| `/green`  | 바로 구현 시작               |
+
+> `/red` ~ `/refactor` 사이클은 생략 가능. `/verify` → `/commit` 은 필수.