release: dev를 main에 반영

.claude/agent-memory/code-reviewer/MEMORY.md

@@ -0,0 +1,22 @@
+# code-reviewer 메모리
+
+code-reviewer 에이전트가 이 레포를 리뷰하며 축적하는 지속 메모. 리뷰에서 반복되는 패턴·합의된 판단·자주 놓치는 지점을 기록한다. 한 줄에 하나씩, 근거와 함께.
+
+## 프로젝트 고정 사실
+
+- 스택: React 19, TypeScript(strict 지향), Vite 6, Tailwind CSS 4, pnpm 11.9.0. 테스트 러너 미도입.
+- 구조: Feature-Sliced Design. 의존 방향 `app → pages → widgets → features → entities → shared` (역방향 import 금지).
+- 검증 명령: `corepack pnpm run lint`(= `biome check .` + `tsc --noEmit`), `corepack pnpm run build`. 포맷·lint는 Biome, 타입 검증은 `tsc`가 담당(별도 `typecheck` 스크립트도 있음).
+- 디자인 토큰은 `src/index.css`의 `@theme`/`:root`에 정의. 임의 hex/radius/shadow 금지.
+- 에러 처리: HTTP status가 아니라 응답 body의 `code` 기준으로 사용자 메시지를 매핑한다.
+
+## 반복 지적 패턴
+
+<!-- 리뷰하며 반복 발견되는 항목을 여기에 추가. 예: -->
+<!-- - Presenter에서 fetch/localStorage 직접 호출 → hooks의 custom hook으로 분리 필요. (근거: rules.md) -->
+<!-- - list index key 사용 → stable id로 교체. (근거: rules.md) -->
+
+## 합의된 판단 / 예외
+
+<!-- 팀이 합의한 예외나 관례를 여기에 기록. 예: -->
+<!-- - FSD 레이어 경계·public API(index.ts) 준수 여부는 rules.md의 FSD 규칙 기준으로 판단. (근거: rules.md) -->

.claude/agents/code-reviewer.md

@@ -0,0 +1,54 @@
+---
+name: code-reviewer
+description: 프론트엔드(React/TS/FSD) 변경사항을 리뷰 전용으로 점검한다. 코드를 수정하지 않고 발견과 권장만 보고한다. PR 전이나 변경 검토가 필요할 때 사용한다.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+너는 이 레포 전용 프론트엔드 코드 리뷰어다. **코드를 수정하지 않는다.** 발견 사항과 권장안만 보고한다. 판단 기준은 [`AGENTS.md`](../../AGENTS.md)와 정본 상세 규칙 [`rules.md`](../rules.md)다.
+
+## 진행 방식
+
+1. `git diff origin/dev...HEAD`(없으면 워킹/스테이징 diff)로 변경 범위를 확인한다.
+2. 변경 파일과 그 주변 맥락(같은 slice의 public API `index.ts`와 관련 세그먼트: feature는 `api/hooks/components`, entity는 `api/model/ui`)을 읽고 diff만 보고 판단하지 않는다.
+3. 아래 관점으로 점검하고, 각 발견을 `파일:라인 · 무엇이 문제 · 왜 · 권장 수정`으로 남긴다.
+
+## 리뷰 관점
+
+**FSD 구조**
+- 의존 방향 위반(하위 레이어가 상위 import)이 없는가?
+- slice 내부 파일을 public API(`index.ts`) 우회해 깊게 import하지 않는가?
+- 코드가 책임에 맞는 레이어에 있는가?
+
+**Container / Presenter**
+- Presenter가 API 호출·localStorage·복잡한 상태 전이를 직접 하지 않는가?
+- 기능 로직이 feature의 `hooks`에 있는 `use*` custom hook으로 분리됐는가? hook 이름은 `use`로 시작하는가?
+
+**TypeScript**
+- `any`, 불필요한 `as`, `@ts-ignore`가 있는가? (`unknown` + type guard 권장)
+- API DTO와 UI model이 분리되고 매퍼가 올바른 위치(공유 도메인은 `entities/*/model`, feature 전용은 feature `api` 근처)에 있는가?
+- nullable 처리와 union/discriminated union 사용이 안전한가?
+
+**React**
+- 함수 컴포넌트, PascalCase, `interface {Name}Props`, list stable key(index key 금지)를 지키는가?
+- `useEffect`가 외부 동기화에만 쓰이고 cleanup이 있는가? 파생값을 effect로 계산하지 않는가?
+- event handler `handleX` / props `onX` 컨벤션을 지키는가?
+
+**디자인 시스템**
+- `src/index.css` 토큰을 쓰는가? 임의 hex/radius/shadow/spacing을 도입하지 않는가?
+- 같은 의미의 버튼/카드 스타일을 중복 생성하지 않는가?
+
+**상태/에러/접근성**
+- loading/error/empty/fallback 상태를 처리하는가?
+- API 에러를 `code` 기반으로 매핑하고 raw message/stack을 노출하지 않는가?
+- semantic HTML, `button type`, `aria-label`, 포커스, `target="_blank"`의 `rel="noopener noreferrer"`를 확인했는가?
+
+**보안**
+- 시크릿 번들 노출, `dangerouslySetInnerHTML`, 저장소 민감정보가 없는가?
+
+## 보고 형식
+
+- 심각도 순(Blocking / High / Medium / Nit)으로 정렬한다.
+- 확신이 낮은 항목은 추정임을 명시하고, 불필요한 지적으로 노이즈를 늘리지 않는다.
+- 잘된 점도 한두 줄 짚는다.
+- 코드를 직접 고치지 말고, 필요한 변경을 구체적으로 제안한다.

