@yeongjaeyou/claude-code-config 0.2.0 → 0.3.0

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/ask-codex.md

@@ -0,0 +1,429 @@
+---
+description: 현재 대화 맥락을 Codex에게 전달하여 검토받기
+---
+
+# Codex 검토 요청 (ask-codex)
+
+현재 대화에서 진행 중인 작업(코드 변경, 설계, 구현 등)을 Codex MCP에게 전달하여 검토받고, Claude가 cross-check하여 합의된 결론을 전달합니다.
+
+**핵심 원칙:**
+- Codex는 context/도구가 제한적이므로 Claude가 반드시 검증
+- 불일치 시 Codex에 재질문 (컨텍스트 재전달 방식)
+- 최대 3회 핑퐁 후 합의 도출
+- 이모지 사용 금지
+
+---
+
+## 아규먼트
+
+`$ARGUMENTS`로 검토 방향 또는 파일 경로를 받습니다.
+
+### 호출 방식 3가지
+
+1. **아규먼트 없이**: `/ask-codex`
+   - Claude가 현재 대화 맥락에서 관련 파일/변경사항을 자동 수집
+   - 범용 검토 (구현 방향성, 코드 품질, 설계 등)
+
+2. **간단한 설명**: `/ask-codex '프론트엔드 컴포넌트 설계 검토해줘'`
+   - 사용자가 지정한 방향으로 검토
+   - Claude가 해당 방향에 맞는 컨텍스트 수집
+
+3. **파일 경로**: `/ask-codex src/components/foo.tsx`
+   - 특정 파일을 중심으로 검토
+   - 해당 파일 + 관련 의존성 파일 포함
+
+### 아규먼트 파싱 규칙
+
+```
+판단 기준 (우선순위 순):
+1. 아규먼트가 실제 존재하는 파일/디렉토리 → 파일 모드
+2. 그 외 모든 경우 → 텍스트 모드 (검토 방향 지시)
+```
+
+---
+
+## Codex 컨텍스트 구성 원칙
+
+### 1. 이번 워크플로우의 Codex 사용 범위
+- **Codex MCP 도구** 사용 (`mcp__codex__codex`)
+- sandbox는 `read-only` 설정
+- 네트워크/웹서치는 사용하지 않음 (재현성과 안전을 위해)
+- 재현성을 위해 컨텍스트를 프롬프트에 직접 포함
+
+### 2. 컨텍스트 자동 수집 항목
+Claude가 다음 정보를 자동으로 수집:
+
+| 항목 | 수집 방법 | 우선순위 |
+|------|----------|---------|
+| 현재 대화에서 다룬 파일들 | 대화 히스토리에서 Read/Edit/Write 사용 이력 | 필수 |
+| git 변경사항 | `git diff`, `git status` | 필수 |
+| CLAUDE.md | 프로젝트 루트 | 필수 |
+| 관련 디렉토리 구조 | `tree` 또는 `ls` | 권장 |
+| 최근 커밋 히스토리 | `git log --oneline -10` | 선택 |
+| 관련 파일 심볼 개요 | `get_symbols_overview` 또는 파일 읽기 | 선택 |
+
+### 3. 포함하지 말아야 할 정보 (Codex 프롬프트에서 제외)
+- Claude 전용 도구 언급 (AskUserQuestion, TodoWrite 등)
+- 내부 워크플로우 세부사항
+
+### 4. 민감정보 필터링 (필수)
+
+Codex에게 전달하는 프롬프트에서 반드시 제외:
+
+```
+제외 파일 패턴:
+- .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: Codex 프롬프트 구성
+
+다음 템플릿을 사용하여 프롬프트 작성:
+
+```
+## 역할
+당신은 코드 검토 전문가입니다. 현재 진행 중인 작업에 대해 검토해주세요.
+
+## 검토 유형
+[아규먼트 또는 사용자 선택에 따라]
+- 구현 방향성 검토: 현재 접근 방식이 올바른지, 더 나은 방법이 있는지
+- 코드 품질 검토: 코드 스타일, 버그 가능성, 리팩토링 제안
+- 설계/아키텍처 검토: 전체적인 설계 패턴, 의존성 구조
+
+## 프로젝트 컨텍스트
+
+### 프로젝트 지침 (CLAUDE.md)
+[CLAUDE.md 전문]
+
+### 디렉토리 구조
+[관련 디렉토리 tree 출력]
+
+## 검토 대상
+
+### 현재 작업 요약
+[대화에서 진행 중인 작업 설명]
+
+### 변경된 파일들
+[git diff 또는 변경 파일 목록]
+
+### 파일 내용
+[주요 변경 파일 내용 - 라인 번호 포함]
+
+## 검토 기준
+1. 구현 방향성: 요구사항에 맞는 접근인지, 대안이 있는지
+2. 코드 품질: 버그 가능성, 예외 처리, 코드 스타일
+3. 설계: 모듈 구조, 의존성, 확장성
+4. 프로젝트 지침 준수: CLAUDE.md 컨벤션 준수 여부
+
+## 출력 형식 (반드시 이 형식으로)
+
+### 잘한 점 (Strengths)
+- [항목]: [설명] (파일:라인)
+
+### 개선 제안 (Suggestions)
+| 항목 | 위치(파일:라인) | 현재 문제 | 개선 방안 |
+|------|---------------|----------|----------|
+
+### 위험 요소 (Risks)
+- [심각도]: [설명] (파일:라인)
+
+### 질문 사항 (Questions)
+- [질문 1]
+- [질문 2]
+
+### 종합 평가
+[1-2문장 요약]
+```
+
+### Step 4: Codex MCP 호출
+
+**mcp__codex__codex 도구 호출:**
+
+파라미터:
+- `prompt`: Step 3에서 구성한 전체 프롬프트
+- `sandbox`: "read-only"
+- `cwd`: 프로젝트 루트 경로
+
+### Step 5: Codex 피드백 수신 및 파싱
+
+Codex 응답을 다음 구조로 정리:
+- Strengths: 잘한 점 목록
+- Suggestions: 개선 제안 테이블
+- Risks: 위험 요소 목록
+- Questions: 질문 사항
+- Summary: 종합 평가
+
+### Step 6: Claude Cross-check
+
+**Codex가 놓칠 수 있는 항목 검증:**
+
+1. **프로젝트 컨텍스트 검증**
+   - Codex가 프로젝트 특성을 제대로 이해했는지
+   - CLAUDE.md 지침 준수 여부 재확인
+
+2. **기술적 정확성 검증**
+   - 제안된 개선 방안이 실제로 적용 가능한지
+   - 프로젝트 기술 스택과 호환되는지
+
+3. **기존 코드베이스 검증**
+   - 제안이 기존 패턴과 일관성 있는지
+   - 이미 해결된 문제를 지적하지 않았는지
+
+4. **Codex 틀린 부분 식별**
+   - 검증 결과 틀린 내용 목록화
+   - 근거 준비 (실제 코드, 문서 등)
+
+### Step 7: 불일치 확인 및 재검토 (최대 3회)
+
+**불일치 항목이 있으면:**
+
+`mcp__codex__codex` 새 세션으로 호출하되, 이전 맥락을 프롬프트에 포함:
+
+```
+## 역할
+당신은 코드 검토 전문가입니다.
+
+## 이전 검토 맥락
+
+### 1차 검토 결과 요약
+[Codex 1차 응답 핵심 내용]
+
+### Claude Cross-check 결과
+[불일치 항목 및 근거]
+
+## 재검토 요청
+위 Cross-check 결과를 반영하여 다음 항목만 재검토해주세요:
+1. [불일치 항목 1]
+2. [불일치 항목 2]
+
+기존 평가 중 변경이 필요한 부분만 수정된 형식으로 답변해주세요.
+
+## 참고 정보
+[필요시 추가 컨텍스트]
+```
+
+**핑퐁 종료 조건:**
+- 합의 도달 (불일치 항목 없음)
+- 최대 3회 도달
+- Codex가 Claude의 근거를 수용
+
+### Step 8: 합의 결과 전달
+
+**출력 형식:**
+
+```markdown
+## Codex 검토 결과 (Codex + Claude 합의)
+
+### 검토 과정
+- 검토 유형: [구현 방향성 / 코드 품질 / 설계 / 복합]
+- 핑퐁 횟수: [N]회
+- 합의 상태: [완전 합의 / 부분 합의 / Claude 판단]
+
+### [VALID] 유효한 피드백
+| 항목 | 설명 | 위치 | 출처 |
+|------|------|------|------|
+
+### [SUGGESTION] 개선 제안
+| 항목 | 현재 문제 | 개선 방안 | 출처 |
+|------|----------|----------|------|
+
+### [RISK] 주의 필요 사항
+| 심각도 | 설명 | 위치 |
+|--------|------|------|
+
+### [CORRECTION] Codex 오류 교정
+| Codex 주장 | 실제 상황 | 근거 |
+|-----------|----------|------|
+
+### [ACTION] 권장 조치
+(선택지가 있으면 AskUserQuestion으로 질문)
+
+### [SUMMARY] 종합 결론
+[최종 요약]
+```
+
+---
+
+## 작업 지침
+
+- 한글로 답변
+- 코드나 문서 작성 시 이모지 사용 금지
+- **불명확한 사항은 추측하지 말고 AskUserQuestion으로 질문**
+- 코드 수정 제안은 사용자 확인 후 진행
+- Codex와 Claude 의견 불일치 시 근거를 명확히 제시
+- `@CLAUDE.md`의 프로젝트 지침을 준수할 것
+
+---
+
+## 오류 처리
+
+- **컨텍스트 부족**: "현재 대화에서 검토할 내용을 찾지 못했습니다. 검토 방향을 지정해주세요."
+- **Codex MCP 호출 실패**: "Codex MCP 도구 호출에 실패했습니다. MCP 서버 상태를 확인해주세요."
+- **타임아웃**: "Codex 응답 시간 초과. 프롬프트 길이를 줄이거나 다시 시도해주세요."
+- **재검토 필요**: "이전 맥락을 포함하여 새 세션으로 재검토를 진행합니다."
+
+---
+
+## 워크플로우 다이어그램
+
+```
+[Step 1: 아규먼트 파싱]
+    |
+    ├─ 없음 → AskUserQuestion으로 검토 유형 확인
+    ├─ 텍스트 → 해당 방향 검토
+    └─ 파일 경로 → 해당 파일 중심 검토
+    |
+    v
+[Step 2: 컨텍스트 자동 수집]
+    - 대화 히스토리에서 파일 목록
+    - git diff / status
+    - CLAUDE.md
+    - 디렉토리 구조
+    |
+    v
+[Step 3: Codex 프롬프트 구성]
+    |
+    v
+[Step 4: Codex MCP 1차 검토] ─────────────────────────┐
+    |     (mcp__codex__codex, read-only)             |
+    v                                                 |
+[Step 5: 피드백 파싱]                                 |
+    |                                                 |
+    v                                                 |
+[Step 6: Claude Cross-check]                          |
+    |                                                 |
+    v                                                 |
+[Step 7: 불일치 있음?]                                |
+    |                                                 |
+    ├─ YES & 반복 < 3 ─> [새 MCP 호출 + 컨텍스트 재전달]┘
+    |
+    └─ NO 또는 반복 >= 3 ─> [Step 8: 합의 결과 전달]
+```
+
+---
+
+## 사용 예시
+
+```bash
+# 범용 검토 (현재 대화 맥락 자동 수집)
+/ask-codex
+
+# 방향 지정 검토
+/ask-codex '프론트엔드 컴포넌트 설계 검토해줘'
+/ask-codex '이 구현 방향이 맞는지 확인해줘'
+/ask-codex '코드 품질 이슈 찾아줘'
+
+# 특정 파일 검토
+/ask-codex src/components/video/video-player.tsx
+/ask-codex services/child_safety_processor.py
+```
+
+---
+
+## 예상 결과물 예시
+
+```markdown
+## Codex 검토 결과 (Codex + Claude 합의)
+
+### 검토 과정
+- 검토 유형: 코드 품질 + 설계
+- 핑퐁 횟수: 2회
+- 합의 상태: 완전 합의
+
+### [VALID] 유효한 피드백
+| 항목 | 설명 | 위치 | 출처 |
+|------|------|------|------|
+| 에러 처리 양호 | try-catch로 API 오류 처리 | hooks/use-video-analysis.ts:45 | Codex |
+| 타입 안전성 | TypeScript 타입 명확히 정의 | components/vlm/types.ts | Codex + Claude |
+
+### [SUGGESTION] 개선 제안
+| 항목 | 현재 문제 | 개선 방안 | 출처 |
+|------|----------|----------|------|
+| 메모이제이션 | 매 렌더링마다 객체 재생성 | useMemo로 최적화 | Codex |
+| 로딩 상태 | 로딩 중 UI 피드백 없음 | Skeleton 컴포넌트 추가 | Claude |
+
+### [RISK] 주의 필요 사항
+| 심각도 | 설명 | 위치 |
+|--------|------|------|
+| Medium | 대용량 파일 처리 시 메모리 이슈 가능성 | video-processor.py:120 |
+
+### [CORRECTION] Codex 오류 교정
+| Codex 주장 | 실제 상황 | 근거 |
+|-----------|----------|------|
+| useState 초기값 누락 | 이미 기본값 설정됨 | hooks/use-video-analysis.ts:12 확인 |
+
+### [SUMMARY] 종합 결론
+전반적으로 코드 품질 양호. 메모이제이션과 로딩 UI 개선 권장.
+```