release: dev를 main에 반영

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

@@ -0,0 +1,13 @@
+# code-reviewer 메모리 (인덱스)
+
+이 파일은 code-reviewer 에이전트가 리뷰를 반복하며 축적하는 학습의 인덱스다. 상세 노트는 같은 디렉토리의 주제별 파일로 분리한다.
+
+## 프로젝트 리뷰 기준 (요약)
+
+- 규칙 원본은 `.claude/rules/`. 리뷰 지적은 항상 규칙 문서 근거와 함께 남긴다.
+- 에러코드는 `ErrorCode` 인터페이스 + `{domain}.exception.{Domain}ErrorCode` enum 구조. 접두어 체계(C/A/S/U/P/F/D)를 지키는지 본다.
+- 성공 응답은 `ApiResponse`(data+meta), 에러는 `ErrorResponse`(code 기반). 페이지 정보는 `meta`에.
+
+## 반복 발견 패턴
+
+(아직 없음 — 리뷰를 진행하며 자주 나오는 위반/오탐 패턴을 여기에 축적한다.)

.claude/agents/code-reviewer.md

@@ -0,0 +1,30 @@
+---
+name: code-reviewer
+description: YouthPick 백엔드 코드 리뷰 전용 에이전트. 규칙 위반·버그·보안 관점으로 검토하고 보고만 한다. 코드를 수정하지 않는다. PR 전이나 변경분 리뷰가 필요할 때 사용.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+너는 YouthPick 백엔드 코드 리뷰어다. **코드를 수정하지 않는다.** 발견 사항을 심각도순으로 보고만 한다.
+
+## 기준 문서
+
+리뷰 전에 관련 규칙을 읽는다: [`.claude/rules/`](../rules/) 의 `architecture.md`, `api-design.md`, `error-handling.md`, `entity-jpa.md`, `service.md`, `lombok.md`, `auth-security.md`, `testing.md`.
+
+## 리뷰 관점 (순서대로)
+
+1. **규칙 위반** — 패키지 구조, 얇은 Controller, `@Valid` 누락, Entity 직접 반환, `ApiResponse` 미사용, raw `RuntimeException`, Pageable 미사용, 금지 Lombok.
+2. **버그/정확성** — 트랜잭션 경계, null/Optional 처리, 경계 조건, 동시성.
+3. **보안** — secret/토큰 노출, 인가 누락(IDOR), 입력 검증 우회. (깊은 점검은 `security-review` 스킬)
+4. **테스트** — A(정상)/E(예외)/X(경계) 관점 누락 여부.
+
+## 출력 형식
+
+각 발견 사항을 다음으로 보고한다:
+
+- **심각도**: critical / high / medium / low
+- **위치**: `파일:라인`
+- **문제**: 무엇이 왜 잘못됐는지 한 문장
+- **제안**: 어떻게 고칠지
+
+확신이 없으면 "가능성"으로 표시하고 근거를 남긴다. 근거 없는 확정 지적을 하지 않는다. 발견이 없으면 없다고 명확히 말한다.

.claude/commands/fix-issue.md

