@yeongjaeyou/claude-code-config 0.1.2 → 0.2.1

package/.claude/agents/web-researcher.md

@@ -21,6 +21,73 @@ model: sonnet
 | **arXiv** | 학술 논문 | WebSearch |
 | **일반 웹** | 블로그, 튜토리얼 | WebSearch / Firecrawl |
 
+## 검색 품질 원칙 (필수)
+
+### 1. 현재 날짜 확인
+
+검색 시작 전 **반드시** 실행:
+```bash
+date +%Y-%m-%d
+```
+- 아래 예시의 연도(2024 등)는 참고용임
+- 실제 검색 시 **위에서 확인한 현재 연도** 사용
+
+### 2. 키워드 vs 시맨틱 검색 이해
+
+| 유형 | 특징 | 적합한 경우 |
+|------|------|-------------|
+| **키워드 검색** | 정확한 단어 매칭 | 에러 메시지, 함수명, 모델명 |
+| **시맨틱 검색** | 의미/의도 기반 | 개념 질문, 방법론, 비교 분석 |
+
+**적용:**
+- 정확한 용어가 있으면 키워드 검색 (`"Qwen2VL"`, `"RuntimeError"`)
+- 개념/방법을 찾으면 시맨틱하게 다양한 표현으로 검색
+
+### 3. Long-tail Keywords 적용
+
+아래 예시의 Short-tail 키워드를 그대로 쓰지 말고, **구체적인 Long-tail로 확장**:
+
+| Short-tail (예시 그대로) | Long-tail (실제 검색 시) |
+|--------------------------|--------------------------|
+| `object detection` | `best lightweight object detection model for edge deployment {현재연도}` |
+| `pytorch serving` | `how to deploy pytorch model with TorchServe in production` |
+| `gradio app` | `gradio demo with image upload real-time inference example` |
+
+**확장 방법:**
+- 목적 추가: "for production", "for beginners", "step by step"
+- 조건 추가: 언어, 프레임워크, 연도, 환경
+- 의도 명시: "how to", "best practices", "comparison", "vs"
+
+### 4. Multi-Query Generation
+
+단일 쿼리 대신 **3-5개 변형 쿼리**로 검색:
+
+```
+원본: "pytorch model serving"
+
+변형 1 (방법): "how to deploy pytorch model in production {현재연도}"
+변형 2 (비교): "pytorch vs tensorflow model serving comparison"
+변형 3 (구체): "TorchServe custom handler tutorial example"
+변형 4 (최적화): "pytorch model inference optimization GPU memory"
+변형 5 (사례): "pytorch model deployment kubernetes docker best practices"
+```
+
+**변형 관점:**
+- 동의어/유사어
+- 문제 해결 vs 개념 설명
+- 특정 도구/프레임워크명
+- 비교 분석
+- 베스트 프랙티스/사례
+
+### 5. 검색 전 체크리스트
+
+- [ ] `date` 명령으로 현재 날짜 확인
+- [ ] 예시 키워드를 Long-tail로 확장
+- [ ] 필요시 3-5개 Multi-Query 생성
+- [ ] 키워드/시맨틱 중 적합한 방식 선택
+
+---
+
 ## 리서치 워크플로우
 
 ### Phase 1: 계획 수립

package/.claude/commands/gh/decompose-issue.md

@@ -13,6 +13,11 @@
 8. 깃허브에 마일스톤과 이슈를 생성할지 묻기: AskUserQuestion 도구로 사용자가 결정하도록 요청하기.
    - 마일스톤 생성: `gh api repos/:owner/:repo/milestones -f title="마일스톤명" -f description="설명"`
    - 이슈 생성 시 `--milestone` 옵션으로 할당
+9. **GitHub Project에 이슈 추가 (선택)**
+   - `gh project list --owner <owner> --format json`으로 프로젝트 존재 여부 확인
+   - 프로젝트가 없으면: "프로젝트가 없습니다. `/gh:init-project`로 생성할 수 있습니다." 안내 후 스킵
+   - 프로젝트가 있으면: AskUserQuestion으로 추가 여부 질문
+   - 추가 원하면: 각 이슈에 대해 `gh project item-add <project-number> --owner <owner> --url <issue-url>`
 
 ## 마일스톤 description 작성 가이드
 

package/.claude/commands/gh/init-project.md

