@yeongjaeyou/claude-code-config 0.1.0

package/.claude/commands/commit-and-push.md

@@ -0,0 +1,52 @@
+---
+description: Git 변경사항 분석 후 적절한 커밋 메시지로 커밋 및 푸시
+---
+
+# 커밋 & 푸시
+
+아규먼트로 받은 파일들만을 분석하여 적절한 커밋 메시지를 작성하고 커밋 후 푸시합니다.
+
+## 작업 순서
+
+1. **변경 분석**: 아규먼트로 받은 파일들만의 변경 내용이 어떤 목적인지 분석
+   - 새로운 기능 추가
+   - 버그 수정
+   - 리팩토링
+   - 문서 업데이트
+   - 스타일/포맷팅
+2. **커밋 메시지 작성**: Conventional Commits 형식으로 명확하게 작성
+4. **커밋 & 푸시**: `git add` → `git commit` → `git push`
+
+## 커밋 메시지 형식
+
+Conventional Commits 규칙 준수:
+
+```
+<type>: <subject>
+
+[optional body]
+```
+
+### Type 종류
+- `feat`: 새로운 기능 추가
+- `fix`: 버그 수정
+- `refactor`: 코드 리팩토링
+- `docs`: 문서 변경
+- `style`: 코드 포맷팅, 세미콜론 누락 등
+- `test`: 테스트 코드 추가/수정
+- `chore`: 빌드, 설정 파일 변경
+
+### Subject 작성 원칙
+- 명령형, 현재 시제 사용
+- 첫 글자 소문자
+- 마침표 없음
+- 50자 이내로 간결하게
+
+## 작성 원칙
+- **한글로 작성 및 답변**
+- **아규먼트로 전달된 파일 외의 파일은 분석하지 않음**
+- **명확성**: 무엇을, 왜 변경했는지 명확히 전달
+- **CLAUDE.md 준수**: `@CLAUDE.md`의 프로젝트 지침 확인
+- **단일 목적**: 하나의 커밋은 하나의 논리적 변경만 포함
+
+

package/.claude/commands/edit-notebook.md

@@ -0,0 +1,42 @@
+---
+description: Jupyter Notebook(.ipynb) 파일 안전 편집
+---
+
+# Notebook 편집
+
+Jupyter Notebook 파일을 올바른 도구로 안전하게 편집합니다.
+
+## 필수 규칙
+
+1. **도구 사용**: `NotebookEdit` 도구만 사용
+   - `Edit`, `Write`, `search_replace` 등 텍스트 편집 도구 사용 금지
+   - .ipynb는 JSON 구조이므로 전용 도구 필수
+
+2. **셀 삽입 순서**: 새 노트북 작성 시 순서 보장 필수
+   - **중요**: `cell_id` 미지정 시 항상 맨 앞에 삽입됨
+   - **방법 1 (권장)**: 이전 셀의 cell_id를 추적하여 순차 삽입
+     ```
+     첫 셀 삽입 → cell_id='abc123' 반환
+     두 번째 셀 삽입 시 cell_id='abc123' 지정 → 첫 셀 다음에 삽입
+     세 번째 셀 삽입 시 cell_id='def456' 지정 → 두 번째 셀 다음에 삽입
+     ```
+   - **방법 2**: 역순 삽입 (마지막 셀부터 첫 셀까지)
+   - **절대 금지**: cell_id 없이 순차 삽입 (역순 결과 발생)
+
+3. **source 형식**: NotebookEdit 사용 시 source가 string으로 저장될 수 있음
+   - **문제**: `"line1\\nline2"` (string) → Jupyter에서 `\n`이 그대로 표시됨
+   - **정상**: `["line1\n", "line2\n"]` (list of strings)
+   - **해결**: 새 노트북 생성 시 Python으로 직접 JSON 작성 권장
+
+4. **편집 후 검증**: 수정 후 반드시 확인
+   - JSON 구문 유효성 검증
+   - 셀 실행 순서 보존 확인 (Read로 첫 30줄 확인)
+   - 함수/임포트/의존성 누락 확인
+   - 명시적 지시가 없으면 셀 출력 보존
+
+## 처리 원칙
+
+- **전용 도구만 사용**: NotebookEdit 외 다른 편집 도구 절대 금지
+- **구조 보존**: 기존 셀 순서 및 출력 유지
+- **검증 필수**: 편집 후 즉시 변경사항 확인
+- **CLAUDE.md 준수**: 프로젝트 지침 엄수