@@ -0,0 +1,15 @@
+---
+description: GitHub 이슈를 Git 컨벤션대로 브랜치 생성부터 검증까지 처리한다
+argument-hint: <이슈번호>
+allowed-tools: Bash(git checkout:*), Bash(git switch:*), Bash(git branch:*), Bash(git add:*), Bash(git commit:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(gh issue view:*), Bash(gh pr create:*), Bash(./gradlew test:*), Read, Edit, Write, Grep, Glob
+---
+
+이슈 #$1 을 이 레포의 Git 컨벤션([.claude/rules/workflow.md](../rules/workflow.md))에 따라 처리한다.
+
+1. `gh issue view $1` 로 이슈 내용·작업 범위·검증 기준을 파악한다.
+2. 기본 분기(`dev` 있으면 `dev`, 없으면 `main`)에서 `type/$1-{short-name}` 브랜치를 만든다. type은 이슈 성격에 맞춰 `feat|fix|docs|refac` 중 고른다.
+3. 관련 규칙 파일(`.claude/rules/`)을 먼저 읽고, 규칙을 지키며 구현한다.
+4. 관련 작은 테스트 → 전체 `./gradlew test` 순으로 검증한다. (JAVA_HOME 필요 시 `CLAUDE.local.md` 참고)
+5. `type: subject` 커밋을 만들고, 변경 내용·검증 결과·`Closes #$1` 을 담은 PR 본문 초안을 제시한다.
+
+파괴적이거나 이슈 범위를 벗어나는 결정이 필요하면 진행 전에 사용자에게 확인한다.

.claude/hooks/block-secrets.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) 훅: 위험한 파괴 명령과 시크릿 파일 접근을 차단한다.
+# 차단 시 exit code 2 + stderr 사유. Claude Code가 사유를 읽고 명령을 막는다.
+#
+# 정규식만으로는 `rm -r -f`, `rm --recursive --force`, `git add .` 같은 우회가
+# 쉬우므로, python3 + shlex로 토큰을 파싱해 플래그/대상/서브명령을 판별한다.
+# 프로그램은 -c 인자로 넘겨 stdin(훅 JSON)을 그대로 python에 전달한다.
+
+set -uo pipefail
+
+exec python3 -c '
+import json, sys, shlex, os, re, subprocess
+
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+
+cmd = (data.get("tool_input", {}) or {}).get("command", "") or ""
+if not cmd.strip():
+    sys.exit(0)
+
+def block(msg):
+    sys.stderr.write("block-secrets: 차단됨 — " + msg + "\n")
+    sys.exit(2)
+
+segments = re.split(r"[;\n]|&&|\|\||\||&", cmd)
+
+BROAD_TARGETS = {"/", "~", "$HOME", ".", "./", "*", "./*", "~/", "/*", ".."}
+ENV_RE = re.compile(r"^\.env(\..+)?$")
+ASSIGN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+
+def is_env_file(arg):
+    base = os.path.basename(arg)
+    return bool(ENV_RE.fullmatch(base)) and base != ".env.example"
+
+def dangerous_target(t):
+    tt = t.rstrip("/")
+    return (
+        t in BROAD_TARGETS
+        or tt in ("", "/", "~", "$HOME", ".", "..")
+        or t.startswith(("/", "~", "$HOME"))
+        or "*" in t
+    )
+
+for seg in segments:
+    try:
+        tokens = shlex.split(seg)
+    except ValueError:
+        tokens = seg.split()
+    if not tokens:
+        continue
+
+    idx = 0
+    while idx < len(tokens):
+        t = tokens[idx]
+        if t in ("sudo", "env") or ASSIGN_RE.match(t):
+            idx += 1
+            continue
+        break
+    if idx >= len(tokens):
+        continue
+
+    name = os.path.basename(tokens[idx])
+    args = tokens[idx + 1:]
+
+    # 1) 파괴적 rm (플래그 결합/분리/롱옵션 모두 탐지)
+    if name == "rm":
+        recursive = force = False
+        targets = []
+        for a in args:
+            if a == "--":
+                continue
+            if a == "--recursive":
+                recursive = True
+            elif a == "--force":
+                force = True
+            elif a.startswith("--"):
+                pass
+            elif a.startswith("-") and len(a) > 1:
+                flags = a[1:]
+                if "r" in flags or "R" in flags:
+                    recursive = True
+                if "f" in flags:
+                    force = True
+            else:
+                targets.append(a)
+        if recursive and any(dangerous_target(x) for x in targets):
+            block("위험한 rm -r 대상(루트/홈/현재 디렉토리/와일드카드). 삭제 대상을 구체적 경로로 좁혀라.")
+
+    # 2) 시크릿 파일(.env) 내용 노출
+    if name in ("cat", "less", "more", "head", "tail", "cp", "scp",
+                "curl", "nc", "xxd", "base64", "strings", "bat", "grep"):
+        if any(is_env_file(a) for a in args if not a.startswith("-")):
+            block("시크릿 파일(.env) 내용 노출 시도. .env는 커밋·출력·전송하지 않는다.")
+
+    # 3) git add 로 .env 스테이징 (명시적/광범위/force 모두 고려)
+    if name == "git":
+        # git 전역 옵션(-C <path>, -c <k=v>, --git-dir <path> 등)을 먼저 건너뛰고
+        # 실제 서브명령을 찾는다. 값을 따로 받는 옵션은 다음 토큰까지 스킵.
+        # (git -C x add ., git -c k=v add .env 우회 방지)
+        VALUE_OPTS = ("-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix")
+        gi = 0
+        while gi < len(args) and args[gi].startswith("-"):
+            gi += 2 if args[gi] in VALUE_OPTS else 1
+        subcmd = args[gi] if gi < len(args) else None
+        add_args = args[gi + 1:]
+
+        if subcmd == "add":
+            positionals = [a for a in add_args if not a.startswith("-")]
+            force_add = any(a in ("-f", "--force") for a in add_args)
+            explicit_env = any(is_env_file(a) for a in positionals)
+            broad = any(a in (".", "./", "-A", "--all", "-u", "--update", "*") for a in add_args)
+
+            if explicit_env:
+                block(".env를 git에 추가하려는 시도. .env는 커밋 금지.")
+            if broad or force_add:
+                status_cmd = ["git", "status", "--porcelain"]
+                if force_add:
+                    status_cmd.append("--ignored")
+                status_cmd += ["--", ".env"]
+                try:
+                    out = subprocess.run(status_cmd, capture_output=True, text=True, timeout=5)
+                    if out.stdout.strip():
+                        block(".env가 스테이징 대상에 포함될 수 있음. .env는 커밋 금지.")
+                except Exception:
+                    pass
+
+sys.exit(0)
+'

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# PostToolUse(Edit|Write) 훅: .java 파일을 저장하면 Spotless로 포맷한다.
+# Spotless가 build.gradle에 없으면 조용히 통과한다(no-op).
+# 훅 stdin은 Claude Code가 주는 JSON. tool_input.file_path 를 뽑는다.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+file_path="$(python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print(""); sys.exit(0)
+ti = data.get("tool_input", {}) or {}
+print(ti.get("file_path", "") or "")
+' 2>/dev/null || true)"
+
+# .java 파일이 아니면 아무것도 하지 않는다.
+case "$file_path" in
+  *.java) ;;
+  *) exit 0 ;;
+esac
+
+# Spotless 미설정이면 no-op.
+if ! grep -q "spotless" "$PROJECT_DIR/build.gradle" 2>/dev/null; then
+  exit 0
+fi
+
+cd "$PROJECT_DIR"
+# JAVA_HOME이 없으면 gradle이 실패하므로, 있을 때만 시도한다.
+if [ -z "${JAVA_HOME:-}" ] && ! command -v java >/dev/null 2>&1; then
+  echo "format-on-save: JAVA_HOME 미설정으로 스킵" >&2
+  exit 0
+fi
+
+./gradlew spotlessApply "-PspotlessFiles=$(printf '%s' "$file_path" | sed 's/[.[\*^$/]/\\&/g')" >/dev/null 2>&1 || true
+exit 0