@@ -0,0 +1,88 @@
+---
+description: GitHub Project 보드 초기화 및 설정
+---
+
+# GitHub Project 초기화
+
+GitHub Project 보드를 생성하고 기본 필드를 설정합니다. `@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+## 사전 요구사항
+
+`gh` CLI에 project 스코프가 필요합니다. 없으면 다음 명령어로 추가:
+```bash
+gh auth refresh -s project --hostname github.com
+```
+
+## 아규먼트
+
+- 프로젝트 이름 (선택): 없으면 저장소 이름을 기본값으로 사용
+
+## 작업 순서
+
+1. **사전 확인**
+   - `gh auth status`로 project 스코프 확인
+   - 없으면 사용자에게 `gh auth refresh -s project --hostname github.com` 실행 안내
+   - `gh repo view --json nameWithOwner,owner -q ".owner.login"`로 owner 확인
+
+2. **기존 프로젝트 확인**
+   - `gh project list --owner <owner> --format json`으로 기존 프로젝트 목록 확인
+   - 동일한 이름의 프로젝트가 있으면 AskUserQuestion으로 처리 방법 질문:
+     - 기존 프로젝트 사용
+     - 새 프로젝트 생성 (다른 이름으로)
+     - 작업 취소
+
+3. **프로젝트 생성**
+   - `gh project create --owner <owner> --title "<프로젝트명>" --format json`
+   - 생성된 프로젝트 번호(number) 저장
+
+4. **Status 필드 확인**
+   - `gh project field-list <project-number> --owner <owner> --format json`으로 필드 확인
+   - GitHub Project는 기본적으로 Status 필드 제공 (Todo, In Progress, Done)
+   - 기본 필드가 있으면 그대로 사용
+
+5. **Priority 필드 생성 (선택)**
+   - AskUserQuestion으로 Priority 필드 생성 여부 질문
+   - 원하면 생성:
+     ```bash
+     gh project field-create <project-number> --owner <owner> \
+       --name "Priority" \
+       --data-type "SINGLE_SELECT" \
+       --single-select-options "High,Medium,Low"
+     ```
+
+6. **저장소에 프로젝트 링크**
+   - `gh repo view --json name -q .name`로 현재 저장소 이름 확인
+   - `gh project link <project-number> --owner <owner> --repo <repo>`로 연결
+   - 주의: `--repo`에는 저장소 이름만 지정 (owner/repo 형식 아님)
+
+7. **결과 출력**
+   - 생성된 프로젝트 정보 요약
+   - 웹에서 확인할 수 있는 URL 제공: `gh project view <project-number> --owner <owner> --web`
+
+## 출력 예시
+
+```
+GitHub Project 초기화 완료!
+
+프로젝트: my-project
+번호: 5
+URL: https://github.com/users/<username>/projects/5
+
+기본 필드:
+- Status: Todo, In Progress, Done
+- Priority: High, Medium, Low (선택적으로 추가됨)
+
+연결된 저장소: owner/repo
+
+다음 단계:
+- 이슈 추가: gh project item-add 5 --owner <owner> --url <issue-url>
+- 보드 확인: gh project view 5 --owner <owner> --web
+```
+
+## 작업 지침
+
+- 한글로 답변
+- 코드나 문서 작성 시 이모지 사용 금지
+- 오류 발생 시 명확한 해결 방법 제시
+- 프로젝트 번호는 이후 명령어에서 사용되므로 사용자에게 안내
+- `@me`는 일부 명령어에서 동작하지 않으므로 실제 owner를 사용

package/.claude/commands/gh/post-merge.md

@@ -35,7 +35,17 @@ PR이 머지된 후 브랜치 정리와 CLAUDE.md 업데이트를 수행합니
    - AskUserQuestion으로 로컬 브랜치 삭제 여부 질문
    - 삭제 원하면: `git branch -d <headRefName>`
 
-5. **CLAUDE.md 분석 및 업데이트**
+5. **GitHub Project 상태 업데이트 (선택)**
+   - PR body에서 관련 이슈 번호 파악: `Closes #N`, `Fixes #N`, `Resolves #N` 패턴 검색
+   - `gh project list --owner <owner> --format json`으로 프로젝트 확인
+   - 프로젝트가 없으면 스킵 (경고 없이 진행)
+   - 프로젝트가 있으면:
+     - `gh project item-list`로 해당 이슈의 item-id 확인
+     - `gh project field-list`로 Status 필드 ID와 "Done" 옵션 ID 획득
+     - `gh project item-edit`로 Status를 "Done"으로 변경
+     - 이슈가 프로젝트에 없거나 Status 필드가 없으면 스킵
+
+6. **CLAUDE.md 분석 및 업데이트**
    - CLAUDE.md 존재 여부 확인
      - 없으면: AskUserQuestion으로 생성 여부 또는 스킵 여부 질문
    - 기존 내용 분석:
@@ -48,7 +58,7 @@ PR이 머지된 후 브랜치 정리와 CLAUDE.md 업데이트를 수행합니
      - **수정 대상**: 오래되거나 부정확한 정보
    - AskUserQuestion으로 제안 내용 확인 후 적용
 
-6. **변경사항 커밋 (선택)**
+7. **변경사항 커밋 (선택)**
    - CLAUDE.md가 변경되었으면 AskUserQuestion으로 커밋 여부 질문
    - 커밋 원하면: Conventional Commits 형식으로 커밋
 

package/.claude/commands/gh/resolve-issue.md

@@ -13,20 +13,33 @@
 2. **브랜치 생성**: `main` 또는 `master` 브랜치에서 `issue-$ISSUE_NUMBER` 형태로 새 브랜치를 생성하고 체크아웃합니다.
    - **서브모듈 초기화**: Worktree 사용 시 `git submodule update --init --recursive` 실행 필요
 
-3. **코드베이스 분석**: 이슈 해결에 필요한 관련 파일과 구조를 파악하기 위해 서브에이전트를 활용하여 코드베이스를 병렬로 분석합니다.
-
-4. **해결 계획 수립**: 분석 결과를 바탕으로 구체적인 해결 방안을 계획하고 작업 단계를 정의합니다.
-
-5. **이슈 해결**: 서브에이전트를 생성하여 계획에 따라 코드를 수정하고 기능을 구현합니다.
+3. **GitHub Project 상태 업데이트 (선택)**
+   - `gh project list --owner <owner> --format json`으로 프로젝트 확인
+   - 프로젝트가 없으면 스킵 (경고 없이 진행)
+   - 프로젝트가 있으면:
+     - `gh project item-list <project-number> --owner <owner> --format json`으로 이슈가 프로젝트에 있는지 확인
+     - 없으면 `gh project item-add`로 추가
+     - `gh project field-list <project-number> --owner <owner> --format json`으로 Status 필드 ID와 "In Progress" 옵션 ID 획득
+     - Status 필드를 "In Progress"로 변경:
+       ```bash
+       gh project item-edit --project-id <project-id> --id <item-id> --field-id <status-field-id> --single-select-option-id <in-progress-option-id>
+       ```
+     - Status 필드가 없으면 스킵
+
+4. **코드베이스 분석**: 이슈 해결에 필요한 관련 파일과 구조를 파악하기 위해 서브에이전트를 활용하여 코드베이스를 병렬로 분석합니다.
+
+5. **해결 계획 수립**: 분석 결과를 바탕으로 구체적인 해결 방안을 계획하고 작업 단계를 정의합니다.
+
+6. **이슈 해결**: 서브에이전트를 생성하여 계획에 따라 코드를 수정하고 기능을 구현합니다.
    - **실행 검증 필수**: Python 스크립트, 실행 파일, 또는 동작 가능한 코드의 경우 반드시 실제 실행하여 정상 동작을 확인합니다. 단순히 파일 존재나 이전 결과만으로 판단하지 않습니다.
 
-6. **테스트 작성**: 파일별로 독립적인 서브에이전트를 생성하여 병렬로 단위 테스트를 작성하고 80% 이상의 커버리지를 확보합니다.
+7. **테스트 작성**: 파일별로 독립적인 서브에이전트를 생성하여 병렬로 단위 테스트를 작성하고 80% 이상의 커버리지를 확보합니다.
 
