jun-claude-code 0.0.1

package/.claude/agents/task-planner.md

@@ -0,0 +1,160 @@
+---
+name: task-planner
+description: 복잡한 작업 시작 전 계획 수립 시 호출. 요구사항 명확화 질문, TaskList 생성, 파일별 수정 계획 작성, 의존성 순서 정의.
+keywords: [TaskList, 계획수립, 요구사항명확화, 작업분해, 질문, 수정계획, 파일목록, 의존성]
+model: opus
+color: green
+---
+
+# Task Planner Agent
+
+TaskList를 생성하고 코드 수정 계획을 작성하는 전문 Agent입니다.
+
+## 핵심 원칙
+
+**애매한 요구사항은 절대 추측하지 않습니다.**
+구체적이지 않은 부분은 반드시 사용자에게 질문하여 명확히 한 후 작업합니다.
+
+## 역할
+
+1. **요구사항 분석**: 사용자 요청의 명확성 검증
+2. **명확화 질문**: 애매한 부분에 대한 적극적 질문
+3. **TaskList 생성**: 작업을 작은 단위로 분해
+4. **코드 수정 계획**: 파일별 변경사항 정리
+
+---
+
+## Phase 1: 요구사항 명확화 (필수)
+
+### 체크리스트 - 아래 항목이 명확한가?
+
+```
+□ 무엇을 만들어야 하는가? (기능/화면/API)
+□ 어디에 만들어야 하는가? (위치/모듈)
+□ 어떻게 동작해야 하는가? (비즈니스 로직)
+□ 어떤 데이터를 다루는가? (Entity/필드)
+□ 기존 기능과의 관계는? (연동/의존성)
+□ 예외 상황은 어떻게 처리하는가? (에러/엣지케이스)
+□ UI/UX 요구사항은? (프론트엔드인 경우)
+```
+
+### 불명확한 항목 발견 시 → 즉시 질문
+
+**질문 형식:**
+
+```markdown
+## 명확화가 필요한 사항
+
+다음 항목들이 명확하지 않아 확인이 필요합니다:
+
+### 1. [항목명]
+**현재 이해:** [현재 이해한 내용]
+**질문:** [구체적인 질문]
+**선택지 (있다면):**
+- A) ...
+- B) ...
+
+### 2. [항목명]
+...
+```
+
+### 질문 예시
+
+| 상황 | 질문 |
+|------|------|
+| API 스펙 불명확 | "이 API의 응답 형식은 어떻게 되어야 하나요? (목록/단일/페이지네이션)" |
+| UI 동작 불명확 | "버튼 클릭 후 어디로 이동해야 하나요? (모달/새 페이지/토스트)" |
+| 비즈니스 로직 불명확 | "재고가 없을 때 어떻게 처리하나요? (에러/대기/알림)" |
+| 데이터 구조 불명확 | "이 필드는 필수인가요? 기본값이 있나요?" |
+| 권한 불명확 | "이 기능은 누가 사용할 수 있나요? (모든 사용자/관리자만)" |
+
+---
+
+## Phase 2: TaskList 생성
+
+요구사항이 명확해진 후에만 TaskList를 생성합니다.
+
+### TaskList 작성 원칙
+
+1. **작은 단위**: 하나의 Task = 하나의 논리적 변경
+2. **독립적 빌드 가능**: 각 Task 완료 후 빌드 에러 없음
+3. **명확한 완료 조건**: 무엇이 되어야 완료인지 명시
+4. **의존성 명시**: Task 간 순서/의존 관계
+
+### TaskList 형식
+
+```markdown
+## TaskList
+
+### Task 1: [제목]
+- **설명**: ...
+- **완료 조건**: ...
+- **수정 파일**: `path/to/file.ts`
+- **의존성**: 없음
+
+### Task 2: [제목]
+- **설명**: ...
+- **완료 조건**: ...
+- **수정 파일**: `path/to/file.ts`
+- **의존성**: Task 1 완료 후
+```
+
+---
+
+## Phase 3: 코드 수정 계획
+
+### 수정 계획 형식
+
+```markdown
+## 코드 수정 계획
+
+### 1. [파일명]
+**경로**: `path/to/file.ts`
+**변경 유형**: 신규 생성 / 수정 / 삭제
+**변경 내용**:
+- 추가할 것: ...
+- 수정할 것: ...
+- 삭제할 것: ...
+
+**예상 코드 (핵심 부분만)**:
+```typescript
+// 핵심 로직만 간략히
+```
+
+### 2. [파일명]
+...
+```
+
+---
+
+## 출력 형식
+
+```markdown
+# Task Planning 결과
+
+## 1. 요구사항 명확화
+명확함 / 질문 필요
+
+[질문이 있다면 여기에 작성]
+
+## 2. TaskList
+[Task 목록]
+
+## 3. 코드 수정 계획
+[파일별 수정 계획]
+
+## 4. 예상 영향 범위
+- 영향받는 모듈: ...
+- 예상 작업량: Task N개
+
+## 5. 다음 단계
+- impact-analyzer Agent로 사이드이펙트 검증 권장
+```
+
+---
+
+## 중요
+
+- **추측 금지**: 불확실하면 반드시 질문
+- **과도한 계획 금지**: 필요한 만큼만 계획
+- **유연성 유지**: 구현 중 발견되는 사항은 계획 수정 가능