.claude/output-styles/teaching.md

@@ -0,0 +1,12 @@
+---
+name: Teaching
+description: 변경한 코드에 왜 그렇게 했는지 설명을 덧붙이는 말투. 학습·온보딩용.
+---
+
+너는 평소처럼 YouthPick 백엔드 작업을 수행하되, 결과에 **왜 그렇게 했는지**를 함께 설명한다. 신입 개발자가 옆에서 배우는 상황을 가정한다.
+
+- 코드를 바꾼 뒤에는 "무엇을 바꿨는지"뿐 아니라 "왜 이 방식인지"를 한두 문장으로 덧붙인다. 특히 이 레포의 규칙(`.claude/rules/`)과 연결해 설명한다. 예: "요청 DTO에 `@Valid`를 붙인 이유는 검증 실패를 `GlobalExceptionHandler`가 `C001`로 통일해 내려주기 때문이다."
+- 대안이 있었다면 왜 그 대안을 택하지 않았는지 짧게 언급한다.
+- Spring/JPA 관용구가 처음 등장하면 한 줄로 개념을 풀어준다. 단, 이미 다룬 개념을 반복 설명하지 않는다.
+- 설명은 **간결하게**. 코드보다 설명이 길어지지 않게 한다. 장황한 이론 강의가 아니라 "이 결정의 이유"에 집중한다.
+- 실제 동작·검증(테스트 결과)은 여전히 사실대로 보고한다. 설명 말투가 결과 왜곡의 핑계가 되지 않는다.

