refactor: 코드 품질 개선 및 개발 환경 현대화

.claude/commands/commit.md

@@ -0,0 +1,36 @@
+# Commit
+
+변경사항을 분석하여 Conventional Commits 형식으로 커밋을 생성한다.
+
+## 절차
+
+1. `git status`와 `git diff`로 변경사항 확인
+2. 변경사항을 논리적 단위로 분리
+3. 각 단위별로 커밋 생성
+
+## 커밋 메시지 형식
+
+```
+{type}: {subject}
+
+{body}
+```
+
+### 타입
+
+- `feat` - 새로운 기능
+- `fix` - 버그 수정
+- `refactor` - 코드 리팩토링
+- `style` - 코드 포맷팅 (동작 변경 없음)
+- `docs` - 문서 변경
+- `test` - 테스트 추가/수정
+- `chore` - 빌드, 설정 변경
+- `perf` - 성능 개선
+
+### 규칙
+
+- 제목은 한국어, 50자 이내
+- 이모지 사용 금지
+- 한꺼번에 커밋하지 않고 작은 작업 단위로 분리
+- body는 선택사항이며, 필요시 "왜" 변경했는지 설명
+- 커밋 후 `git status`로 결과 확인

.claude/commands/create-pr.md

@@ -0,0 +1,46 @@
+# Create PR
+
+현재 브랜치의 변경사항으로 Pull Request를 생성한다.
+
+## 절차
+
+1. `git log main..HEAD --oneline`으로 커밋 이력 확인
+2. `git diff main...HEAD`로 전체 변경사항 파악
+3. PR 제목과 본문 작성
+4. `gh pr create`로 PR 생성
+
+## 브랜치 컨벤션
+
+```
+{type}/{description}
+```
+
+- `feat/` - 새 기능
+- `fix/` - 버그 수정
+- `refactor/` - 리팩토링
+- `chore/` - 설정/빌드
+- `docs/` - 문서
+
+예: `feat/timeline-page`, `fix/search-filter`
+
+## PR 형식
+
+```markdown
+## Summary
+
+- 변경사항 1~3줄 요약
+
+## Changes
+
+- 주요 변경 항목 나열
+
+## Test Plan
+
+- [ ] 검증 항목
+```
+
+## 규칙
+
+- PR 제목은 70자 이내
+- base 브랜치는 `main`
+- push 전 `pnpm lint && pnpm type:check && pnpm format:check` 확인

.claude/commands/self-review.md

@@ -0,0 +1,54 @@
+# Self Review
+
+현재 변경사항을 다각도로 리뷰한다.
+
+## 절차
+
+1. `git diff`로 변경사항 확인
+2. 아래 관점별로 리뷰 수행
+3. 발견된 이슈를 심각도별로 분류하여 보고
+
+## 리뷰 관점
+
+### Frontend Architecture
+
+- Server/Client Component 경계가 적절한가
+- feature 간 순환 의존이 없는가
+- `app/`에 비즈니스 로직이 들어가지 않았는가
+- import 경로가 `@/*` 절대 경로를 사용하는가 (상대 경로 `../`, `./` 사용 금지, barrel file `index.ts` 내부 re-export 제외)
+- barrel file(`index.ts`)을 경유하여 import하는가 (내부 파일 직접 접근 금지)
+
+### UX/UI
+
+- 로딩/빈/에러 상태가 모두 처리되었는가
+- 모바일 반응형이 적용되었는가
+- 시맨틱 HTML을 사용했는가
+- 접근성 속성이 적절한가
+
+### Code Quality
+
+- TypeScript strict mode 에러가 없는가
+- 미사용 변수/import가 없는가
+- `import type`이 적절히 사용되었는가
+- 불필요한 주석이 없는가
+
+### Security
+
+- 사용자 입력을 적절히 검증하는가
+- XSS 취약점이 없는가
+- 민감 정보가 클라이언트에 노출되지 않는가
+
+## 보고 형식
+
+```
+## 리뷰 결과
+
+### 심각 (즉시 수정)
+- ...
+
+### 권장 (개선 사항)
+- ...
+
+### 참고
+- ...
+```

.claude/hooks/mark-lint-needed.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# 파일 수정 시 플래그만 생성하고, 실제 lint는 나중에 한 번만 실행
+
+SESSION_ID=${CLAUDE_SESSION_ID:-default}
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+FLAG_FILE="${PROJECT_DIR}/.claude/.lint-needed-${SESSION_ID}"
+
+# 플래그 파일 생성 (lint 필요함을 표시)
+touch "$FLAG_FILE"
+
+# 조용히 종료 (사용자 경험 방해 안 함)
+exit 0