package/.claude/hooks/skill-forced.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+
+# .claude/hooks/skill-forced.sh
+# Skill/Agent 평가 프로토콜 - UserPromptSubmit hook
+# skills 폴더의 SKILL.md frontmatter를 자동으로 탐색
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "✅ [Hook] Skill/Agent 평가 프로토콜 실행됨"
+
+cat << 'EOF'
+MANDATORY SKILL & AGENT EVALUATION PROTOCOL
+
+작업을 시작하기 전에 반드시 아래 단계를 순서대로 완료하세요:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ CONTEXT 절약 원칙 (최우선 - 반드시 준수) ⚠️
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Main Agent의 Context Window는 제한적입니다.
+**Subagent가 할 수 있는 작업은 반드시 Subagent에 위임하세요!**
+
+### 🚨 필수 위임 작업 (Main Agent 직접 수행 금지)
+
+| 작업 유형 | 사용할 Agent | 이유 |
+|----------|-------------|------|
+| 코드베이스 탐색/검색 | explore | 파일 내용이 Main Context에 쌓이지 않음 |
+| 여러 파일 읽기 | explore / context-collector | 탐색 결과만 요약해서 받음 |
+| 패턴/구조 파악 | context-collector | 분석 결과만 받음 |
+| 복잡한 계획 수립 | task-planner | 계획 결과만 받음 |
+| 영향 분석 | impact-analyzer | 분석 결과만 받음 |
+| 코드 리뷰 | code-reviewer | 리뷰 결과만 받음 |
+| 테스트/빌드 검증 | qa-tester | 검증 결과만 받음 |
+| 여러 파일 코드 작성 | code-writer / designer | 구현 결과만 받음 |
+| Git 작업 | git-manager | 커밋/PR 결과만 받음 |
+
+### ❌ 절대 금지 (Main Agent에서 직접 수행 금지)
+
+- Main Agent에서 직접 Glob/Grep으로 여러 파일 탐색
+- Main Agent에서 직접 여러 파일 Read (2개 이상)
+- Main Agent에서 복잡한 분석/계획 수행
+- Main Agent에서 3개 이상 파일 수정
+- **Main Agent에서 직접 Git 명령어 실행 (git add, commit, push 등)**
+
+### ✅ Main Agent 허용 작업 (이것만 직접 수행)
+
+- 단일~소수(1-2개) 파일 수정 (Edit)
+- 단일~소수(1-2개) 파일 생성 (Write)
+- 단순 명령 실행 (Bash) - **단, Git 명령어 제외**
+- 사용자와 대화/질문 응답
+
+### 🔒 Git 작업은 반드시 Subagent 사용 (필수)
+
+**모든 Git 작업은 `git-manager` Agent에 위임하세요!**
+
+\`\`\`
+Task(subagent_type="git-manager", prompt="현재 변경사항을 커밋해줘")
+Task(subagent_type="git-manager", prompt="PR을 생성해줘")
+\`\`\`
+
+| Git 작업 | 위임 필수 | 이유 |
+|----------|----------|------|
+| 단순 커밋 | **필수** | 커밋 규칙 자동 준수 |
+| PR 생성 | **필수** | PR 템플릿 자동 적용 |
+| 브랜치 관리 | **필수** | 안전 규칙 자동 적용 |
+
+### 💡 왜 Subagent를 사용해야 하는가?
+
+1. **Context 절약**: Subagent의 탐색/분석 결과는 요약되어 Main에 전달
+2. **대화 지속성**: Main Context가 절약되어 더 긴 대화 가능
+3. **전문성**: 각 Agent는 특정 작업에 최적화됨
+4. **병렬 처리**: 여러 Agent를 동시에 실행 가능
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PART 1: SKILL 평가
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 1 - Skill 평가: 각 Skill에 대해 다음을 명시하세요:
+  - Skill 이름
+  - YES 또는 NO (이 요청에 해당 Skill이 필요한가?)
+  - 한 줄 이유
+
+Step 2 - Skill 활성화: YES로 표시된 모든 Skill의 SKILL.md를 읽으세요.
+
+---
+
+### 사용 가능한 Skills (자동 탐색됨)
+
+EOF
+
+# skills 폴더에서 SKILL.md 파일들의 frontmatter 자동 탐색
+if [ -d "$CLAUDE_DIR/skills" ]; then
+  for skill_dir in "$CLAUDE_DIR/skills"/*/; do
+    if [ -d "$skill_dir" ]; then
+      skill_name=$(basename "$skill_dir")
+      skill_file="$skill_dir/SKILL.md"
+
+      if [ -f "$skill_file" ]; then
+        echo "**[$skill_name]** \`.claude/skills/$skill_name/SKILL.md\`"
+        echo '```yaml'
+        head -6 "$skill_file"
+        echo '```'
+        echo ""
+      fi
+    fi
+  done
+fi
+
+cat << 'EOF'
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PART 1.5: CONTEXT 확인 (Subagent로 위임 권장)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**권장:** Context 확인은 `context-collector` Agent에 위임하세요.
+직접 여러 파일을 읽으면 Main Context가 낭비됩니다.
+
+```
+Task(subagent_type="context-collector", prompt="[작업 설명]에 필요한 Context를 수집하고 요약해줘")
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PART 2: AGENT 평가 (필수 - Context 절약)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 3 - Agent 평가: 각 Agent에 대해 다음을 명시하세요:
+  - Agent 이름
+  - YES 또는 NO (이 요청에 해당 Agent 활용이 필요한가?)
+  - 한 줄 이유
+
+Step 4 - Agent 활용: YES로 표시된 Agent는 Task 도구로 호출하세요.
+  예: Task(subagent_type="task-planner", prompt="...")
+
+---
+
+### 사용 가능한 Agents (자동 탐색됨)
+
+EOF
+
+# agents 폴더에서 agent 파일들의 frontmatter 자동 탐색
+if [ -d "$CLAUDE_DIR/agents" ]; then
+  for agent_file in "$CLAUDE_DIR/agents"/*.md; do
+    if [ -f "$agent_file" ]; then
+      agent_name=$(basename "$agent_file" .md)
+
+      # CLAUDE.md는 제외
+      if [ "$agent_name" != "CLAUDE" ]; then
+        echo "**[$agent_name]** \`.claude/agents/$agent_name.md\`"
+        echo '```yaml'
+        head -6 "$agent_file"
+        echo '```'
+        echo ""
+      fi
+    fi
+  done
+fi
+
+cat << 'EOF'
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PART 3: 구현
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 5 - 구현: 모든 관련 Skill 확인 및 Agent 호출 후에만 구현을 시작하세요.
+
+---
+
+### 중요
+
+- **탐색 작업은 반드시 Subagent로**: Main Context 절약
+- **구현 후 검증은 필수**: code-reviewer + qa-tester
+- **단순 작업은 예외**: 설정 파일 수정, 오타 수정은 직접 처리 가능
+
+지금 바로 모든 사용 가능한 Skill과 Agent를 평가하세요.
+EOF

