chore: initialize monorepo (Rust backend + Next.js frontend)

Coupang Review AI 프로젝트 초기 세팅.

- monorepo: backend/ (Rust + Axum, Hexagonal) + frontend/ (Next.js 14)
- specification/ 스펙 문서 6종, CLAUDE.md, ADR, 작업 로그
- .claude/ 워크플로우 규칙 + 자동화 훅 14개 ($CLAUDE_PROJECT_DIR 기반)
- CI: .github/workflows backend-ci / frontend-ci (paths 필터)
- 검증: cargo check/fmt/clippy/test, FE type-check/lint/vitest 모두 통과

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: trz-21

.claude/code-rules.md

@@ -0,0 +1,71 @@
+# AI Agent 코드 수정 규칙
+
+코드를 수정할 때 반드시 준수한다.
+
+## 일반 규칙
+
+1. **컴파일 먼저**: `cargo check` 통과 없이 작업 완료 불가
+2. **테스트 통과**: `cargo test` 전체 통과 필수
+3. **API 계약 유지**: 기존 API 응답 필드 제거/타입 변경 금지 (추가만 허용)
+4. **트레이트 계약**: Port trait 변경 시 모든 구현체 동시 수정
+5. **테스트 동반**: 새 엔드포인트/기능 추가 시 테스트 필수
+6. **스펙 동기화**: 기능/설계 변경 시 `specification/` 업데이트 필수
+
+## 백엔드 새 API 엔드포인트 추가 순서
+
+```
+[ ] 1. domain/ports/ 에 필요한 trait 정의 (없으면 추가)
+[ ] 2. adapters/ 에 구현체 작성
+[ ] 3. application/ 에 서비스 로직 작성
+[ ] 4. http/handlers/ 에 핸들러 작성 (매크로 패턴 사용, 아래 참조)
+[ ] 5. http/router.rs 의 route_table() 에 한 줄 추가
+[ ] 6. 통합 테스트 작성 (TestApp + Mock 주입)
+[ ] 7. cargo check && cargo test 통과
+[ ] 8. specification/dev/api.md 업데이트
+```
+
+### 핸들러 작성 규칙
+
+**표준 케이스 → 매크로 사용 (backend/src/http/macros.rs)**
+
+| 패턴 | 매크로 |
+|------|--------|
+| POST + JSON body | `post_endpoint!` |
+| GET + /:id | `get_endpoint_with_id!` |
+| POST + /:id (body 없음) | `post_endpoint_with_id!` |
+
+매크로는 Request/Response 구조체와 핸들러 함수를 함께 생성한다.
+잘못된 타입 또는 서비스 메서드 시그니처는 컴파일 에러로 즉시 검출된다.
+
+**비표준 케이스 → 수동 작성** (OptionalUser, Query 파라미터, SSE)
+
+수동 작성 시 반드시 `impl IntoResponse` 대신 `Result<Json<XxxResponse>, AppError>` 를 명시한다.
+XxxResponse는 `#[derive(Serialize)]` 구조체여야 한다 (`json!({...})` 매크로 금지).
+
+## 프론트엔드 새 API 함수 추가 패턴
+
+**모든 API 함수는 명명된 타입을 사용한다. 인라인 타입(`Promise<{ field: Type }>`) 금지.**
+
+```
+[ ] 1. src/features/{domain}/types.ts 에 {Action}Request / {Action}Response 인터페이스 추가
+[ ] 2. src/features/{domain}/api/index.ts 에 함수 추가:
+        export async function actionName(req: ActionRequest): Promise<ActionResponse>
+[ ] 3. npm run type-check && npm test 통과
+```
+
+### 타입 네이밍 규칙
+
+| 종류 | 패턴 | 예시 |
+|------|------|------|
+| 요청 body | `{Action}Request` | `CreateItemRequest` |
+| 응답 | `{Action}Response` | `CreateItemResponse` |
+| 도메인 모델 | 명사형 | `Item`, `User` |
+
+- `{Action}Request`, `{Action}Response` → `src/features/{domain}/types.ts` (예외 파일이므로 테스트 불필요)
+- BE `XxxResponse` 구조체와 1:1 대응 유지
+
+## 파일별 단위 테스트 요구사항
+
+- `backend/src/application/`, `backend/src/adapters/` 하위 .rs 파일: `#[cfg(test)] mod tests` 필수
+- `frontend/src/features/` 하위 .ts/.tsx 파일: 동일 경로 `.test.ts` 파일 필수
+- 예외: `mod.rs`, `main.rs`, `lib.rs`, `config.rs`, `error.rs`, `index.ts`, `types.ts`