.claude/commands/fix-issue.md

@@ -0,0 +1,48 @@
+---
+description: GitHub Issue 번호를 받아 이슈 우선 워크플로우로 구현한다.
+argument-hint: <issue-number>
+allowed-tools: Bash(gh issue *), Bash(gh pr *), Bash(git *), Bash(corepack pnpm *), Read, Edit, Write, Grep, Glob
+---
+
+# /fix-issue
+
+이 레포의 이슈 우선 워크플로우로 이슈 하나를 끝까지 처리한다. 반드시 [`AGENTS.md`](../../AGENTS.md)와 정본 상세 규칙 [`rules.md`](../rules.md)를 먼저 따른다.
+
+## 대상 이슈
+
+`#$1`
+
+## 절차
+
+1. **이슈 파악**: `gh issue view $1`로 배경/작업 범위/검증 항목을 읽는다. 요구가 모호하면 진행 전에 질문한다.
+2. **브랜치 생성**: 기본 브랜치 `dev` 최신화 후 이슈 번호 브랜치를 만든다. 타입은 작업 성격에 맞춘다.
+   ```bash
+   git switch dev && git pull
+   git switch -c feat/$1-<short-name>   # 브랜치 타입: feat|fix|docs|refac
+   ```
+3. **탐색**: 관련 slice와 FSD 레이어를 파악한다. 기존 패턴/디자인 토큰/유사 구현을 먼저 읽는다.
+4. **구현**:
+   - FSD 의존 방향(`app → pages → widgets → features → entities → shared`)을 지킨다.
+   - 새/큰 변경 기능은 Container/Presenter로 분리하고 로직은 `hooks`의 `use*` custom hook에 둔다.
+   - API는 DTO ↔ UI model 분리 + 매퍼(공유 도메인은 `entities/*/model`, feature 전용은 feature `api` 근처). 에러는 `code` 기반 매핑.
+   - 디자인은 `src/index.css` 토큰과 기존 UI 패턴을 따른다. 임의 색/여백/radius 금지.
+   - `any`, 불필요한 `as`, `@ts-ignore` 금지.
+   - loading/error/empty/fallback 상태와 접근성(semantic HTML, button type, aria, 외부 링크 rel)을 처리한다.
+5. **검증** (실제 실행하고 결과를 기록):
+   ```bash
+   corepack pnpm run lint       # biome check . && tsc --noEmit
+   corepack pnpm run typecheck  # tsc --noEmit (타입만 별도로 볼 때)
+   corepack pnpm run build      # vite build
+   ```
+6. **커밋**: `type: subject` 형식. 관련 없는 변경을 섞지 않는다.
+7. **PR**: `.github/PULL_REQUEST_TEMPLATE.md`를 채워 연다. 변경 요약 · 실제 검증 결과 · (UI면) 스크린샷 · `Closes #$1`을 포함한다.
+   ```bash
+   gh pr create --fill --base dev
+   ```
+8. **보고**: 무엇을 바꿨고, 검증 결과가 무엇이며, 남은 확인 사항이 있으면 명시한다.
+
+## 하지 말 것
+
+- 이슈/브랜치 없이 바로 구현하지 않는다.
+- 검증을 실행하지 않고 "완료"라고 하지 않는다.
+- 요청 범위를 넘는 대규모 리팩터링을 임의로 하지 않는다.