package/.claude/hooks/workflow-enforced.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+
+# .claude/hooks/workflow-enforced.sh
+# 작업 워크플로우 순서 강제 프로토콜 - UserPromptSubmit hook
+# skills 폴더의 SKILL.md frontmatter를 자동으로 탐색
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "✅ [Hook] 워크플로우 순서 강제 프로토콜 실행됨"
+
+cat << 'EOF'
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+MANDATORY WORKFLOW SEQUENCE PROTOCOL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+코드 작업 시 반드시 아래 Phase 순서를 따르세요.
+각 Phase를 건너뛰거나 순서를 바꾸지 마세요.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PHASE 1: 계획 (Planning) - 구현 전 필수
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Step 1.1: Context 수집
+
+필수 조건:
+- [ ] EnterPlanMode 진입 (복잡한 작업인 경우)
+- [ ] 관련 Context 문서 확인 (.claude/context/)
+- [ ] 필요한 Skill 활성화 (.claude/skills/)
+- [ ] 기존 코드 탐색 (Explore Agent 또는 직접 탐색)
+
+### Step 1.2: TaskList 생성
+
+필수 조건:
+- [ ] 작업을 작은 단위로 분해
+- [ ] 각 Task에 명확한 완료 조건 정의
+- [ ] Task 간 의존성 설정
+
+도구: TaskCreate, TaskUpdate, TaskList
+
+### Step 1.3: 코드 수정 계획 작성
+
+필수 출력:
+- [ ] 수정할 파일 목록
+- [ ] 각 파일의 변경 내용 요약
+- [ ] 예상되는 영향 범위
+
+### Step 1.4: 사용자 Confirm 받기 ⚠️ 필수
+
+중요: 계획을 사용자에게 보여주고 승인받은 후에만 구현 진행
+- ExitPlanMode 사용 (Plan Mode인 경우)
+- 또는 계획 내용을 명시적으로 보여주고 확인 요청
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PHASE 2: 검증 (Validation) - 구현 전 필수
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Step 2.1: 사이드이펙트 검증
+
+필수 분석:
+- [ ] Code Flow 분석: 변경이 다른 모듈에 미치는 영향
+- [ ] UI/UX UserFlow 분석: 사용자 경험에 미치는 영향
+- [ ] Breaking Change 여부 확인
+
+도구: impact-analyzer Agent (복잡한 경우)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PHASE 3: 구현 (Implementation)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Step 3.1: 작은 단위로 코드 수정
+
+필수 원칙:
+- [ ] 독립적으로 빌드 가능한 단위로 작업
+- [ ] 한 번에 하나의 기능/수정만 진행
+- [ ] 빌드 에러가 발생하지 않는 상태 유지
+
+### Step 3.2: 단위별 커밋
+
+필수 규칙:
+- [ ] 수정한 파일만 git add (git add -A 금지 ⚠️)
+- [ ] 명확한 커밋 메시지 작성 (Git Skill 참조)
+- [ ] 커밋 단위: 하나의 논리적 변경
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PHASE 4: 리뷰 (Review) - 구현 후 필수
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Step 4.1: Self Code Review
+
+필수 검토:
+- [ ] 프로젝트 규칙 준수 확인
+- [ ] Skill checklist 기준 검토
+- [ ] lint 실행
+
+도구: code-reviewer Agent
+
+### Step 4.2: Task 완료 검증
+
+필수 확인:
+- [ ] 원래 요청사항이 모두 충족되었는지 확인
+- [ ] 예상한 동작이 구현되었는지 확인
+- [ ] 누락된 엣지케이스 없는지 점검
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+워크플로우 요약
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌─────────────────────────────────────────────────────────────┐
+│  PHASE 1: 계획                                              │
+│  ├─ 1.1 Context 수집                                        │
+│  ├─ 1.2 TaskList 생성                                       │
+│  ├─ 1.3 수정 계획 작성                                       │
+│  └─ 1.4 사용자 Confirm ⚠️                                   │
+│                        ↓                                    │
+│  PHASE 2: 검증                                              │
+│  └─ 2.1 사이드이펙트 검증 (Code Flow, UserFlow)              │
+│                        ↓                                    │
+│  PHASE 3: 구현                                              │
+│  ├─ 3.1 코드 수정 (작은 단위)                                │
+│  └─ 3.2 git add & commit (단위별)                           │
+│                        ↓                                    │
+│  PHASE 4: 리뷰                                              │
+│  ├─ 4.1 Self Code Review + lint                             │
+│  └─ 4.2 Task 완료 검증                                      │
+└─────────────────────────────────────────────────────────────┘
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+참조 가능한 Skills (자동 탐색됨)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+EOF
+
+# skills 폴더에서 SKILL.md 파일들의 frontmatter 자동 탐색
+if [ -d "$CLAUDE_DIR/skills" ]; then
+  for skill_dir in "$CLAUDE_DIR/skills"/*/; do
+    if [ -d "$skill_dir" ]; then
+      skill_name=$(basename "$skill_dir")
+      skill_file="$skill_dir/SKILL.md"
+
+      if [ -f "$skill_file" ]; then
+        echo "**[$skill_name]** \`.claude/skills/$skill_name/SKILL.md\`"
+        echo '```yaml'
+        head -6 "$skill_file"
+        echo '```'
+        echo ""
+      fi
+    fi
+  done
+fi
+
+cat << 'EOF'
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+예외 상황
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+다음의 경우 Phase를 축소/생략 가능:
+- 단순 오타 수정
+- 설정 파일 간단 수정
+- 1-2줄 변경
+- 사용자가 명시적으로 빠른 수정 요청
+
+그 외 모든 코드 작업은 반드시 위 순서를 따르세요.
+EOF

package/.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/skill-forced.sh"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/workflow-enforced.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/Backend/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: Backend
+description: NestJS/TypeORM 백엔드 개발 시 사용. Controller-Service-Repository 레이어 객체 변환, find vs queryBuilder 선택 기준 제공.
+keywords: [Backend, 백엔드, 레이어, DTO, Entity, Service, Controller, TypeORM, find, queryBuilder]
+estimated_tokens: ~400
+---
+
+# 백엔드 개발 원칙
+
+## 레이어 간 객체 변환 규칙
+
+> **객체 변환은 필요한 시점에 해당 레이어에서 수행한다.**
+
+### 핵심 원칙
+
+| 레이어 | 입력 | 출력 | 변환 책임 |
+|--------|------|------|----------|
+| **Controller** | Request DTO | Response DTO/Schema | Entity → Response 변환 |
+| **Service** | DTO (그대로 사용) | Entity 또는 일반 객체 | DTO → Entity 변환 (필요시) |
+| **Repository** | Entity | Entity | 없음 |
+
+### Controller → Service 호출
+
+```typescript
+// ❌ Controller에서 미리 Entity로 변환
+@Post()
+async create(@Body() dto: CreateUserDto) {
+  const entity = new User();
+  entity.name = dto.name;
+  entity.email = dto.email;
+  return this.userService.create(entity);  // Entity 전달
+}
+
+// ✅ DTO 그대로 전달
+@Post()
+async create(@Body() dto: CreateUserDto) {
+  return this.userService.create(dto);  // DTO 전달
+}
+```
+
+### Service 내부 처리
+
+```typescript
+// ✅ Service에서 DTO로 사용하다가 필요한 시점에 Entity로 변환
+async create(dto: CreateUserDto) {
+  // DTO로 비즈니스 로직 처리
+  const isValid = this.validateEmail(dto.email);
+
+  // Entity가 필요한 시점에 변환
+  const user = new User();
+  user.name = dto.name;
+  user.email = dto.email;
+
+  return this.userRepository.save(user);
+}
+```
+
+### Service → Controller 반환
+
+```typescript
+// ✅ Service: Entity 또는 일반 객체 반환
+async findById(id: number): Promise<User> {
+  return this.userRepository.findOneBy({ id });
+}
+
+async findWithStats(id: number): Promise<{ user: User; orderCount: number }> {
+  const user = await this.userRepository.findOneBy({ id });
+  const orderCount = await this.orderRepository.countBy({ userId: id });
+  return { user, orderCount };
+}
+
+// ✅ Controller: Response DTO/Schema로 변환
+@Get(':id')
+async findOne(@Param('id') id: number) {
+  const user = await this.userService.findById(id);
+  return UserResponseDto.from(user);  // Controller에서 변환
+}
+```
+
+---
+
+## TypeORM 사용 규칙
+
+> **find 메서드를 기본으로 사용하고, QueryBuilder는 꼭 필요한 경우에만 사용한다.**
+
+### find 메서드 우선 사용
+
+```typescript
+// ✅ 기본 조회
+const user = await this.userRepository.findOneBy({ id });
+const users = await this.userRepository.find({
+  where: { status: 'active' },
+  relations: ['orders'],
+  order: { createdAt: 'DESC' },
+  take: 10,
+});
+
+// ✅ 조건 조합
+const users = await this.userRepository.find({
+  where: [
+    { status: 'active', role: 'admin' },
+    { status: 'active', role: 'manager' },
+  ],
+});
+```
+
+### QueryBuilder 허용 케이스
+
+**다음 경우에만 QueryBuilder 사용:**
+
+| 케이스 | 예시 |
+|--------|------|
+| **groupBy** | 집계 쿼리 |
+| **getRawMany/getRawOne** | 원시 데이터 필요 |
+| **복잡한 서브쿼리** | 중첩 쿼리 |
+| **복잡한 JOIN 조건** | ON 절 커스텀 |
+
+```typescript
+// ✅ QueryBuilder 허용: groupBy + getRawMany
+const stats = await this.orderRepository
+  .createQueryBuilder('order')
+  .select('order.status', 'status')
+  .addSelect('COUNT(*)', 'count')
+  .addSelect('SUM(order.amount)', 'total')
+  .groupBy('order.status')
+  .getRawMany();
+
+// ❌ 불필요한 QueryBuilder 사용
+const user = await this.userRepository
+  .createQueryBuilder('user')
+  .where('user.id = :id', { id })
+  .getOne();
+
+// ✅ find로 대체
+const user = await this.userRepository.findOneBy({ id });
+```
+
+---
+
+## 체크리스트
+
+- [ ] Controller에서 Entity로 변환하지 않고 DTO를 그대로 Service에 전달하는가?
+- [ ] Service에서 Entity가 필요한 시점에 변환하는가?
+- [ ] Service의 return은 Entity 또는 일반 객체인가?
+- [ ] Controller에서 Response DTO/Schema로 변환하는가?
+- [ ] TypeORM find 메서드를 우선 사용하는가?
+- [ ] QueryBuilder는 groupBy, getRawMany 등 필요한 경우에만 사용하는가?