.claude/commit-rules.md

@@ -0,0 +1,39 @@
+# 커밋 규칙
+
+## 타이밍
+
+- DoD (`.claude/dod.md`) 전체 충족 시점에 커밋
+- 논리적으로 완결된 단계마다 커밋 (한 작업을 여러 단계로 나눌 때)
+- WIP 상태 (컴파일/테스트 실패) 는 커밋하지 않는다
+
+## 메시지 형식
+
+```
+<type>: <subject>
+
+[optional body]
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+## Type 목록
+
+| type | 사용 상황 |
+|------|-----------|
+| `feat` | 새 기능 추가 |
+| `fix` | 버그 수정 |
+| `refactor` | 기능 변경 없는 코드 개선 |
+| `test` | 테스트 추가/수정 |
+| `docs` | 문서만 변경 |
+| `infra` | 인프라/배포 설정 변경 |
+| `chore` | 의존성, 설정, 빌드 스크립트 |
+
+## 범위
+
+- 백엔드 + 프론트엔드 + 문서가 하나의 기능을 위한 변경이면 **한 커밋**
+- 서로 독립적인 변경은 **별도 커밋**
+- `.env`, `.env.prod`, 시크릿 파일은 **절대 커밋 금지**
+
+## 푸시
+
+사용자가 명시적으로 요청할 때만 푸시한다.

.claude/dod.md

@@ -0,0 +1,34 @@
+# 작업 완료 기준 (Definition of Done)
+
+코드 수정이 포함된 모든 작업은 아래가 **모두** 충족돼야 "완료"다.
+
+## 체크리스트
+
+- [ ] **컴파일/타입**: `cargo check` (BE) / `npm run type-check` (FE) 통과
+- [ ] **테스트**: `cargo test` (BE) / `npm test -- --run` (FE) 전체 통과
+- [ ] **작업 로그**: `docs/works/YYYYMMDD-[작업명].md` 작성
+- [ ] **스펙 동기화**: 기능/설계 변경 시 `specification/` 해당 파일 업데이트
+- [ ] **커밋**: 작업 단위로 git commit (`.claude/commit-rules.md` 참조)
+
+## 검증 명령어
+
+```bash
+# 백엔드
+cd backend
+cargo check
+cargo test
+
+# 프론트엔드
+cd frontend
+npm run type-check
+npm test -- --run
+```
+
+## 서브에이전트 주의사항
+
+훅은 메인 Claude에만 적용된다. 서브에이전트에게 작업을 위임할 경우,
+메인이 서브에이전트 완료 후 직접 검증해야 한다:
+
+1. 해당 명령어 실행 (cargo check, npm run type-check, cargo test, npm test -- --run)
+2. `docs/works/YYYYMMDD-*.md` 오늘 날짜 파일 존재 확인
+3. 모두 통과 시에만 작업 완료 처리

.claude/hooks/block-git-push.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+COMMAND=$(jq -r '.tool_input.command // ""' 2>/dev/null)
+if echo "$COMMAND" | grep -qE '^\s*git push'; then
+  echo '{"continue": false, "stopReason": "git push는 사용자가 명시적으로 요청할 때만 실행합니다."}'
+  exit 0
+fi

.claude/hooks/cargo-check-on-edit.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+if ! echo "$FILE_PATH" | grep -qE '\.rs$'; then exit 0; fi
+if ! echo "$FILE_PATH" | grep -q 'backend/'; then exit 0; fi
+
+BACKEND_DIR="${PROJECT_ROOT}/backend"
+cd "$BACKEND_DIR" || exit 0
+
+CHECK_OUTPUT=$(cargo check 2>&1)
+if [ $? -ne 0 ]; then echo "$CHECK_OUTPUT" >&2; exit 2; fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# mod.rs, lib.rs, main.rs → 전체 단위 테스트
+if echo "$BASENAME" | grep -qE '^(mod|lib|main)\.rs$'; then
+  cargo nextest run --lib 2>&1; exit $?
+fi
+
+# tests/ 하위 → 해당 integration test만
+if echo "$FILE_PATH" | grep -qE 'backend/tests/[^/]+\.rs$'; then
+  TEST_NAME=$(basename "$FILE_PATH" .rs)
+  cargo nextest run --test "$TEST_NAME" 2>&1; exit $?
+fi
+
+# src/ 하위 → 모듈 경로로 변환하여 단위 테스트 필터
+if echo "$FILE_PATH" | grep -qE 'backend/src/'; then
+  MODULE=$(echo "$FILE_PATH" | sed 's|.*/backend/src/||' | sed 's|\.rs$||' | sed 's|/|::|g')
+  cargo nextest run --lib --filter-expr "test(~$MODULE)" 2>&1; exit $?
+fi

.claude/hooks/check-docs-on-stop.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then exit 0; fi
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+RUST_MARKER="${PROJECT_ROOT}/.claude/.pending-rust-check"
+SPEC_MARKER="${PROJECT_ROOT}/.claude/.pending-spec-check"
+MARKER="${PROJECT_ROOT}/.claude/.pending-doc-check"
+
+if [ -f "$RUST_MARKER" ]; then
+  BACKEND_DIR="${PROJECT_ROOT}/backend"
+  CHECK_OUTPUT=$(cd "$BACKEND_DIR" && cargo check 2>&1)
+  if [ $? -ne 0 ]; then
+    echo "{\"decision\": \"block\", \"reason\": \"cargo check 실패. 컴파일 오류를 수정한 후 완료하세요.\"}"
+    exit 0
+  fi
+fi
+
+if [ -f "$SPEC_MARKER" ]; then
+  echo "{\"decision\": \"block\", \"reason\": \"구조적 BE 파일이 변경됐는데 specification/ 업데이트가 없습니다.\"}"
+  exit 0
+fi
+
+if [ -f "$MARKER" ]; then
+  TODAY=$(date +%Y%m%d)
+  echo "{\"decision\": \"block\", \"reason\": \"소스 코드가 변경됐는데 작업 로그가 없습니다. docs/works/${TODAY}-[작업명].md 를 작성한 후 완료하세요.\"}"
+  exit 0
+fi

.claude/hooks/check-plan-on-edit.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+# docs/plans/ 작성 자체는 허용
+if echo "$FILE_PATH" | grep -qE 'docs/plans/'; then exit 0; fi
+
+# 소스 파일이 아니면 통과
+if ! echo "$FILE_PATH" | grep -qE '(backend/src/|frontend/src/|frontend/app/|backend/tests/|backend/migrations/)'; then
+  exit 0
+fi
+
+PLAN_MARKER="${PROJECT_ROOT}/.claude/.plan-exists"
+if [ -f "$PLAN_MARKER" ]; then exit 0; fi
+
+echo '{"decision": "block", "reason": "소스 코드를 수정하기 전에 작업 플랜을 먼저 작성하세요.\n\ndocs/plans/YYYYMMDD-[작업명].md 파일을 작성한 뒤 다시 시도하세요."}'

.claude/hooks/clear-marker-on-start.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+rm -f "${PROJECT_ROOT}/.claude/.pending-doc-check"
+rm -f "${PROJECT_ROOT}/.claude/.pending-rust-check"
+rm -f "${PROJECT_ROOT}/.claude/.pending-spec-check"
+rm -f "${PROJECT_ROOT}/.claude/.plan-exists"

.claude/hooks/coverage-check-fe.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+FE_DIR="${PROJECT_ROOT}/frontend"
+[ ! -d "$FE_DIR" ] && exit 0
+[ ! -d "$FE_DIR/node_modules" ] && exit 0
+
+cd "$FE_DIR" || exit 0
+npm test -- --run --coverage --silent 2>&1 | grep -E "^(All files|src/|Coverage|Threshold)" >&2
+exit ${PIPESTATUS[0]}

.claude/hooks/docker-cleanup-after-test.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+if ! echo "$COMMAND" | grep -qE 'cargo (test|nextest)'; then exit 0; fi
+if ! docker info > /dev/null 2>&1; then exit 0; fi
+
+TC_CONTAINERS=$(docker ps -aq --filter "label=org.testcontainers.managed-by=testcontainers" 2>/dev/null)
+if [ -n "$TC_CONTAINERS" ]; then
+  docker stop $TC_CONTAINERS > /dev/null 2>&1
+  docker rm $TC_CONTAINERS > /dev/null 2>&1
+fi
+docker system prune -f > /dev/null 2>&1