@yeongjaeyou/claude-code-config 0.2.1 → 0.3.1

package/.claude/commands/ask-gemini.md

@@ -0,0 +1,438 @@
+---
+description: 현재 대화 맥락을 Gemini에게 전달하여 검토받기
+---
+
+# Gemini 검토 요청 (ask-gemini)
+
+현재 대화에서 진행 중인 작업(코드 변경, 설계, 구현 등)을 Gemini CLI에게 전달하여 검토받고, Claude가 cross-check하여 합의된 결론을 전달합니다.
+
+**핵심 원칙:**
+- Gemini CLI 호출 (API 비용 없음, Pro 구독 활용)
+- Gemini는 context/도구가 제한적이므로 Claude가 반드시 검증
+- 불일치 시 Gemini에 재질문 (컨텍스트 재전달 방식)
+- 최대 3회 핑퐁 후 합의 도출
+
+---
+
+## 아규먼트
+
+`$ARGUMENTS`로 검토 방향 또는 파일 경로를 받습니다.
+
+### 호출 방식 3가지
+
+1. **아규먼트 없이**: `/ask-gemini`
+   - Claude가 현재 대화 맥락에서 관련 파일/변경사항을 자동 수집
+   - 범용 검토 (구현 방향성, 코드 품질, 설계 등)
+
+2. **간단한 설명**: `/ask-gemini '프론트엔드 컴포넌트 설계 검토해줘'`
+   - 사용자가 지정한 방향으로 검토
+   - Claude가 해당 방향에 맞는 컨텍스트 수집
+
+3. **파일 경로**: `/ask-gemini src/components/foo.tsx`
+   - 특정 파일을 중심으로 검토
+   - 해당 파일 + 관련 의존성 파일 포함
+
+### 아규먼트 파싱 규칙
+
+```
+판단 기준 (우선순위 순):
+1. 아규먼트가 실제 존재하는 파일/디렉토리 -> 파일 모드
+2. 그 외 모든 경우 -> 텍스트 모드 (검토 방향 지시)
+```
+
+---
+
+## Gemini 컨텍스트 구성 원칙
+
+### 1. 이번 워크플로우의 Gemini 사용 범위
+- **Gemini CLI** 사용 (Bash 도구로 호출)
+- 네트워크/웹서치는 사용하지 않음 (재현성과 안전을 위해)
+- 재현성을 위해 컨텍스트를 프롬프트에 직접 포함
+
+### 2. 컨텍스트 자동 수집 항목
+Claude가 다음 정보를 자동으로 수집:
+
+| 항목 | 수집 방법 | 우선순위 |
+|------|----------|---------|
+| 현재 대화에서 다룬 파일들 | 대화 히스토리에서 Read/Edit/Write 사용 이력 | 필수 |
+| git 변경사항 | `git diff`, `git status` | 필수 |
+| CLAUDE.md | 프로젝트 루트 | 필수 |
+| 관련 디렉토리 구조 | `tree` 또는 `ls` | 권장 |
+| 최근 커밋 히스토리 | `git log --oneline -10` | 선택 |
+| 관련 파일 심볼 개요 | `get_symbols_overview` 또는 파일 읽기 | 선택 |
+
+### 3. 포함하지 말아야 할 정보 (Gemini 프롬프트에서 제외)
+- Claude 전용 도구 언급 (AskUserQuestion, TodoWrite 등)
+- 내부 워크플로우 세부사항
+
+### 4. 민감정보 필터링 (필수)
+
+Gemini에게 전달하는 프롬프트에서 반드시 제외:
+
+```
+제외 파일 패턴:
+- .env*, secrets*, *credentials*, *token*
+- *.pem, *.key, *.p12, *.pfx
+
+제외 콘텐츠 패턴 (정규식):
+- API 키: sk-[a-zA-Z0-9]+, AKIA[A-Z0-9]+, ghp_[a-zA-Z0-9]+
+- 토큰: Bearer [a-zA-Z0-9._-]+
+- 비밀번호: password\s*[:=]\s*['"][^'"]+
+
+기타 제외:
+- 바이너리/미디어 파일 (*.mp4, *.png, *.jpg 등)
+- node_modules/, __pycache__/, .git/
+- 로그 파일 (*.log)
+```
+
+### 5. 프롬프트 크기 관리 (토큰 초과 방지)
+
+```
+축약 정책 (우선순위 순):
+1. git diff 우선 - 전체 파일 대신 변경분만 포함
+2. 대용량 파일 - 500줄 초과 시 변경 주변 50줄만 발췌
+3. 심볼 개요 - 매우 큰 파일은 함수/클래스 목록만
+4. 최대 파일 수 - 한 번에 5개 파일까지만 (나머지는 요약)
+
+타임아웃 발생 시:
+- CLAUDE.md 핵심 섹션만 포함 (전체 대신)
+- 디렉토리 구조 깊이 축소 (tree -L 1)
+- 파일 본문 생략하고 diff만 전달
+```
+
+### 6. 출력 형식 강제
+- 구조화된 형식 명시 (테이블, 리스트)
+- 라인 번호/파일 위치 참조 요구 (`nl -ba <file>` 형식 사용)
+
+---
+
+## 작업 순서
+
+### Step 1: 아규먼트 파싱
+
+```
+$ARGUMENTS 분석:
+- 없음 -> 범용 검토 모드
+- 텍스트 (따옴표 포함) -> 해당 방향 검토 모드
+- 파일 경로 -> 해당 파일 중심 검토 모드
+```
+
+아규먼트가 없으면 사용자에게 AskUserQuestion으로 검토 방향 확인:
+- 구현 방향성 검토
+- 코드 품질 검토
+- 설계/아키텍처 검토
+- 기타 (직접 입력)
+
+### Step 2: 컨텍스트 자동 수집
+
+#### 2.1 현재 대화에서 다룬 파일 목록 정리
+- 이 대화에서 Read/Edit/Write 도구로 접근한 파일들
+- 수정된 코드 내용 요약
+
+#### 2.2 git 변경사항 수집
+```bash
+git status
+git diff --stat
+git diff [특정 파일]  # 변경된 파일의 diff
+```
+
+#### 2.3 CLAUDE.md 읽기
+- 프로젝트 지침 전체 포함
+
+#### 2.4 관련 디렉토리 구조
+```bash
+tree -L 2 --dirsfirst -I 'node_modules|__pycache__|.git|dist|build|.next' [관련 디렉토리]
+```
+
+#### 2.5 (선택) 관련 파일 심볼 개요
+- 주요 변경 파일의 클래스/함수 구조 파악
+
+### Step 3: Gemini 프롬프트 구성
+
+다음 템플릿을 사용하여 프롬프트 작성:
+
+```
+## 역할
+당신은 코드 검토 전문가입니다. 현재 진행 중인 작업에 대해 검토해주세요.
+
+## 검토 유형
+[아규먼트 또는 사용자 선택에 따라]
+- 구현 방향성 검토: 현재 접근 방식이 올바른지, 더 나은 방법이 있는지
+- 코드 품질 검토: 코드 스타일, 버그 가능성, 리팩토링 제안
+- 설계/아키텍처 검토: 전체적인 설계 패턴, 의존성 구조
+
+## 프로젝트 컨텍스트
+
+### 프로젝트 지침 (CLAUDE.md)
+[CLAUDE.md 전문]
+
+### 디렉토리 구조
+[관련 디렉토리 tree 출력]
+
+## 검토 대상
+
+### 현재 작업 요약
+[대화에서 진행 중인 작업 설명]
+
+### 변경된 파일들
+[git diff 또는 변경 파일 목록]
+
+### 파일 내용
+[주요 변경 파일 내용 - 라인 번호 포함]
+
+## 검토 기준
+1. 구현 방향성: 요구사항에 맞는 접근인지, 대안이 있는지
+2. 코드 품질: 버그 가능성, 예외 처리, 코드 스타일
+3. 설계: 모듈 구조, 의존성, 확장성
+4. 프로젝트 지침 준수: CLAUDE.md 컨벤션 준수 여부
+
+## 출력 형식 (반드시 이 형식으로)
+
+### 잘한 점 (Strengths)
+- [항목]: [설명] (파일:라인)
+
+### 개선 제안 (Suggestions)
+| 항목 | 위치(파일:라인) | 현재 문제 | 개선 방안 |
+|------|---------------|----------|----------|
+
+### 위험 요소 (Risks)
+- [심각도]: [설명] (파일:라인)
+
+### 질문 사항 (Questions)
+- [질문 1]
+- [질문 2]
+
+### 종합 평가
+[1-2문장 요약]
+```
+
+### Step 4: Gemini CLI 호출
+
+**히어독 방식으로 Bash 도구 호출** (따옴표/개행 이스케이프 문제 방지):
+
+```bash
+cat <<'EOF' | gemini -p -
+[Step 3에서 구성한 전체 프롬프트]
+EOF
+```
+
+**Bash 도구 파라미터:**
+- `timeout`: 300000 (5분)
+- `description`: "Gemini 코드 검토 요청"
+
+**에러 처리:**
+- CLI 실패 시 stderr 캡처하여 사용자에게 보고
+- 타임아웃 시 프롬프트 길이 축소 후 1회 재시도
+
+### Step 5: Gemini 피드백 수신 및 파싱
+
+Gemini 응답을 다음 구조로 정리:
+- Strengths: 잘한 점 목록
+- Suggestions: 개선 제안 테이블
+- Risks: 위험 요소 목록
+- Questions: 질문 사항
+- Summary: 종합 평가
+
+### Step 6: Claude Cross-check
+
+**Gemini가 놓칠 수 있는 항목 검증:**
+
+1. **프로젝트 컨텍스트 검증**
+   - Gemini가 프로젝트 특성을 제대로 이해했는지
+   - CLAUDE.md 지침 준수 여부 재확인
+
+2. **기술적 정확성 검증**
+   - 제안된 개선 방안이 실제로 적용 가능한지
+   - 프로젝트 기술 스택과 호환되는지
+
+3. **기존 코드베이스 검증**
+   - 제안이 기존 패턴과 일관성 있는지
+   - 이미 해결된 문제를 지적하지 않았는지
+
+4. **Gemini 틀린 부분 식별**
+   - 검증 결과 틀린 내용 목록화
+   - 근거 준비 (실제 코드, 문서 등)
+
+### Step 7: 불일치 확인 및 재검토 (최대 3회)
+
+**불일치 항목이 있으면:**
+
+새 Gemini CLI 호출하되, 이전 맥락을 프롬프트에 포함:
+
+```
+## 역할
+당신은 코드 검토 전문가입니다.
+
+## 이전 검토 맥락
+
+### 1차 검토 결과 요약
+[Gemini 1차 응답 핵심 내용]
+
+### Claude Cross-check 결과
+[불일치 항목 및 근거]
+
+## 재검토 요청
+위 Cross-check 결과를 반영하여 다음 항목만 재검토해주세요:
+1. [불일치 항목 1]
+2. [불일치 항목 2]
+
+기존 평가 중 변경이 필요한 부분만 수정된 형식으로 답변해주세요.
+
+## 참고 정보
+[필요시 추가 컨텍스트]
+```
+
+**핑퐁 종료 조건:**
+- 합의 도달 (불일치 항목 없음)
+- 최대 3회 도달
+- Gemini가 Claude의 근거를 수용
+
+### Step 8: 합의 결과 전달
+
+**출력 형식:**
+
+```markdown
+## Gemini 검토 결과 (Gemini + Claude 합의)
+
+### 검토 과정
+- 검토 유형: [구현 방향성 / 코드 품질 / 설계 / 복합]
+- 핑퐁 횟수: [N]회
+- 합의 상태: [완전 합의 / 부분 합의 / Claude 판단]
+
+### [VALID] 유효한 피드백
+| 항목 | 설명 | 위치 | 출처 |
+|------|------|------|------|
+
+### [SUGGESTION] 개선 제안
+| 항목 | 현재 문제 | 개선 방안 | 출처 |
+|------|----------|----------|------|
+
+### [RISK] 주의 필요 사항
+| 심각도 | 설명 | 위치 |
+|--------|------|------|
+
+### [CORRECTION] Gemini 오류 교정
+| Gemini 주장 | 실제 상황 | 근거 |
+|-------------|----------|------|
+
+### [ACTION] 권장 조치
+(선택지가 있으면 AskUserQuestion으로 질문)
+
+### [SUMMARY] 종합 결론
+[최종 요약]
+```
+
+---
+
+## 작업 지침
+
+- 한글로 답변
+- 코드나 문서 작성 시 이모지 사용 금지
+- **불명확한 사항은 추측하지 말고 AskUserQuestion으로 질문**
+- 코드 수정 제안은 사용자 확인 후 진행
+- Gemini와 Claude 의견 불일치 시 근거를 명확히 제시
+- `@CLAUDE.md`의 프로젝트 지침을 준수할 것
+
+---
+
+## 오류 처리
+
+- **컨텍스트 부족**: "현재 대화에서 검토할 내용을 찾지 못했습니다. 검토 방향을 지정해주세요."
+- **Gemini CLI 미설치**: "Gemini CLI가 설치되어 있지 않습니다. `npm install -g @google/gemini-cli` 후 `gemini auth`로 인증해주세요."
+- **Gemini CLI 호출 실패**: "Gemini CLI 호출에 실패했습니다. `gemini auth` 상태를 확인해주세요."
+- **타임아웃**: "Gemini 응답 시간 초과. 프롬프트 길이를 줄이거나 다시 시도해주세요."
+- **재검토 필요**: "이전 맥락을 포함하여 새 세션으로 재검토를 진행합니다."
+
+---
+
+## 워크플로우 다이어그램
+
+```
+[Step 1: 아규먼트 파싱]
+    |
+    +-- 없음 -> AskUserQuestion으로 검토 유형 확인
+    +-- 텍스트 -> 해당 방향 검토
+    +-- 파일 경로 -> 해당 파일 중심 검토
+    |
+    v
+[Step 2: 컨텍스트 자동 수집]
+    - 대화 히스토리에서 파일 목록
+    - git diff / status
+    - CLAUDE.md
+    - 디렉토리 구조
+    |
+    v
+[Step 3: Gemini 프롬프트 구성]
+    |
+    v
+[Step 4: Gemini CLI 호출] --------------------------------+
+    |     cat <<'EOF' | gemini -p -                       |
+    v                                                     |
+[Step 5: 피드백 파싱]                                     |
+    |                                                     |
+    v                                                     |
+[Step 6: Claude Cross-check]                              |
+    |                                                     |
+    v                                                     |
+[Step 7: 불일치 있음?]                                    |
+    |                                                     |
+    +-- YES & 반복 < 3 --> [새 CLI 호출 + 컨텍스트 재전달]-+
+    |
+    +-- NO 또는 반복 >= 3 --> [Step 8: 합의 결과 전달]
+```
+
+---
+
+## 사용 예시
+
+```bash
+# 범용 검토 (현재 대화 맥락 자동 수집)
+/ask-gemini
+
+# 방향 지정 검토
+/ask-gemini '프론트엔드 컴포넌트 설계 검토해줘'
+/ask-gemini '이 구현 방향이 맞는지 확인해줘'
+/ask-gemini '코드 품질 이슈 찾아줘'
+
+# 특정 파일 검토
+/ask-gemini src/components/video/video-player.tsx
+/ask-gemini services/child_safety_processor.py
+```
+
+---
+
+## 예상 결과물 예시
+
+```markdown
+## Gemini 검토 결과 (Gemini + Claude 합의)
+
+### 검토 과정
+- 검토 유형: 코드 품질 + 설계
+- 핑퐁 횟수: 2회
+- 합의 상태: 완전 합의
+
+### [VALID] 유효한 피드백
+| 항목 | 설명 | 위치 | 출처 |
+|------|------|------|------|
+| 에러 처리 양호 | try-catch로 API 오류 처리 | hooks/use-video-analysis.ts:45 | Gemini |
+| 타입 안전성 | TypeScript 타입 명확히 정의 | components/vlm/types.ts | Gemini + Claude |
+
+### [SUGGESTION] 개선 제안
+| 항목 | 현재 문제 | 개선 방안 | 출처 |
+|------|----------|----------|------|
+| 메모이제이션 | 매 렌더링마다 객체 재생성 | useMemo로 최적화 | Gemini |
+| 로딩 상태 | 로딩 중 UI 피드백 없음 | Skeleton 컴포넌트 추가 | Claude |
+
+### [RISK] 주의 필요 사항
+| 심각도 | 설명 | 위치 |
+|--------|------|------|
+| Medium | 대용량 파일 처리 시 메모리 이슈 가능성 | video-processor.py:120 |
+
+### [CORRECTION] Gemini 오류 교정
+| Gemini 주장 | 실제 상황 | 근거 |
+|-------------|----------|------|
+| useState 초기값 누락 | 이미 기본값 설정됨 | hooks/use-video-analysis.ts:12 확인 |
+
+### [SUMMARY] 종합 결론
+전반적으로 코드 품질 양호. 메모이제이션과 로딩 UI 개선 권장.
+```

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