-7. **검증**: 테스트 실행, 린트 검사, 빌드 확인을 각각 독립적인 서브에이전트로 병렬 실행하여 코드 품질을 검증합니다.
+8. **검증**: 테스트 실행, 린트 검사, 빌드 확인을 각각 독립적인 서브에이전트로 병렬 실행하여 코드 품질을 검증합니다.
 
-8. **PR 생성**: 해결된 이슈에 대한 풀 리퀘스트를 생성합니다.
+9. **PR 생성**: 해결된 이슈에 대한 풀 리퀘스트를 생성합니다.
 
-9. **이슈 체크박스 업데이트**: 해당 이슈의 체크박스 항목들을 완료된 것으로 체크하여 업데이트합니다.
+10. **이슈 체크박스 업데이트**: 해당 이슈의 체크박스 항목들을 완료된 것으로 체크하여 업데이트합니다.
 
 ## 작업 지침
 - 불명확한 요구사항이나 구현 방향이 여러 가지일 경우 AskUserQuestion 도구로 사용자에게 확인

package/.claude/commands/tm/convert-prd.md

@@ -0,0 +1,127 @@
+# PRD 초안 -> TaskMaster PRD 변환
+
+초안 파일을 TaskMaster PRD 포맷으로 변환합니다.
+
+**템플릿:** `.claude/guideline/tm/prd-guide.md` 복사해서 초안 작성
+
+**원칙:**
+- 원본 내용 유지 (임의로 늘리거나 줄이지 않음)
+- 한글로 작성
+- `.taskmaster/templates/example_prd.txt` 포맷 준수
+
+---
+
+## 아규먼트
+
+`$ARGUMENTS`로 초안 파일 경로를 받습니다:
+- 예: `/tm:convert-prd .taskmaster/docs/my-idea.md`
+- 없으면 AskUserQuestion으로 경로 입력 요청
+
+---
+
+## 작업 순서
+
+### 1. 초안 읽기
+
+```bash
+cat $ARGUMENTS
+```
+
+파일이 없거나 내용이 비어있으면 작성 요청.
+
+### 2. 타겟 포맷 확인
+
+`.taskmaster/templates/example_prd.txt` 구조:
+
+```
+<context>
+# Overview
+# Core Features
+# User Experience
+</context>
+
+<PRD>
+# Technical Architecture
+# Development Roadmap
+# Logical Dependency Chain
+# Risks and Mitigations
+# Appendix
+</PRD>
+```
+
+### 3. 변환
+
+초안 내용을 위 포맷에 맞게 재배치:
+
+| 초안 섹션 | PRD 섹션 |
+|----------|----------|
+| 뭘 만들고 싶은지 | Overview |
+| 주요 기능 | Core Features |
+| (UX 관련 내용) | User Experience |
+| 기술 스택 | Technical Architecture |
+| 만드는 순서 | Development Roadmap, Logical Dependency Chain |
+| 기타 (걱정) | Risks and Mitigations |
+| 기타 (참고) | Appendix |
+
+**변환 규칙:**
+- 원본에 없는 내용 추가 금지
+- 섹션 내용이 없으면 "[추후 작성]" 표시
+- 한글로 작성
+- Development Roadmap은 Phase 단위로 구분
+
+### 4. 결과 출력
+
+변환된 PRD 전체 출력.
+
+### 5. 저장
+
+AskUserQuestion으로 확인 후 저장:
+- 기본: `.taskmaster/docs/prd.md`
+- 다른 경로 가능
+
+### 6. 다음 단계 안내
+
+```
+[변환 완료]
+
+다음 단계:
+task-master parse-prd .taskmaster/docs/prd.md
+```
+
+---
+
+## 출력 포맷
+
+```markdown
+<context>
+# Overview
+[뭘 만들고 싶은지 내용]
+
+# Core Features
+[주요 기능 내용]
+
+# User Experience
+[UX 관련 내용 또는 추후 작성]
+</context>
+
+<PRD>
+# Technical Architecture
+[기술 스택 내용]
+
+# Development Roadmap
+## Phase 1: [이름]
+- [기능]
+
+## Phase 2: [이름]
+- [기능]
+
+# Logical Dependency Chain
+[만드는 순서 기반 의존성]
+
+# Risks and Mitigations
+[걱정되는 점]
+
+# Appendix
+[참고사항]
+</PRD>
+```

package/.claude/commands/tm/post-merge.md