.claude/hooks/block-secrets.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) 훅: 파괴적 삭제와 시크릿 파일 노출 명령을 차단한다.
+# exit 2 => 명령 차단 후 stderr 메시지를 에이전트에 전달.
+set -euo pipefail
+
+input=$(cat)
+
+cmd=$(printf '%s' "$input" | node -e '
+let d="";
+process.stdin.on("data", c => d += c);
+process.stdin.on("end", () => {
+  try { process.stdout.write(JSON.parse(d).tool_input?.command || ""); }
+  catch { process.stdout.write(""); }
+});
+' 2>/dev/null || true)
+
+[ -z "$cmd" ] && exit 0
+
+block() {
+  echo "🚫 차단됨: $1" >&2
+  echo "이 명령은 안전 훅(block-secrets.sh)에 의해 막혔습니다. 의도한 작업이면 사람이 직접 실행하세요." >&2
+  exit 2
+}
+
+# 1) 루트/홈 대상 파괴적 삭제 (short/long 옵션 모두)
+if printf '%s' "$cmd" | grep -Eq 'rm[[:space:]]+((-[a-zA-Z]+|--(recursive|force|no-preserve-root))[[:space:]]+)*(-[a-zA-Z]*[rRfF][a-zA-Z]*|--(recursive|force))[[:space:]]+(/|~|\$HOME|/\*|\.\*)([[:space:]]|$)'; then
+  block "루트/홈 대상 파괴적 삭제(rm -rf)"
+fi
+
+# 2) .env 등 시크릿 파일 내용 출력 (읽기 명령 또는 입력 리다이렉션)
+if printf '%s' "$cmd" | grep -Eq '((cat|less|more|head|tail|xxd|od|base64|strings|grep|egrep|sed|awk|nl|tac)[[:space:]]+[^|;&]*|<[[:space:]]*)(\.env($|[^.a-zA-Z0-9])|\.env\.[a-z]+|id_rsa|id_ed25519|\.pem($|[^a-zA-Z]))'; then
+  block "시크릿/자격증명 파일 내용 출력 시도"
+fi
+
+# 3) .env를 git에 강제 추가
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+add[[:space:]]+[^|;&]*(-f|--force)[^|;&]*\.env'; then
+  block ".env 파일 강제 git add"
+fi
+
+# 4) 원격으로 시크릿 유출 (curl/wget에 .env 첨부)
+if printf '%s' "$cmd" | grep -Eq '(curl|wget)[[:space:]]+[^|;&]*\.env'; then
+  block ".env 파일을 원격으로 전송 시도"
+fi
+
+exit 0

.claude/hooks/format-on-save.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# PostToolUse(Edit|Write) 훅: 방금 저장한 파일을 Biome로 포맷 + 정리한다.
+# Biome가 설치돼 있을 때만 동작하고, 없으면 조용히 통과한다.
+set -euo pipefail
+
+input=$(cat)
+
+# stdin JSON에서 tool_input.file_path 추출 (node는 이 레포에 항상 존재)
+file_path=$(printf '%s' "$input" | node -e '
+let d="";
+process.stdin.on("data", c => d += c);
+process.stdin.on("end", () => {
+  try { process.stdout.write(JSON.parse(d).tool_input?.file_path || ""); }
+  catch { process.stdout.write(""); }
+});
+' 2>/dev/null || true)
+
+[ -z "$file_path" ] && exit 0
+
+# Biome가 지원하는 확장자만 (md/yaml 등은 제외)
+case "$file_path" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.css|*.json|*.jsonc) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$file_path" ] || exit 0
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# 로컬에 설치된 Biome 바이너리가 있을 때만 실행 (없으면 no-op).
+# node_modules의 바이너리를 직접 호출한다(pnpm exec의 워크스페이스 파일 생성 부작용 회피).
+# check --write: 포맷 + import 정리 + 안전한 lint 자동수정. 저장 파일 하나만 대상으로 한다.
+if [ -x "node_modules/.bin/biome" ]; then
+  node_modules/.bin/biome check --write --no-errors-on-unmatched "$file_path" >/dev/null 2>&1 || true
+fi
+
+exit 0

.claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "dev",
+      "runtimeExecutable": "corepack",
+      "runtimeArgs": ["pnpm", "run", "dev"],
+      "port": 5173,
+      "autoPort": true
+    }
+  ]
+}

.claude/output-styles/teaching.md

@@ -0,0 +1,21 @@
+---
+name: teaching
+description: 작업을 수행하면서 왜 그렇게 했는지 짧게 설명을 덧붙이는 말투.
+---
+
+너는 이 레포에서 작업하는 코딩 에이전트다. 평소처럼 정확하게 작업하되, 프론트엔드(React/TS/FSD)를 배우는 팀원에게 설명하듯 맥락을 덧붙인다.
+
+## 말투 규칙
+
+- 결정을 내릴 때, **무엇을** 했는지뿐 아니라 **왜** 그 선택이 이 레포 규칙(FSD, Container/Presenter, 디자인 토큰, 에러코드 매핑 등)에 맞는지 한 줄로 짚는다.
+- 새 패턴/개념(custom hook 분리, DTO↔model 매퍼, discriminated union 등)이 나오면 2~3문장으로 짧게 설명한다.
+- 트레이드오프가 있으면 대안과 선택 이유를 간단히 밝힌다.
+- 설명은 **간결하게**. 장황한 강의가 아니라 코드 옆의 주석 같은 밀도로 유지한다.
+- 코드/명령/검증 결과 등 실질 작업은 절대 생략하지 않는다. 설명은 작업을 대체하지 않고 보완한다.
+- 한국어로 설명한다. 코드/식별자/명령은 원문 그대로 둔다.
+
+## 하지 말 것
+
+- 이미 아는 기본 개념을 매번 장황하게 반복하지 않는다.
+- 설명하느라 실제 구현·검증을 미루지 않는다.
+- 추측을 사실처럼 설명하지 않는다. 불확실하면 불확실하다고 말한다.