@@ -21,10 +21,15 @@ PR이 머지된 후 브랜치 정리와 CLAUDE.md 업데이트를 수행합니
 
 2. **로컬 변경사항 확인**
    - `git status --porcelain`으로 uncommitted 변경사항 확인
-   - 변경사항이 있으면 AskUserQuestion으로 처리 방법 질문:
-     - **stash 후 진행**: `git stash push -m "post-merge: 임시 저장"` 후 베이스 브랜치 이동, 작업 완료 후 `git stash pop`
+   - **Untracked 파일 (`??`)**: 브랜치 이동에 영향 없으므로 무시하고 진행
+   - **Modified/Staged 파일 (`M`, `A`, `D` 등)**: AskUserQuestion으로 처리 방법 질문:
+     - **stash 후 진행**: `git stash push -m "post-merge: 임시 저장"`
      - **변경사항 버리기**: `git checkout -- . && git clean -fd`
      - **작업 중단**: 사용자가 직접 처리하도록 중단
+   - **stash 선택 시**: 작업 완료 후 AskUserQuestion으로 stash 복원 여부 질문:
+     - **pop**: `git stash pop` (stash 제거하면서 복원)
+     - **apply**: `git stash apply` (stash 유지하면서 복원)
+     - **나중에**: 사용자가 직접 처리
 
 3. **베이스 브랜치로 이동**
    - `git fetch origin`

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