.claude/rules/api-design.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - "src/main/java/**"
+---
+
+# Controller / DTO / 응답 규칙
+
+## Controller
+
+- 생성자 주입(`@RequiredArgsConstructor` + `final` 필드). 필드 주입(`@Autowired`) 금지.
+- Entity를 API 응답으로 직접 반환하지 않는다.
+- 요청 body 파라미터에는 `@Valid @RequestBody`를 붙인다. validation 없는 요청 DTO, `@Valid` 없는 바인딩은 금지.
+- 성공 응답은 항상 `global.common.ApiResponse`로 감싼다.
+
+## 요청 DTO (`{domain}.dto`)
+
+- `record`를 우선 사용한다. 모든 사용자 입력 필드에 의도를 드러내는 Bean Validation annotation을 붙인다.
+- validation message는 한국어로 작성한다.
+- 문자열은 보통 `@NotBlank`(`@NotNull`은 공백을 못 막는다), 길이는 `@Size`, 허용값 문자열은 `@Pattern`, 숫자 범위는 `@Min`/`@Max`/`@Positive`. 중첩 DTO 필드에는 `@Valid`.
+- enum을 직접 바인딩하면 Jackson deserialization 단계에서 터진다. 잘못된 enum 값을 `C001` 입력값 오류로 내려야 하면 문자열 필드 + `@Pattern`을 사용한다.
+
+```java
+public record UserSignupRequest(
+        @NotBlank(message = "아이디는 필수입니다.")
+        @Size(min = 4, max = 20, message = "아이디는 4~20자여야 합니다.")
+        String username,
+
+        @NotBlank(message = "비밀번호는 필수입니다.")
+        String password
+) {
+}
+```
+
+## 응답 DTO
+
+- Entity를 받아 정적 팩토리 메서드 `from(...)`으로 생성한다.
+- Entity의 민감 필드, 내부 상태, raw payload, secret 값을 노출하지 않는다.
+
+```java
+public record PolicyCardResponse(Long id, String title, String summary) {
+    public static PolicyCardResponse from(Policy policy) {
+        return new PolicyCardResponse(policy.getId(), policy.getTitle(), policy.getSummary());
+    }
+}
+```
+
+## 공통 응답 봉투 `ApiResponse` (data + meta)
+
+- 단일/객체 데이터는 `ApiResponse.ok(data)`. 페이지 부가정보(`page`, `totalCount`, `totalPages`)는 **`data`가 아니라 `meta`(`PageMeta`)에** 담는다.
+- `meta`는 Swagger(OpenAPI) 문서에 필드 스키마가 드러나도록 `Map`이 아니라 타입 있는 `PageMeta` record를 사용한다. 새 부가정보가 필요하면 `Map`으로 돌아가지 말고 `PageMeta`에 필드를 추가하거나 전용 meta 타입을 정의한다.
+- 200 외 상태 코드가 필요하면 `ResponseEntity<ApiResponse<?>>`로 감싼다.
+- 에러 응답은 `ApiResponse`가 아니라 `global.error.ErrorResponse`로 내려간다 (→ `error-handling.md`).
+
+## 페이지네이션 — Spring Data `Pageable`/`Page`
+
+```java
+@GetMapping
+public ApiResponse<List<PolicyCardResponse>> search(@PageableDefault(size = 20) Pageable pageable) {
+    Page<PolicyCardResponse> page = policySearchService.search(pageable);
+    return ApiResponse.ok(page.getContent(), page);
+}
+```
+
+- max page size는 코드의 `Math.min`이 아니라 설정(`spring.data.web.pageable.max-page-size`)으로 제한한다.
+- 금지: `@RequestParam int page/size` 직접 수신, `Math.min(size, 50)` 정규화, `totalPages` 직접 계산.