package/.claude/commands/gh/create-issue-label.md

@@ -0,0 +1,29 @@
+## 이슈 라벨 생성하기
+
+프로젝트 구조를 분석하여 적절한 GitHub 이슈 라벨을 생성합니다. `@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+## 작업 순서
+1. 프로젝트 분석: `package.json`, `README.md`, 코드 구조 파악
+2. 기술 스택 확인: 사용된 프레임워크, 라이브러리, 도구 식별
+3. 프로젝트 영역 분류: 프론트엔드, 백엔드, API, 인프라 등
+4. 라벨 생성: 타입, 영역, 난이도 기반으로 핵심 라벨만 생성
+
+## 라벨 생성 기준
+
+**아래는 예시이며, 프로젝트에 맞게 조정해서 생성해주세요.**
+
+### 타입 (Type)
+- `type: feature`, `type: bug`, `type: enhancement`, `type: documentation`, `type: refactor`
+
+### 영역 (Area)
+- `frontend` `backend` `api` `devops`, `crawling` `ai` `database` `infrastructure`
+
+### 난이도 (Complexity)
+- `complexity: easy` `complexity: medium` `complexity: hard`
+
+## 생성 명령어 예시
+```bash
+gh label create "type: feature" --color "0e8a16" --description "새로운 기능 추가"
+gh label create "frontend" --color "1d76db" --description "프론트엔드 관련 작업"
+gh label create "complexity: easy" --color "7057ff" --description "간단한 작업"
+```

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

@@ -0,0 +1,60 @@
+## 작업 세분화하기
+
+큰 작업을 관리 가능한 독립적인 이슈들로 분해합니다. `@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+## 작업 순서
+1. 이슈 번호 확인: `gh issue list`로 현재 이슈 번호 확인하기.
+2. 작업 분석: 작업의 핵심 요구사항과 목표를 이해하기.
+3. 작업 분해: 주요 작업을 더 작고 관리하기 쉬운 하위 작업 또는 이슈로 나누기. **너무 많은 이슈보다 최적의 개수로 분해 (관리 가능한 수준)**할 것.
+4. 의존성 분석: 다른 작업이 선행돼야 하는 의존성 파악하기
+5. 마일스톤 이름 제안: 분해된 작업들을 묶을 마일스톤명 제안하기
+6. 관련 PR 확인 (선택): `gh pr list --state closed --limit 20`로 참고할 만한 유사 작업 찾기 (없으면 생략)
+7. 분해된 이슈 출력: 분해된 이슈들을 마일스톤명과 함께 출력하기.
+8. 깃허브에 마일스톤과 이슈를 생성할지 묻기: AskUserQuestion 도구로 사용자가 결정하도록 요청하기.
+   - 마일스톤 생성: `gh api repos/:owner/:repo/milestones -f title="마일스톤명" -f description="설명"`
+   - 이슈 생성 시 `--milestone` 옵션으로 할당
+
+## 마일스톤 description 작성 가이드
+
+마일스톤 description에 반드시 포함할 내용:
+- 전체 작업의 목표와 범위
+- 이슈 처리 순서 (의존성 그래프)
+- 예: "이슈 순서: #1 -> #2 -> #3 -> #4"
+
+## 이슈 템플릿
+
+### 제목
+`[타입] 간결한 작업 설명`
+
+### 라벨 (실제 저장소 라벨 사용)
+**주의**: 라벨을 지정하기 전에 `gh label list` 명령어로 저장소의 실제 라벨을 확인하세요.
+
+예시 (프로젝트에 따라 다름, 참고용으로만 이해하고 사용하지 말 것):
+- **타입**: `type: feature`, `type: documentation`, `type: enhancement`, `type: bug`
+- **영역**: `area: model/inference`, `area: model/training`, `area: dataset`, `area: detection`
+- **난이도**: `complexity: easy`, `complexity: medium`, `complexity: hard`
+- **우선순위**: `priority: high`, `priority: medium`, `priority: low`
+
+### 설명
+**목적**: [왜 필요한지]
+
+**작업 내용**:
+- [ ] 구체적 요구사항 1
+- [ ] 구체적 요구사항 2
+
+**수정할 파일**:
+- `경로/파일명` - 변경 내용
+
+**완료 조건**:
+- [ ] 기능 구현 완료
+- [ ] 데모 페이지에 추가 (UI 컴포넌트인 경우)
+
+**의존성**:
+- [ ] 없음 또는 선행 이슈 #번호
+
+**권장 에이전트** (해당되는 경우):
+- 아규먼트에 에이전트 사용이 명시된 경우 여기에 포함
+
+**참고 자료** (선택사항):
+- 관련 PR이 있으면 추가 (예: PR #36 - 간단한 설명)
+- 없으면 이 섹션 생략 가능

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

@@ -0,0 +1,71 @@
+---
+description: PR 머지 후 브랜치 정리 및 CLAUDE.md 업데이트
+---
+
+# PR 머지 후 정리
+
+PR이 머지된 후 브랜치 정리와 CLAUDE.md 업데이트를 수행합니다. `@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+## 아규먼트
+
+- PR 번호 (선택): 없으면 대화 맥락에서 파악하거나 최근 머지된 PR 목록에서 선택 요청
+
+## 작업 순서
+
+1. **PR 정보 확인**
+   - 아규먼트로 PR 번호가 주어지면 해당 PR 사용
+   - 없으면 대화 맥락에서 관련 PR/이슈 번호 파악 시도
+   - 파악 불가하면 `gh pr list --state merged --limit 5`로 최근 머지 PR 목록 보여주고 AskUserQuestion으로 선택 요청
+   - `gh pr view <PR번호> --json number,title,baseRefName,headRefName,body,state`로 PR 정보 확인
+   - `state`가 MERGED인지 확인
+
+2. **베이스 브랜치로 이동**
+   - `git fetch origin`
+   - `git checkout <baseRefName>`
+   - `git pull origin <baseRefName>`
+
+3. **이슈 브랜치 정리 (선택)**
+   - AskUserQuestion으로 로컬 브랜치 삭제 여부 질문
+   - 삭제 원하면: `git branch -d <headRefName>`
+
+4. **CLAUDE.md 분석 및 업데이트**
+   - CLAUDE.md 존재 여부 확인
+     - 없으면: AskUserQuestion으로 생성 여부 또는 스킵 여부 질문
+   - 기존 내용 분석:
+     - 해결된 이슈 관련 임시 지침 찾기 (예: `#<이슈번호>`, `issue-<번호>` 언급)
+     - 오래되거나 부정확한 정보 식별
+     - 중복되거나 불필요한 내용 식별
+   - 업데이트 제안 작성:
+     - **삭제 대상**: 해결된 이슈 관련 임시 메모/지침
+     - **추가 대상**: 이슈 해결 과정에서 발견한 새로운 패턴/컨벤션
+     - **수정 대상**: 오래되거나 부정확한 정보
+   - AskUserQuestion으로 제안 내용 확인 후 적용
+
+5. **변경사항 커밋 (선택)**
+   - CLAUDE.md가 변경되었으면 AskUserQuestion으로 커밋 여부 질문
+   - 커밋 원하면: Conventional Commits 형식으로 커밋
+
+## 작업 지침
+
+- 한글로 답변
+- 코드나 문서 작성 시 이모지 사용 금지
+- 불명확한 사항은 추측하지 말고 AskUserQuestion 도구로 질문
+- CLAUDE.md 변경은 반드시 사용자 확인 후 진행
+- 브랜치 삭제, 커밋 등 되돌리기 어려운 작업은 항상 사용자 확인 필요
+
+## CLAUDE.md 업데이트 가이드
+
+### 삭제 대상 예시
+- `TODO: #123 해결 후 제거` 형태의 임시 메모
+- 특정 이슈 해결을 위한 임시 워크어라운드 설명
+- 이미 해결된 알려진 이슈 목록
+
+### 추가 대상 예시
+- 이슈 해결 중 발견한 코드 컨벤션
+- 자주 발생하는 실수 방지 가이드
+- 새로 도입된 패턴이나 아키텍처 결정
+
+### 수정 대상 예시
+- 변경된 디렉토리 구조 설명
+- 업데이트된 의존성 정보
+- 더 이상 유효하지 않은 명령어나 설정

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

@@ -0,0 +1,54 @@
+
+# 깃허브 이슈 해결하기
+
+깃허브 이슈를 체계적으로 분석하고 해결하는 전문 개발자 역할을 수행합니다. 아규먼트로 깃허브 이슈 번호를 받아 해당 이슈를 해결합니다. `@CLAUDE.md`의 프로젝트 지침을 준수할 것.
+
+## 작업 순서
+
+1. **이슈 분석**: 
+   - `gh issue view $ISSUE_NUMBER --json title,body,comments,milestone`로 이슈의 제목, 본문, 레이블, 마일스톤을 확인
+   - 마일스톤이 있다면 `gh issue list --milestone "<milestone-name>" --json number,title,state`로 관련 이슈들을 확인하여 전체 맥락 파악
+   - 요구사항을 정확히 파악
+
+2. **브랜치 생성**: `main` 또는 `master` 브랜치에서 `issue-$ISSUE_NUMBER` 형태로 새 브랜치를 생성하고 체크아웃합니다.
+   - **서브모듈 초기화**: Worktree 사용 시 `git submodule update --init --recursive` 실행 필요
+
+3. **코드베이스 분석**: 이슈 해결에 필요한 관련 파일과 구조를 파악하기 위해 서브에이전트를 활용하여 코드베이스를 병렬로 분석합니다.
+
+4. **해결 계획 수립**: 분석 결과를 바탕으로 구체적인 해결 방안을 계획하고 작업 단계를 정의합니다.
+
+5. **이슈 해결**: 서브에이전트를 생성하여 계획에 따라 코드를 수정하고 기능을 구현합니다.
+   - **실행 검증 필수**: Python 스크립트, 실행 파일, 또는 동작 가능한 코드의 경우 반드시 실제 실행하여 정상 동작을 확인합니다. 단순히 파일 존재나 이전 결과만으로 판단하지 않습니다.
+
+6. **테스트 작성**: 파일별로 독립적인 서브에이전트를 생성하여 병렬로 단위 테스트를 작성하고 80% 이상의 커버리지를 확보합니다.
+
+7. **검증**: 테스트 실행, 린트 검사, 빌드 확인을 각각 독립적인 서브에이전트로 병렬 실행하여 코드 품질을 검증합니다.
+
+8. **PR 생성**: 해결된 이슈에 대한 풀 리퀘스트를 생성합니다.
+
+9. **이슈 체크박스 업데이트**: 해당 이슈의 체크박스 항목들을 완료된 것으로 체크하여 업데이트합니다.
+
+## 작업 지침
+- 불명확한 요구사항이나 구현 방향이 여러 가지일 경우 AskUserQuestion 도구로 사용자에게 확인
+- 마일스톤이 있다면 마일스톤 description을 읽어 전체 맥락과 이슈 순서를 파악
+- 한글로 답할 것, 주석 및 마크다운도 한글로 작성할 것
+- 코드나 문서 작성 시 이모지 사용 금지
+- PR 설명은 한글로 작성
+- 컴포넌트가 데모 페이지에 추가되는 경우, Playwright MCP를 사용해 해당 컴포넌트를 E2E 테스트로 검증합니다.
+- 일회성 테스트 스크립트나 임시 헬퍼 파일은 작업 완료 후 반드시 삭제합니다.
+- 커밋, PR, 이슈에 'Generated with Claude', 'Co-Authored-By: Claude' 등 Claude attribution 금지
+
+## 검증 및 완료 기준
+
+**중요**: 체크박스를 완료로 표시하기 전에 반드시 실제 동작을 확인해야 합니다.
+
+### 검증 원칙
+1. **실제 실행 필수**: 코드/설정이 실제로 동작하는지 직접 실행하여 확인
+2. **증거 제시**: 완료를 증명할 수 있는 실제 출력이나 결과를 보여줄 것
+3. **추측 금지**: 확인하지 않은 것은 "미확인" 또는 "추정됨"으로 명시
+4. **부분 완료 구분**: 코드는 작성했지만 테스트하지 않은 경우 명확히 구분
+
+### 금지 사항
+- 실행하지 않고 "동작할 것으로 예상됩니다"라고 보고
+- 로그를 보지 않고 "로그에 나타날 것입니다"라고 단언
+- 추측을 사실처럼 보고

package/.claude/commands/plan.md

@@ -0,0 +1,25 @@
+---
+description: 요구사항 분석 후 구현 계획만 수립
+---
+
+# 구현 계획 수립
+
+아규먼트로 받은 요구사항을 신중히 분석하고, 코드베이스를 이해한 후, **실제 구현 없이** 실행 계획만 제시합니다.
+
+## IMPORTANT
+- When you need clarification or there are multiple options, please ask me interactive questions (USE interactive question tool `AskUserQuestion`) before proceeding.
+
+## 수행 작업
+
+1. 요구사항의 의도 파악 (불명확하면 질문)
+2. 관련 코드베이스 조사 및 이해
+3. 단계별 실행 계획 작성
+4. 주의사항 및 결정 필요 사항 제시
+
+## 처리 원칙
+
+- **구현 금지**: 바로 코드 작성하지 말고 계획만 수립
+- **충분한 조사**: 코드베이스를 먼저 이해한 후 계획
+- **질문 우선**: 모르는 것이나 헷갈리는 것은 추측하지 말고 반드시 질문
+- **CLAUDE.md 준수**: `@CLAUDE.md`의 프로젝트 지침을 준수할 것
+- **투명한 소통**: 불명확한 부분, 위험 요소, 대안 등 명시

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

@@ -0,0 +1,186 @@
+---
+name: code-explorer
+description: Search and analyze code repositories on GitHub and Hugging Face (Models, Datasets, Spaces). This skill should be used when exploring open-source projects, finding implementation references, discovering ML models/datasets, or analyzing how others have solved similar problems.
+---
+
+# Code Explorer
+
+## Overview
+
+To search and analyze code repositories across GitHub and Hugging Face platforms, use this skill. It enables discovering implementation patterns, finding relevant ML models/datasets, and exploring demo applications (Spaces) for learning and reference.
+
+## Supported Platforms
+
+| Platform | Search Targets | Tool |
+|----------|---------------|------|
+| **GitHub** | Repositories, Code | `gh` CLI |
+| **Hugging Face** | Models, Datasets, Spaces | `uvx hf` CLI + `huggingface_hub` API |
+
+## Workflow Decision Tree
+
+```
+User wants to explore code/resources
+    |
+    +-- Looking for code implementations?
+    |   +-- Use GitHub search
+    |       +-- scripts/search_github.py (or gh CLI directly)
+    |       +-- Analyze repo structure, README, key files
+    |
+    +-- Looking for ML resources?
+        +-- Use Hugging Face search
+            +-- scripts/search_huggingface.py (search via API)
+            +-- uvx hf download (download files)
+```
+
+## Scripts
+
+**Always run scripts with `--help` first** to see usage. These scripts handle common search workflows reliably.
+
+### Available Scripts
+
+- `scripts/search_github.py` - GitHub repository search using gh CLI
+- `scripts/search_huggingface.py` - Hugging Face search (models, datasets, spaces)
+
+### Quick Examples
+
+```bash
+# GitHub search
+python scripts/search_github.py "object detection" --limit 10 --help
+
+# Hugging Face search
+python scripts/search_huggingface.py "qwen vl" --type models --help
+```
+
+## GitHub Search
+
+### Using gh CLI Directly
+
+```bash
+# Search repositories by keyword
+gh search repos "open vocabulary detection" --sort stars --limit 10
+
+# Filter by language
+gh search repos "gradio app" --language python --limit 5
+
+# View repository details
+gh repo view owner/repo
+
+# Search code within repositories
+gh search code "Qwen2VL" --extension py
+```
+
+### Repository Analysis
+
+To analyze a found repository:
+
+1. Review README.md for usage instructions
+2. Identify main entry points (app.py, main.py, inference.py)
+3. Check dependencies (requirements.txt, pyproject.toml)
+4. Study implementation patterns in source files
+
+## Hugging Face Search
+
+### Search (via script or Python API)
+
+```bash
+# Search models
+python scripts/search_huggingface.py "object detection" --type models --limit 10
+
+# Search datasets
+python scripts/search_huggingface.py "coco" --type datasets --limit 5
+
+# Search spaces (demos)
+python scripts/search_huggingface.py "gradio demo" --type spaces --limit 10
+
+# Search all types
+python scripts/search_huggingface.py "qwen vl" --type all
+```
+
+### Download (via uvx hf)
+
+```bash
+# Download space source code (use /tmp/ for temporary analysis)
+uvx hf download <space_id> --repo-type space --include "*.py" --local-dir /tmp/<space_name>
+
+# Download model files
+uvx hf download <repo_id> --include "*.json" --local-dir /tmp/<model_name>
+
+# Download to project directory (when needed permanently)
+uvx hf download <repo_id> --local-dir ./my-model
+```
+
+**Note**: Always use `--local-dir /tmp/` for temporary code analysis to avoid cluttering the project.
+
+### Common Search Patterns
+
+```bash
+# Find models for specific task
+python scripts/search_huggingface.py "open vocabulary detection" --type models
+python scripts/search_huggingface.py "qwen2 vl" --type models
+python scripts/search_huggingface.py "grounding dino" --type models
+
+# Find demo applications
+python scripts/search_huggingface.py "object detection demo" --type spaces
+python scripts/search_huggingface.py "gradio image" --type spaces
+```
+
+### Analyzing a Space
+
+To understand how a Space is implemented:
+
+1. Find the space: `python scripts/search_huggingface.py "keyword" --type spaces`
+2. Download source: `uvx hf download <space_id> --repo-type space --include "*.py" --include "requirements.txt" --local-dir /tmp/<space_name>`
+3. Or view online: `https://huggingface.co/spaces/{space_id}/tree/main`
+4. Focus on `app.py` for main logic
+5. Check `requirements.txt` for dependencies
+
+## Example Use Cases
+
+### Find Qwen3-VL Open Vocab Detection Code
+
+```bash
+# Search GitHub
+gh search repos "qwen vl object detection" --sort stars
+gh search code "Qwen2VL" --extension py
+
+# Search Hugging Face
+python scripts/search_huggingface.py "qwen2-vl" --type models
+python scripts/search_huggingface.py "qwen vl" --type spaces
+```
+
+### Find Gradio Demo Patterns
+
+```bash
+# Search spaces using Gradio
+python scripts/search_huggingface.py "gradio object detection" --type spaces
+
+# Download a space to study
+uvx hf download username/space-name --repo-type space --include "*.py" --local-dir /tmp/space-name
+```
+
+### Find Pre-trained Detection Models
+
+```bash
+python scripts/search_huggingface.py "object-detection" --type models --limit 20
+python scripts/search_huggingface.py "grounding-dino" --type models
+python scripts/search_huggingface.py "yolo-world" --type models
+```
+
+## Resources
+
+### scripts/
+- `search_github.py` - GitHub repository search wrapper
+- `search_huggingface.py` - Hugging Face Hub search wrapper
+
+### references/
+- `github_api.md` - GitHub CLI detailed reference
+- `huggingface_api.md` - Hugging Face Hub API and CLI reference
+
+## Tips
+
+1. **Start broad, then narrow**: Begin with general keywords, then add filters
+2. **Check stars/likes**: Higher counts often indicate quality
+3. **Review recent activity**: Recently updated repos are better maintained
+4. **Use --help first**: Scripts have detailed usage information
+5. **Download selectively**: Use `uvx hf download --include` to download only needed files
+6. **Always cite sources**: Include repository URLs, Space links, or model IDs you referenced