@@ -81,10 +81,15 @@ task-master set-status --id=<TASK_ID> --status=done
 git status --porcelain
 ```
 
-변경사항이 있으면 AskUserQuestion으로 처리 방법 질문:
-- **stash 후 진행**: `git stash push -m "post-merge: 임시 저장"`
-- **변경사항 버리기**: `git checkout -- . && git clean -fd`
-- **작업 중단**: 사용자가 직접 처리
+- **Untracked 파일 (`??`)**: 브랜치 이동에 영향 없으므로 무시하고 진행
+- **Modified/Staged 파일 (`M`, `A`, `D` 등)**: AskUserQuestion으로 처리 방법 질문:
+  - **stash 후 진행**: `git stash push -m "post-merge: 임시 저장"`
+  - **변경사항 버리기**: `git checkout -- . && git clean -fd`
+  - **작업 중단**: 사용자가 직접 처리
+- **stash 선택 시**: 작업 완료 후 AskUserQuestion으로 stash 복원 여부 질문:
+  - **pop**: `git stash pop` (stash 제거하면서 복원)
+  - **apply**: `git stash apply` (stash 유지하면서 복원)
+  - **나중에**: 사용자가 직접 처리
 
 ### 5. 베이스 브랜치로 이동
 
@@ -170,7 +175,9 @@ TaskMaster 상태:
 - 한글로 답변
 - 코드나 문서 작성 시 이모지 사용 금지
 - 불명확한 사항은 추측하지 말고 AskUserQuestion으로 질문
-- TaskMaster 상태 변경, 브랜치 삭제 등은 항상 사용자 확인 필요
+- CLAUDE.md 변경은 반드시 사용자 확인 후 진행
+- TaskMaster 상태 변경, 브랜치 삭제 등 되돌리기 어려운 작업은 항상 사용자 확인 필요
+- 커밋, PR, 이슈에 'Generated with Claude', 'Co-Authored-By: Claude' 등 Claude attribution 금지
 
 ---
 

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

@@ -57,6 +57,17 @@ task-master show $TASK_ID
 gh issue list --search "in:body \"Task Master 참조: task $TASK_ID\"" --json number,title
 ```
 