.claude/rules/architecture.md

@@ -0,0 +1,41 @@
+---
+paths:
+  - "src/main/java/**"
+---
+
+# 패키지 구조
+
+도메인 우선 + 단순 구조를 유지한다. 패키지 루트는 `com.bop.youthpick`.
+
+```text
+com.bop.youthpick
+├── global
+│   ├── common      // ApiResponse 등 공통 응답 봉투
+│   ├── config      // SecurityConfig, RestAuthenticationEntryPoint 등
+│   └── error       // ErrorCode(인터페이스), CustomException, ErrorResponse, GlobalExceptionHandler
+├── admin           // 관리자 전용 코드 — 도메인별 하위 패키지로만 구성
+│   └── {domain}    // admin.policy, admin.board, admin.log, admin.sync, admin.user ...
+│       ├── controller  // Admin* 컨트롤러 (/api/v1/admin/** 경로)
+│       ├── service     // Admin* 서비스
+│       ├── repository  // Admin*Specifications 등 admin 전용 query-spec
+│       └── dto         // admin 응답/요청 전용 DTO
+└── {domain}        // user, policy, auth, favorite(즐겨찾기), diagnosis(자가진단) ...
+    ├── controller  // HTTP Controller와 API 입출력 조립
+    ├── service     // 비즈니스 흐름, scheduler, lock, 외부 API client
+    ├── repository  // Spring Data JPA repository interface
+    ├── dto         // 요청/응답 DTO, service 결과 DTO, 외부 API payload DTO
+    ├── entity      // JPA Entity, domain enum
+    └── exception   // {Domain}ErrorCode(ErrorCode 구현 enum), {Domain}Exception(CustomException 상속)
+```
+
+- `global`에는 여러 도메인이 공유하는 공통 응답·설정·예외 처리만 둔다.
+- 관리자(Admin) 전용 컨트롤러/서비스/query-spec/전용 DTO는 각 도메인이 아니라 최상위 `admin.{domain}` 패키지에 둔다(예: `admin.policy.controller.AdminPolicyController`). 여러 도메인에서 공유하는 Entity·일반 Repository·`{Domain}ErrorCode`는 그대로 각 도메인 패키지에 남기고, admin 쪽에서 그 도메인 패키지를 참조한다 — 반대 방향(도메인 → admin) 의존은 만들지 않는다.
+- 도메인에 아직 필요 없는 하위 패키지는 만들지 않는다.
+- Controller는 얇게: HTTP 파싱, Bean Validation, Service 호출, 응답 DTO 변환만. 비즈니스 판단·중복 검사·외부 API 호출·Entity 상태 변경은 Service에 둔다.
+
+**금지 구조** — DDD식 패키지를 만들지 않는다:
+
+```text
+com.bop.youthpick.{domain}
+├── api / application / domain / infrastructure / external   // ❌
+```