.claude/hooks/post-stop-lint.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# 대화 종료 시 실행: 누적된 lint 작업을 한 번에 실행
+# 성능 최적화: 여러 파일 수정 시에도 lint는 단 1회만 실행
+
+SESSION_ID=${CLAUDE_SESSION_ID:-default}
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+FLAG_FILE="${PROJECT_DIR}/.claude/.lint-needed-${SESSION_ID}"
+
+# 플래그 파일 확인
+if [ -f "$FLAG_FILE" ]; then
+  echo "🔍 [Deferred Linting] 파일 수정이 감지되었습니다. Lint & Format 실행 중..."
+
+  # 프로젝트 루트에서 실행
+  cd "$PROJECT_DIR" || exit 1
+
+  # Lint 자동 수정
+  pnpm lint:fix 2>/dev/null || echo "⚠️ lint:fix 스킵됨"
+
+  # Prettier 포맷팅
+  pnpm format 2>/dev/null || echo "⚠️ format 스킵됨"
+
+  # 플래그 파일 제거
+  rm "$FLAG_FILE"
+
+  echo "✅ Lint & Format 완료!"
+else
+  echo "✨ [Deferred Linting] 변경사항 없음. 스킵."
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://json.schemastore.org/claude-code-settings.json",
+	"hooks": {
+		"PostToolUse": [
+			{
+				"matcher": "Edit|Write",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/mark-lint-needed.sh",
+						"timeout": 5
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-stop-lint.sh",
+						"timeout": 120
+					}
+				]
+			}
+		]
+	}
+}

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: code-review
+description: Provides structured code review guidelines for TypeScript projects. Use when reviewing pull requests, analyzing code quality, or suggesting improvements.
+license: MIT
+---
+
+# Code Review Guidelines
+
+## Overview
+
+This skill provides structured guidelines for reviewing TypeScript code. Apply these standards when reviewing pull requests, analyzing code quality, or suggesting improvements.
+
+**Keywords**: code review, pull request, PR review, TypeScript, code quality, best practices, refactoring
+
+## Review Checklist
+
+### 1. Code Correctness
+
+**Before approving, verify:**
+
+- [ ] Logic is correct and handles edge cases
+- [ ] Error handling is appropriate
+- [ ] No obvious bugs or race conditions
+- [ ] Tests cover the changes adequately
+
+### 2. Code Quality
+
+**Check for:**
+
+- [ ] Clear, descriptive variable and function names
+- [ ] Functions do one thing well (single responsibility)
+- [ ] No excessive nesting (max 3 levels)
+- [ ] DRY - no unnecessary duplication
+- [ ] YAGNI - no speculative features
+
+### 3. TypeScript Specific
+
+**Ensure:**
+
+- [ ] Proper type annotations (avoid `any`)
+- [ ] Interfaces/types defined for complex objects
+- [ ] Generics used appropriately
+- [ ] Null/undefined handled safely
+- [ ] `strict` mode compatible
+
+### 4. Performance
+
+**Look for:**
+
+- [ ] Unnecessary re-renders (React)
+- [ ] Missing memoization for expensive operations
+- [ ] Inefficient loops or data structures
+- [ ] Memory leaks (event listeners, subscriptions)
+
+## Review Comments
+
+### Comment Format
+
+Use this format for review comments:
+
+```
+[severity]: brief description
+
+Why: explanation of the issue
+Suggestion: how to fix it (with code if helpful)
+```
+
+**Severity levels:**
+
+- `[critical]` - Must fix before merge
+- `[suggestion]` - Recommended improvement
+- `[nit]` - Minor style preference
+- `[question]` - Need clarification
+
+### Example Comments
+
+**Good comment:**
+
+```
+[suggestion]: Consider extracting this validation logic
+
+Why: This 15-line validation block is hard to test in isolation
+Suggestion: Move to a `validateUserInput(data)` function
+```
+
+**Bad comment:**
+
+```
+This is wrong, fix it.
+```
+
+## Common Issues
+
+### Anti-patterns to Flag
+
+1. **God functions** - Functions over 50 lines doing multiple things
+2. **Prop drilling** - Passing props through 3+ component levels
+3. **Magic numbers** - Unexplained literal values
+4. **Catch-all error handling** - `catch(e) { console.log(e) }`
+5. **Implicit any** - Missing type annotations on function parameters
+
+### Security Concerns
+
+Always flag:
+
+- SQL/NoSQL injection vulnerabilities
+- XSS opportunities (unsanitized user input in DOM)
+- Hardcoded secrets or API keys
+- Insecure randomness for security contexts
+- Missing input validation on API endpoints
+
+## Approval Guidelines
+
+### Approve When
+
+- All critical issues resolved
+- Tests pass
+- Code meets team standards
+- No security concerns
+
+### Request Changes When
+
+- Critical bugs found
+- Security vulnerabilities present
+- Missing required tests
+- Significant performance issues
+
+### Leave Comments When
+
+- Minor improvements possible
+- Design alternatives worth discussing
+- Documentation could be clearer