+**GitHub Issue를 찾지 못한 경우 (중요):**
+```
+→ sync-to-github가 실행되지 않은 상태일 수 있음
+→ 절대로 임의로 GitHub Issue를 새로 생성하지 말 것
+→ AskUserQuestion으로 사용자에게 확인:
+  1. "sync-to-github를 먼저 실행할까요?" (Issue 동기화 후 진행)
+  2. "Issue 없이 브랜치만 생성하고 진행할까요?" (task-N 브랜치 사용)
+  3. "작업을 중단할까요?"
+→ 사용자 선택에 따라 진행
+```
+
 ### 2. 태스크 정보 확인
 
 ```bash
@@ -225,6 +236,35 @@ $(task-master show $TASK_ID | grep -A 100 'Subtasks:')"
 
 ---
 
+## 작업 지침
+
+- 불명확한 요구사항이나 구현 방향이 여러 가지일 경우 AskUserQuestion 도구로 사용자에게 확인
+- 한글로 답할 것, 주석 및 마크다운도 한글로 작성할 것
+- 코드나 문서 작성 시 이모지 사용 금지
+- PR 설명은 한글로 작성
+- 컴포넌트가 데모 페이지에 추가되는 경우, Playwright MCP를 사용해 해당 컴포넌트를 E2E 테스트로 검증
+- 일회성 테스트 스크립트나 임시 헬퍼 파일은 작업 완료 후 반드시 삭제
+- 커밋, PR, 이슈에 'Generated with Claude', 'Co-Authored-By: Claude' 등 Claude attribution 금지
+
+---
+
+## 검증 및 완료 기준
+
+**중요**: 체크박스를 완료로 표시하기 전에 반드시 실제 동작을 확인해야 합니다.
+
+### 검증 원칙
+1. **실제 실행 필수**: 코드/설정이 실제로 동작하는지 직접 실행하여 확인
+2. **증거 제시**: 완료를 증명할 수 있는 실제 출력이나 결과를 보여줄 것
+3. **추측 금지**: 확인하지 않은 것은 "미확인" 또는 "추정됨"으로 명시
+4. **부분 완료 구분**: 코드는 작성했지만 테스트하지 않은 경우 명확히 구분
+
+### 금지 사항
+- 실행하지 않고 "동작할 것으로 예상됩니다"라고 보고
+- 로그를 보지 않고 "로그에 나타날 것입니다"라고 단언
+- 추측을 사실처럼 보고
+
+---
+
 ## 주의사항
 
 1. **ID 혼동 주의**