@@ -0,0 +1,194 @@
+# PR 머지 후 정리 (TaskMaster 연동)
+
+PR이 머지된 후 브랜치 정리, TaskMaster 상태 업데이트, CLAUDE.md 업데이트를 수행합니다.
+
+**중요 - ID 구분:**
+- **GitHub PR/Issue**: `#1`, `#2` (GitHub 번호)
+- **TaskMaster Task**: `task 1`, `task 1.1` (tasks.json 기준)
+
+`@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+---
+
+## 아규먼트
+
+- PR 번호 (선택): 없으면 대화 맥락에서 파악하거나 최근 머지된 PR 목록에서 선택 요청
+
+---
+
+## 작업 순서
+
+### 1. PR 정보 확인
+
+```bash
+# 아규먼트로 PR 번호가 주어지면 해당 PR 사용
+# 없으면 최근 머지 PR 목록 표시
+gh pr list --state merged --limit 5
+
+# PR 상세 정보 확인
+gh pr view <PR번호> --json number,title,baseRefName,headRefName,body,state
+```
+
+**확인 사항:**
+- `state`가 `MERGED`인지 확인
+- PR 본문에서 `Task Master 참조: task N` 추출
+
+### 2. TaskMaster Task ID 추출
+
+PR 본문 또는 연결된 Issue에서 TaskMaster ID 파악:
+
+```bash
+# PR 본문에서 추출
+gh pr view <PR번호> --json body | grep -o "Task Master 참조: task [0-9.]*"
+
+# 또는 연결된 Issue에서 추출
+gh pr view <PR번호> --json closedIssues
+```
+
+**추출 결과 예시:**
+```
+Task Master 참조: task 1
+→ TaskMaster Task ID: 1
+→ 관련 Subtasks: 1.1, 1.2, 1.3 (있는 경우)
+```
+
+### 3. TaskMaster 상태 업데이트
+
+```bash
+# 메인 태스크 상태 확인
+task-master show <TASK_ID>
+
+# 모든 subtask가 done인지 확인
+# subtask가 있고 모두 완료되었다면:
+task-master set-status --id=<TASK_ID> --status=done
+
+# subtask가 있고 일부만 완료된 경우:
+# → 메인 태스크는 in-progress 유지
+# → 완료된 subtask만 done 처리
+```
+
+**상태 업데이트 규칙:**
+
+| 상황 | 메인 태스크 상태 | Subtask 상태 |
+|------|------------------|--------------|
+| PR 머지 완료, subtask 없음 | done | N/A |
+| PR 머지 완료, 모든 subtask 완료 | done | 모두 done |
+| PR 머지 완료, 일부 subtask 남음 | in-progress | 완료분만 done |
+
+### 4. 로컬 변경사항 확인
+
+```bash
+git status --porcelain
+```
+
+변경사항이 있으면 AskUserQuestion으로 처리 방법 질문:
+- **stash 후 진행**: `git stash push -m "post-merge: 임시 저장"`
+- **변경사항 버리기**: `git checkout -- . && git clean -fd`
+- **작업 중단**: 사용자가 직접 처리
+
+### 5. 베이스 브랜치로 이동
+
+```bash
+git fetch origin
+git checkout <baseRefName>  # 보통 main
+git pull origin <baseRefName>
+```
+
+### 6. 이슈 브랜치 정리 (선택)
+
+AskUserQuestion으로 로컬 브랜치 삭제 여부 질문:
+
+```bash
+# 삭제 원하면
+git branch -d <headRefName>  # 예: issue-1
+```
+
+### 7. 다음 태스크 확인
+
+```bash
+# TaskMaster에서 다음 작업 가능한 태스크 확인
+task-master next
+
+# 출력 예시:
+# Next task: Task 2 - 디자인 시스템 및 테마 구축
+# Dependencies satisfied: Task 1 (done)
+```
+
+### 8. CLAUDE.md 분석 및 업데이트
+
+**분석 대상:**
+- 해결된 Issue/Task 관련 임시 지침 (`#1`, `task 1` 언급)
+- 오래되거나 부정확한 정보
+- 새로 발견한 패턴/컨벤션
+
+**업데이트 제안 작성 후 사용자 확인:**
+- 삭제 대상: 해결된 이슈 관련 임시 메모
+- 추가 대상: 작업 중 발견한 새 패턴
+- 수정 대상: 변경된 정보
+
+### 9. 변경사항 커밋 (선택)
+
+CLAUDE.md가 변경되었으면 AskUserQuestion으로 커밋 여부 질문:
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: CLAUDE.md 업데이트 (task $TASK_ID 완료 반영)"
+git push origin main
+```
+
+---
+
+## 결과 보고
+
+```
+[PR 머지 후 정리 완료]
+
+PR 정보:
+- PR: #<PR번호>
+- 제목: <PR 제목>
+- 브랜치: <headRefName> → <baseRefName>
+
+TaskMaster 상태:
+- Task ID: task <N>
+- 상태: done
+- Subtasks: 모두 완료 (1.1, 1.2, 1.3)
+
+정리 작업:
+- [x] 로컬 브랜치 삭제: issue-<N>
+- [x] TaskMaster 상태 업데이트
+- [ ] CLAUDE.md 업데이트 (변경 없음)
+
+다음 작업:
+- task-master next → Task <M>
+- /tm:resolve-issue <M> 으로 시작
+```
+
+---
+
+## 작업 지침
+
+- 한글로 답변
+- 코드나 문서 작성 시 이모지 사용 금지
+- 불명확한 사항은 추측하지 말고 AskUserQuestion으로 질문
+- TaskMaster 상태 변경, 브랜치 삭제 등은 항상 사용자 확인 필요
+
+---
+
+## ID 참조 가이드
+
+```
+[이 커맨드에서 사용되는 ID들]
+
+GitHub:
+- PR 번호: #13, #14
+- Issue 번호: #1, #2 (PR과 동일 네임스페이스)
+- 브랜치: issue-1, issue-2
+
+TaskMaster:
+- 메인 태스크: task 1, task 2
+- Subtask: task 1.1, task 1.2
+
+연결:
+- PR 본문의 "Task Master 참조: task N"
+- PR 본문의 "Closes #N" (GitHub Issue 연결)
+```

package/.claude/commands/tm/resolve-issue.md

@@ -0,0 +1,267 @@
+# TaskMaster 기반 GitHub Issue 해결하기
+
+GitHub Issue를 TaskMaster subtask 단위로 체계적으로 해결하고 PR을 생성합니다.
+
+**중요**: 이 커맨드는 TaskMaster와 GitHub Issue를 연동합니다.
+- **GitHub Issue 번호**: `#1`, `#2` 형태 (GitHub에서 생성된 번호)
+- **TaskMaster Task ID**: `task 1`, `task 1.1` 형태 (tasks.json 기준)
+
+`@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+---
+
+## 아규먼트
+
+`$ARGUMENTS`로 다음 중 하나를 받습니다:
+- GitHub Issue 번호 (예: `1`, `#1`)
+- TaskMaster Task ID (예: `task 1`, `task:1`)
+
+---
+
+## 작업 순서
+
+### 1. 아규먼트 파싱 및 ID 매핑
+
+```
+입력값 분석:
+- "#1" 또는 "1" → GitHub Issue 번호로 해석
+- "task 1" 또는 "task:1" → TaskMaster Task ID로 해석
+```
+
+**GitHub Issue 번호인 경우:**
+
+```bash
+# 1단계: Issue 정보 가져오기
+gh issue view $ISSUE_NUMBER --json number,title,body,state
+
+# 2단계: 본문에서 TaskMaster Task ID 추출
+BODY=$(gh issue view $ISSUE_NUMBER --json body --jq '.body')
+echo "$BODY" | grep -oP "Task Master 참조: task \K[0-9]+"
+
+# 예상 출력: 1 (숫자만)
+```
+
+**추출 실패 시 (Task Master 참조가 없는 경우):**
+```
+→ Issue가 sync-to-github로 생성된 게 아닐 수 있음
+→ 사용자에게 TaskMaster Task ID 직접 입력 요청
+→ AskUserQuestion: "이 Issue에 해당하는 TaskMaster Task ID가 무엇인가요?"
+```
+
+**TaskMaster Task ID인 경우:**
+```bash
+# tasks.json에서 해당 태스크 확인
+task-master show $TASK_ID
+
+# 해당하는 GitHub Issue 찾기 (역방향 매핑)
+gh issue list --search "in:body \"Task Master 참조: task $TASK_ID\"" --json number,title
+```
+
+### 2. 태스크 정보 확인
+
+```bash
+# TaskMaster에서 태스크 상세 정보 확인
+task-master show $TASK_ID
+
+# 출력 예시:
+# Task 1: Next.js 15 프로젝트 초기 설정
+# Status: pending
+# Dependencies: none
+# Subtasks: (none)
+```
+
+**확인 사항:**
+- [ ] 태스크 상태가 `pending` 또는 `in-progress`인지
+- [ ] 의존성 태스크가 모두 완료되었는지 (`task-master show`로 dependencies 확인)
+
+### 3. Subtask 확장 (필요시)
+
+```bash
+# subtask가 없는 경우에만 실행
+task-master expand --id=$TASK_ID --research
+```
+
+**확장 후 확인:**
+```bash
+task-master show $TASK_ID
+# Subtasks:
+#   - 1.1: 프로젝트 생성 (pending)
+#   - 1.2: Shadcn/ui 초기화 (pending)
+#   - 1.3: 의존성 설치 (pending)
+#   ...
+```
+
+### 4. 브랜치 생성
+
+```bash
+# main 또는 master에서 새 브랜치 생성
+git checkout main && git pull origin main
+git checkout -b issue-$ISSUE_NUMBER
+```
+
+**브랜치 명명 규칙:**
+- `issue-1` (GitHub Issue #1 작업용)
+- `issue-1-subtask-1.2` (특정 subtask만 작업 시, 선택사항)
+
+### 5. Subtask 순차 처리
+
+**처리 순서 결정:**
+```bash
+# subtask 목록과 의존성 확인
+task-master show $TASK_ID
+```
+
+**각 subtask별 처리 루프:**
+
+```
+[Subtask 1.1 시작]
+1. task-master set-status --id=1.1 --status=in-progress
+2. subtask 내용에 따라 코드 구현
+3. 구현 완료 후 검증 (빌드, 린트, 테스트)
+4. task-master set-status --id=1.1 --status=done
+5. task-master update-subtask --id=1.1 --prompt="구현 완료: [간단한 설명]"
+
+[Subtask 1.2 시작]
+... 반복 ...
+```
+
+**중요 원칙:**
+- 한 번에 하나의 subtask만 `in-progress`
+- 의존성이 있는 subtask는 선행 subtask 완료 후 처리
+- 각 subtask 완료 시 즉시 상태 업데이트
+
+### 6. 메인 태스크 완료 처리
+
+모든 subtask가 `done` 상태가 되면:
+
+```bash
+# 메인 태스크 완료
+task-master set-status --id=$TASK_ID --status=done
+
+# 최종 확인
+task-master show $TASK_ID
+```
+
+### 7. 커밋 및 푸시
+
+```bash
+# 변경사항 확인
+git status
+git diff
+
+# 커밋 (태스크 정보 포함)
+git add .
+git commit -m "feat: [Task $TASK_ID] 태스크 제목
+
+- subtask 1.1: 완료 내용
+- subtask 1.2: 완료 내용
+...
+
+Task Master 참조: task $TASK_ID
+Closes #$ISSUE_NUMBER"
+
+# 푸시
+git push -u origin issue-$ISSUE_NUMBER
+```
+
+### 8. PR 생성
+
+```bash
+gh pr create \
+  --title "[Task $TASK_ID] 태스크 제목" \
+  --body "$(cat <<'EOF'
+## 개요
+GitHub Issue #$ISSUE_NUMBER 해결
+
+## TaskMaster 태스크 정보
+- **Task ID**: $TASK_ID
+- **Task 제목**: [태스크 제목]
+
+## 완료된 Subtask
+- [x] subtask 1.1: [설명]
+- [x] subtask 1.2: [설명]
+- [x] subtask 1.3: [설명]
+
+## 변경 사항
+- [주요 변경 내용 요약]
+
+## 테스트
+- [ ] 빌드 성공
+- [ ] 린트 통과
+- [ ] 기능 테스트 완료
+
+## 관련 이슈
+Closes #$ISSUE_NUMBER
+
+---
+Task Master 참조: task $TASK_ID
+EOF
+)"
+```
+
+### 9. GitHub Issue 업데이트
+
+```bash
+# Issue에 진행 상황 코멘트 추가
+gh issue comment $ISSUE_NUMBER --body "PR #[PR번호] 생성 완료. 코드리뷰 요청드립니다.
+
+**완료된 작업:**
+$(task-master show $TASK_ID | grep -A 100 'Subtasks:')"
+```
+
+---
+
+## ID 매핑 참조표
+
+| 구분 | 형식 | 예시 | 설명 |
+|------|------|------|------|
+| GitHub Issue | `#N` | `#1`, `#12` | GitHub에서 자동 부여 |
+| TaskMaster 메인 태스크 | `task N` | `task 1`, `task 12` | tasks.json의 id 필드 |
+| TaskMaster Subtask | `task N.M` | `task 1.1`, `task 1.2` | 메인태스크.서브태스크 |
+
+**매핑 규칙:**
+- `sync-to-github` 실행 시 Issue 본문에 `Task Master 참조: task N` 포함됨
+- 이를 통해 GitHub Issue ↔ TaskMaster Task 연결
+
+---
+
+## 주의사항
+
+1. **ID 혼동 주의**
+   - GitHub Issue `#1`과 TaskMaster `task 1`은 다를 수 있음
+   - 항상 Issue 본문의 "Task Master 참조" 확인
+
+2. **subtask 순서 준수**
+   - 의존성이 있는 subtask는 반드시 순서대로 처리
+   - `task-master show`로 dependencies 확인
+
+3. **상태 업데이트 즉시 수행**
+   - subtask 완료 즉시 `set-status --status=done`
+   - 진행 상황이 tasks.json에 실시간 반영되어야 함
+
+4. **커밋 메시지에 참조 포함**
+   - `Task Master 참조: task N` 포함
+   - `Closes #N` 또는 `Fixes #N` 포함
+
+---
+
+## 에러 처리
+
+**의존성 미완료:**
+```
+Error: Task 1의 의존성 task 0이 완료되지 않았습니다.
+→ 선행 태스크 먼저 완료 필요
+```
+
+**subtask expand 실패:**
+```
+Error: expand 실패
+→ task-master expand --id=$TASK_ID --force 시도
+```
+
+**빌드/테스트 실패:**
+```
+→ 해당 subtask를 in-progress로 유지
+→ 문제 해결 후 다시 진행
+→ task-master update-subtask --id=N.M --prompt="이슈: [설명]"
+```

package/.claude/commands/tm/sync-to-github.md

@@ -0,0 +1,333 @@
+# TaskMaster -> GitHub Issue 동기화
+
+TaskMaster의 tasks.json을 읽어 GitHub Issue와 Milestone을 자동 생성합니다.
+
+**중요 - ID 구분:**
+- **GitHub Issue**: `#1`, `#2` (GitHub 자동 부여, 순차적)
+- **TaskMaster Task ID**: `task 1`, `task 2` (tasks.json 기준)
+- **동기화 후**: Issue 본문에 `Task Master 참조: task N` 포함되어 매핑됨
+
+`@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+---
+
+## 구조 설계
+
+```
+GitHub                          TaskMaster
+──────                          ──────────
+Milestone: Phase 1 MVP    ←──   PRD Phase 1 (Task 1-4)
+├── Issue #1              ←──   task 1 (메인 태스크)
+├── Issue #2              ←──   task 2
+├── Issue #3              ←──   task 3
+└── Issue #4              ←──   task 4
+
+Milestone: Phase 2 Core   ←──   PRD Phase 2 (Task 5-7)
+├── Issue #5              ←──   task 5
+...
+```
+
+**원칙:**
+- **Milestone** = PRD Phase 단위 (4개)
+- **Issue** = 메인 태스크 단위 (12개)
+- **Subtask** = Issue 내 체크박스 + TaskMaster 내부 관리
+
+---
+
+## 작업 순서
+
+### 1. 사전 확인
+
+```bash
+# tasks.json 존재 확인
+ls .taskmaster/tasks/tasks.json
+
+# 저장소 라벨 확인
+gh label list
+
+# 기존 마일스톤 확인
+gh milestone list
+
+# 기존 Issue 확인 (번호 예측용)
+gh issue list --state all --limit 1 --json number
+# 예: [{"number": 5}] → 다음 Issue는 #6부터 시작
+
+# TaskMaster 관련 Issue 이미 있는지 확인
+gh issue list --search "in:body \"Task Master 참조\"" --state all --json number,title
+```
+
+**Issue 번호 예측:**
+```
+현재 최대 Issue 번호: #5
+→ task 1 = Issue #6
+→ task 2 = Issue #7
+→ ...
+→ task 12 = Issue #17
+
+(주의: PR도 같은 번호 풀 사용하므로 중간에 PR 생성되면 번호 밀림)
+```
+
+### 2. tasks.json 및 PRD 분석
+
+```bash
+# 태스크 목록 확인
+task-master list
+```
+
+**PRD Phase 매핑 (prd.md 참조):**
+
+| Phase | TaskMaster Task IDs | 설명 |
+|-------|---------------------|------|
+| Phase 1: MVP | task 1, 2, 3, 4 | 초기 설정, 디자인, 레이아웃, 인증 |
+| Phase 2: Core Features | task 5, 6, 7 | 대시보드, VLM, VLM-CoT |
+| Phase 3: UX Enhancement | task 8, 9, 10 | 애니메이션, 에러처리, 성능 |
+| Phase 4: Deploy | task 11, 12 | CORS, Docker |
+
+### 3. 변환 계획 수립 및 사용자 확인
+
+아래 형식으로 변환 계획을 출력하고 **반드시 사용자 확인** 요청:
+
+```
+[Milestone 생성 계획] (4개)
+- Phase 1: MVP (task 1-4 포함)
+- Phase 2: Core Features (task 5-7 포함)
+- Phase 3: UX Enhancement (task 8-10 포함)
+- Phase 4: Deploy (task 11-12 포함)
+
+[Issue 생성 계획] (12개)
+Phase 1: MVP 하위:
+  - Issue: [feature] task 1 - Next.js 15 프로젝트 초기 설정
+  - Issue: [feature] task 2 - 디자인 시스템 및 테마 구축
+  - Issue: [feature] task 3 - 공통 레이아웃 및 네비게이션 구현
+  - Issue: [feature] task 4 - 인증 시스템 및 보호된 라우트 구현
+Phase 2: Core Features 하위:
+  ...
+```
+
+### 4. Milestone 생성
+
+Phase 단위로 Milestone 생성:
+
+```bash
+# Phase 1
+gh api repos/:owner/:repo/milestones \
+  -f title="Phase 1: MVP" \
+  -f description="초기 설정, 디자인 시스템, 레이아웃, 인증 구현 (task 1-4)"
+
+# Phase 2
+gh api repos/:owner/:repo/milestones \
+  -f title="Phase 2: Core Features" \
+  -f description="대시보드, VLM 분석, VLM-CoT 분석 구현 (task 5-7)"
+
+# Phase 3, 4도 동일하게...
+```
+
+### 5. Issue 생성
+
+메인 Task를 Issue로 변환:
+
+#### 제목 형식
+`[타입] 간결한 작업 설명`
+
+#### 라벨 선택 (실제 저장소 라벨 사용)
+**주의**: `gh label list` 결과에서 실제 존재하는 라벨만 사용
+
+예시 (프로젝트에 따라 다름):
+- **타입**: `type: feature`, `type: enhancement`, `type: bug`, `type: refactor`
+- **영역**: `frontend`, `backend`, `api`, `ai`, `infrastructure`
+- **난이도**: `complexity: easy`, `complexity: medium`, `complexity: hard`
+
+#### 본문 템플릿
+
+**중요**: `Task Master 참조` 섹션은 반드시 포함되어야 함 (resolve-issue에서 매핑에 사용)
+
+```markdown
+## 목적
+[Task description에서 추출]
+
+## 작업 내용
+[details 필드를 체크박스로 변환]
+- [ ] 구체적 요구사항 1
+- [ ] 구체적 요구사항 2
+- [ ] 구체적 요구사항 3
+
+## 수정할 파일
+[details 필드에서 파일 경로 추출, 없으면 "구현 시 결정"]
+- `경로/파일명` - 변경 내용
+
+## 기술 상세
+[details 필드의 코드 예시나 상세 내용]
+
+## 완료 조건
+[testStrategy 필드에서 추출]
+- [ ] 테스트 조건 1
+- [ ] 테스트 조건 2
+
+## 의존성
+[dependencies 필드 → GitHub Issue 번호로 변환]
+- 선행 작업: #N (task M) 또는 "없음"
+
+## 참고 자료 (선택사항)
+[관련 PR이나 문서가 있으면 추가, 없으면 섹션 생략]
+- 관련 PR: #N - 설명
+- 문서: [링크]
+
+---
+**Task Master 참조**: task [TASK_ID]
+```
+
+**예시 (task 1의 경우):**
+```markdown
+## 목적
+frontend/ 디렉토리에 Next.js 15 App Router 기반 프로젝트를 생성하고 핵심 의존성을 설정합니다.
+
+## 작업 내용
+- [ ] create-next-app으로 프로젝트 생성
+- [ ] Shadcn/ui 초기화
+- [ ] 필수 의존성 설치 (next-themes, framer-motion 등)
+- [ ] Pretendard 폰트 설정
+- [ ] tailwind.config.ts 커스터마이징
+- [ ] ESLint/Prettier 설정
+
+## 수정할 파일
+- `frontend/` - 새 디렉토리 생성
+- `frontend/tailwind.config.ts` - 커스텀 설정
+- `frontend/app/layout.tsx` - Pretendard 폰트 설정
+
+## 완료 조건
+- [ ] npm run dev 정상 구동
+- [ ] npm run build 성공
+- [ ] localhost:3000 접속 확인
+
+## 의존성
+- 없음
+
+---
+**Task Master 참조**: task 1
+```
+
+#### Issue 생성 명령어
+```bash
+gh issue create \
+  --title "[타입] 제목" \
+  --body "본문 내용" \
+  --label "라벨1,라벨2" \
+  --milestone "마일스톤명"
+```
+
+### 6. 의존성 연결 및 ID 매핑 기록
+
+**Issue 생성 순서**: task 1부터 순서대로 생성하면 Issue 번호도 순차적
+
+| TaskMaster ID | GitHub Issue | 제목 |
+|---------------|--------------|------|
+| task 1 | #1 | Next.js 15 프로젝트 초기 설정 |
+| task 2 | #2 | 디자인 시스템 및 테마 구축 |
+| ... | ... | ... |
+
+**의존성 변환:**
+- task 2의 dependencies: [1] → Issue #2 본문에 "선행 작업: #1 (task 1)"
+
+### 7. 결과 보고 및 매핑 테이블 출력
+
+**중요**: 실제 생성된 Issue 번호로 매핑 테이블 작성 (사전 확인에서 예측한 번호 기반)
+
+```
+[동기화 완료]
+
+Milestones (4개):
+- Phase 1: MVP
+- Phase 2: Core Features
+- Phase 3: UX Enhancement
+- Phase 4: Deploy
+
+Issues (12개):
+| GitHub Issue | TaskMaster | 제목 | Milestone |
+|--------------|------------|------|-----------|
+| #N | task 1 | Next.js 15 프로젝트 초기 설정 | Phase 1: MVP |
+| #N+1 | task 2 | 디자인 시스템 및 테마 구축 | Phase 1: MVP |
+| #N+2 | task 3 | 공통 레이아웃 및 네비게이션 | Phase 1: MVP |
+| #N+3 | task 4 | 인증 시스템 구현 | Phase 1: MVP |
+| #N+4 | task 5 | 대시보드 홈 구현 | Phase 2: Core |
+| ... | ... | ... | ... |
+
+(N = 기존 최대 Issue/PR 번호 + 1)
+```
+
+**생성 후 검증:**
+```bash
+# 실제 생성된 Issue 확인
+gh issue list --state open --json number,title --limit 20
+
+# 매핑 확인
+gh issue view <번호> --json body | grep "Task Master 참조"
+```
+
+**다음 단계 안내:**
+```
+다음 단계: /tm:resolve-issue <GitHub Issue 번호> 또는 /tm:resolve-issue task 1
+```
+
+---
+
+## 옵션 처리
+
+### 아규먼트
+- ARGUMENTS 비어있음: 전체 Task 동기화 (12개)
+- ARGUMENTS가 Phase 번호: 해당 Phase만 (예: phase1, 1)
+- ARGUMENTS가 Task ID: 해당 Task만 (예: task 1, 1,2,3)
+
+### 상태 필터
+- pending, in-progress 상태만 동기화
+- done, cancelled는 건너뜀
+
+---
+
+## 주의사항
+
+1. **중복 생성 방지**
+
+   동기화 전 반드시 기존 Issue 확인:
+
+   ```bash
+   # 전체 Issue 목록 확인
+   gh issue list --state all --limit 100
+
+   # 특정 task가 이미 Issue로 생성되었는지 검색
+   gh issue list --search "Task Master 참조: task 1" --state all
+
+   # 또는 본문 내용으로 검색
+   gh issue list --search "in:body \"Task Master 참조\"" --state all
+   ```
+
+   **이미 존재하면**: 해당 task는 건너뛰고 사용자에게 알림
+
+2. **사용자 확인 필수**
+   - Milestone/Issue 생성 전 반드시 계획 확인
+   - 라벨이 없으면 라벨 생성 여부 문의
+
+3. **ID 매핑 기록 유지**
+   - 동기화 완료 후 매핑 테이블 출력
+   - 이후 resolve-issue에서 참조
+
+---
+
+## ID 참조 가이드
+
+```
+[ID 형식 구분]
+
+GitHub:
+- Issue: #1, #2, #12 (# 접두어)
+- PR: #13, #14 (Issue와 동일 네임스페이스)
+- Milestone: "Phase 1: MVP" (이름으로 참조)
+
+TaskMaster:
+- 메인 태스크: task 1, task 2, task 12
+- Subtask: task 1.1, task 1.2, task 2.1
+- 상태: pending, in-progress, done
+
+매핑:
+- GitHub Issue #N ←→ TaskMaster task N (sync-to-github 실행 후)
+- Issue 본문의 "Task Master 참조: task N"으로 연결
+```

package/.claude/guideline/tm/prd-guide.md

@@ -0,0 +1,36 @@
+# PRD 초안 템플릿
+
+여기에 아이디어를 자유롭게 작성하세요.
+`/tm:convert-prd` 커맨드로 TaskMaster PRD 포맷으로 변환됩니다.
+
+---
+
+## 뭘 만들고 싶은지
+
+(프로젝트 목적, 해결하려는 문제)
+
+
+
+## 주요 기능
+
+(만들고 싶은 기능들 나열)
+
+
+
+## 기술 스택
+
+(사용할 기술, 프레임워크 등)
+
+
+
+## 만드는 순서
+
+(먼저 만들 것, 나중에 만들 것)
+
+
+
+## 기타
+
+(걱정되는 점, 참고사항 등)
+
+

package/.claude/skills/code-explorer/SKILL.md

@@ -16,6 +16,56 @@ To search and analyze code repositories across GitHub and Hugging Face platforms
 | **GitHub** | Repositories, Code | `gh` CLI |
 | **Hugging Face** | Models, Datasets, Spaces | `uvx hf` CLI + `huggingface_hub` API |
 
+## 검색 품질 원칙 (필수)
+
+### 1. 현재 날짜 확인
+
+```bash
+date +%Y-%m-%d
+```
+아래 예시의 연도는 참고용. 실제 검색 시 **현재 연도** 사용.
+
+### 2. Long-tail Keywords 적용
+
+예시의 Short-tail을 그대로 쓰지 말고 확장:
+
+| 예시 (참고용) | 실제 검색 (Long-tail) |
+|---------------|----------------------|
+| `"object detection"` | `"open vocabulary object detection pytorch inference {현재연도}"` |
+| `"gradio demo"` | `"gradio image segmentation interactive demo huggingface"` |
+| `"qwen vl"` | `"qwen2-vl vision language model zero-shot example code"` |
+
+### 3. Multi-Query 적용
+
+한 번에 찾기 어려우면 **2-3개 관점**으로 검색:
+
+```bash
+# 모델명 중심
+gh search repos "qwen2-vl" --sort stars
+
+# 기능 중심
+gh search repos "vision language open vocabulary detection" --sort stars
+
+# 구현 중심
+gh search repos "vl model gradio demo inference" --sort stars
+```
+
+### 4. 필터 활용
+
+```bash
+# 최신 + 품질 필터 (현재 연도 적용)
+gh search repos "keyword" stars:>50 pushed:>{현재연도-1}-01-01 --language python
+```
+
+### 5. 검색 전 체크리스트
+
+- [ ] 현재 날짜 확인했는가?
+- [ ] Short-tail을 Long-tail로 변환했는가?
+- [ ] 필요시 2-3개 변형 쿼리로 검색했는가?
+- [ ] 적절한 필터(언어, 스타, 날짜) 적용했는가?
+
+---
+
 ## Workflow Decision Tree
 
 ```

package/README.md

@@ -12,11 +12,15 @@ Claude Code CLI를 위한 커스텀 슬래시 커맨드, 에이전트, 스킬
 │   ├── commit-and-push.md       # Git 커밋 및 푸시 자동화
 │   ├── edit-notebook.md         # Jupyter Notebook 안전 편집
 │   ├── plan.md                  # 구현 계획 수립 (코드 작성 전)
-│   └── gh/
-│       ├── create-issue-label.md  # GitHub 이슈 라벨 생성
-│       ├── decompose-issue.md     # 큰 작업을 이슈로 분해
-│       ├── post-merge.md          # PR 머지 후 정리 작업
-│       └── resolve-issue.md       # GitHub 이슈 해결 워크플로우
+│   ├── gh/
+│   │   ├── create-issue-label.md  # GitHub 이슈 라벨 생성
+│   │   ├── decompose-issue.md     # 큰 작업을 이슈로 분해
+│   │   ├── post-merge.md          # PR 머지 후 정리 작업
+│   │   └── resolve-issue.md       # GitHub 이슈 해결 워크플로우
+│   └── tm/
+│       ├── post-merge.md          # TaskMaster 연동 PR 머지 후 정리
+│       ├── resolve-issue.md       # TaskMaster 기반 이슈 해결
+│       └── sync-to-github.md      # TaskMaster -> GitHub 동기화
 ├── agents/                      # 커스텀 에이전트
 │   ├── web-researcher.md        # 다중 플랫폼 웹 리서치
 │   ├── python-pro.md            # Python 전문가
@@ -54,6 +58,14 @@ Claude Code CLI를 위한 커스텀 슬래시 커맨드, 에이전트, 스킬
 | `/gh/post-merge` | PR 머지 후 브랜치 정리 및 CLAUDE.md 업데이트 |
 | `/gh/resolve-issue` | GitHub 이슈 번호를 받아 체계적으로 분석하고 해결 |
 
+### TaskMaster 연동 커맨드 (`/tm/`)
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/tm/sync-to-github` | TaskMaster tasks.json을 GitHub Issue/Milestone으로 동기화 |
+| `/tm/resolve-issue` | GitHub Issue를 TaskMaster subtask 단위로 체계적 해결 |
+| `/tm/post-merge` | PR 머지 후 TaskMaster 상태 업데이트 및 브랜치 정리 |
+
 ## 에이전트
 
 | 에이전트 | 설명 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeongjaeyou/claude-code-config",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Claude Code CLI custom commands, agents, and skills",
   "bin": {
     "claude-code-config": "./bin/cli.js"