@kood/claude-code 0.6.0 → 0.6.2

package/templates/.claude/skills/research/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: research
+description: 범용 자료조사 후 사람이 읽기 쉬운 구조화 리포트 생성. 모든 검색 채널(WebSearch, WebFetch, GitHub MCP, Firecrawl, SearXNG) 동원.
+user-invocable: true
+---
+
+@../../instructions/workflow-patterns/sequential-thinking.md
+@../../instructions/agent-patterns/parallel-execution.md
+@../../instructions/agent-patterns/model-routing.md
+@../../instructions/sourcing/reliable-search.md
+@../../instructions/context-optimization/redundant-exploration-prevention.md
+@../../instructions/validation/forbidden-patterns.md
+@../../instructions/validation/required-behaviors.md
+
+# Research Skill
+
+> 범용 자료조사 → 사람이 읽기 쉬운 구조화 리포트 자동 생성
+
+---
+
+<purpose>
+
+brainstorm = **아이디어 발산** / research = **팩트 수렴**
+docs-fetch = **AI용 문서** / research = **사람이 읽는 리포트**
+
+**입력:** 주제 (자연어) + 선택적 깊이 (--quick/--deep)
+**출력:** `.claude/research/[NN].주제_요약.md` (Consulting Style 리포트)
+
+</purpose>
+
+---
+
+<trigger_conditions>
+
+| 트리거 | 반응 |
+|--------|------|
+| `/research AI 에이전트 프레임워크 비교` | 기술 비교 조사 |
+| `/research --deep 한국 SaaS 시장 트렌드` | 심층 시장 조사 |
+| `/research --quick WebSocket vs SSE` | 빠른 기술 비교 |
+| "OO에 대해 자료조사 해줘" | 주제 확인 후 실행 |
+
+ARGUMENT 없음 → 즉시 질문: "어떤 주제를 조사할까요?"
+
+</trigger_conditions>
+
+---
+
+<depth_levels>
+
+| 설정 | quick | standard (기본) | deep |
+|------|-------|----------------|------|
+| **플래그** | `--quick` | (없음) | `--deep` |
+| **검색 쿼리** | 3-5개 | 5-10개 | 10-15개 |
+| **에이전트** | researcher 2 + explore 0-1 | researcher 3-4 + explore 0-1 | researcher 4-5 + explore 1 + MCP |
+| **Iterative** | X | X | O (analyst → 2차 수집) |
+| **소스 최소** | 5개 | 10개 | 20개+ |
+| **리포트** | 500-1000자 | 1500-3000자 | 3000-6000자 |
+
+</depth_levels>
+
+---
+
+<topic_classification>
+
+Phase 0에서 자동 분류 → 채널 조합 결정:
+
+| 유형 | 키워드 | 채널 |
+|------|--------|------|
+| **기술 비교** | "vs", "비교" | WebSearch + explore(gh) |
+| **시장/트렌드** | "시장", "트렌드" | WebSearch + Firecrawl |
+| **경쟁사 분석** | "경쟁사", "대안" | WebSearch + GitHub MCP |
+| **학술/개념** | "원리", "논문" | WebSearch (arxiv) + WebFetch |
+| **프로젝트 내부** | "우리 코드" | explore + Grep |
+| **라이브러리** | 패키지명@버전 | → **docs-fetch 위임** |
+
+</topic_classification>
+
+---
+
+<sourcing_strategy>
+
+@../../instructions/sourcing/reliable-search.md
+
+**Research 고유 설정:**
+
+| 깊이 | 최소 소스 | 출처 등급 S/A 비율 |
+|------|-----------|-------------------|
+| quick | 5개 | 40%+ |
+| standard | 10개 | 50%+ |
+| deep | 20개+ | 60%+ |
+
+</sourcing_strategy>
+
+---
+
+<workflow>
+
+## 실행 흐름
+
+| Phase | 작업 | 도구 |
+|-------|------|------|
+| **0** | 입력 파싱 + MCP 감지 + 주제 분류 | ToolSearch × 3 |
+| **1** | 검색 전략 (Sequential Thinking 2단계) | ST: 질문 도출 → 쿼리 생성 |
+| **2** | 병렬 자료 수집 | researcher + explore + MCP |
+| **3** | 갭 분석 + 2차 수집 (**deep만**) | analyst → researcher |
+| **4** | 리포트 생성 | general-purpose |
+| **5** | 저장 + 터미널 출력 | Write |
+
+---
+
+### Phase 0: 환경 감지
+
+```
+1. 입력 파싱: 주제, --quick/--deep, 특수 지시 ("한국어 우선" 등)
+2. 주제 분류: <topic_classification> 참조 (라이브러리 → docs-fetch 위임)
+3. MCP 감지: ToolSearch("firecrawl"), ToolSearch("searxng"), ToolSearch("github")
+4. 기존 조사: .claude/research/ 동일 주제 → 업데이트 모드
+```
+
+### Phase 1: 검색 전략
+
+```
+Sequential Thinking (2단계):
+  thought 1: 핵심 질문 3-5개, 주제 유형 확정, 범위 결정 (시간/지역/언어)
+  thought 2: 다각도 쿼리 생성 (영어+한국어), 채널별 배분, 에이전트 역할 분배
+
+**필수**: 모든 검색 쿼리에 현재 연도(2026) 포함. @reliable-search.md 날짜 인식 규칙 적용.
+```
+
+### Phase 2: 병렬 수집
+
+**에이전트 도구 제약 (@.claude/agents/ 정의 준수):**
+
+| Agent | Model | 도구 | 역할 |
+|-------|-------|------|------|
+| researcher | sonnet | WebSearch, WebFetch, Read | 웹 조사 + 출처 수집 |
+| explore | haiku | Read, Glob, Grep, **Bash** | `gh` CLI GitHub 분석 |
+| main agent | - | MCP 도구들 | Firecrawl/SearXNG/GitHub MCP 직접 실행 |
+
+```typescript
+// 기술 비교 (standard: researcher 3 + explore 1 병렬)
+Task({ subagent_type: 'researcher',
+       prompt: '기술 A 장단점, 성능 2026. 검색 쿼리에 현재 연도 포함. 출처: URL + 발행일 + 소스유형(공식/블로그/커뮤니티).' })
+Task({ subagent_type: 'researcher',
+       prompt: '기술 B 장단점, 성능 2026. 검색 쿼리에 현재 연도 포함. 출처: URL + 발행일 + 소스유형.' })
+Task({ subagent_type: 'researcher',
+       prompt: 'A vs B 벤치마크, 비교, 후기 2026. 검색 쿼리에 현재 연도 포함. 출처: URL + 발행일 + 소스유형.' })
+Task({ subagent_type: 'explore', model: 'haiku',
+       prompt: 'gh search repos "기술 A/B" --sort stars. 스타, 커밋, 이슈 비교.' })
+// MCP 가용 시 main agent가 동시에 search_repositories, firecrawl_scrape 등 실행
+```
+
+**researcher 출력:** `요약 → 공식 문서 → GitHub 이슈/PR → 추가 참고 → 권장사항` (researcher agent 정의 준수)
+**시장/트렌드:** researcher를 글로벌/한국/투자 등 관점별 배분
+**경쟁사:** researcher를 경쟁사별 1개씩 + 비교 리뷰 1개
+
+### Phase 3: Iterative Deep Search (deep만)
+
+```
+analyst (opus, 6-gap 프레임워크):
+  1차 수집 갭 분석 → 커버/빈 영역 식별, 미검증 가정, 추가 쿼리 2-5개 도출
+
+researcher × 2-3: 빈 영역 집중 검색
+```
+
+### Phase 4: 리포트 생성
+
+**document-writer는 AI용 문서 전문 → general-purpose 사용.**
+
+```typescript
+Task({ subagent_type: 'general-purpose',
+       prompt: `수집 자료 기반 리포트 작성.
+       형식: <report_template> 참조. 경로: .claude/research/[NN].주제_요약.md
+       필수: Executive Summary 250-400자 (결론 우선), 출처 URL, 비교 테이블, 권장사항
+       사람용 문서: XML 태그/토큰 최적화 하지 말 것` })
+```
+
+### Phase 5: 저장
+
+```
+파일: .claude/research/[NN].주제_요약.md (기존 파일 다음 번호, 한글+언더스코어)
+넘버링: ls .claude/research/ | sort -r | head -1 → 다음 번호
+출력: Executive Summary + 핵심 발견 3-5개 + "전체 리포트: [경로]" 안내
+```
+
+</workflow>
+
+---
+
+<report_template>
+
+@./report-template.md
+
+### 작성 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| **결론 우선** | 가장 중요한 결론을 첫 문장에 (Pyramid Principle) |
+| **팩트 기반** | 모든 핵심 주장에 출처 URL 필수 |
+| **시각적 계층** | H1 하나, H2-H3, 테이블 활용 |
+| **Progressive Disclosure** | 요약→상세, Executive Summary만 읽어도 충분 |
+
+</report_template>
+
+---
+
+<chaining>
+
+| 흐름 | 사용 시점 |
+|------|---------|
+| research → brainstorm | 팩트 조사 후 아이디어 도출 |
+| research → prd | 시장 조사 → 요구사항 정의 |
+| brainstorm → research | 아이디어 실현 가능성 검증 |
+
+</chaining>
+
+---
+
+<examples>
+
+```
+/research WebSocket vs SSE vs gRPC 실시간 통신
+
+Phase 0: 기술 비교, standard
+Phase 1: 쿼리 7개 (장단점, 성능, 사용사례, 스케일링)
+Phase 2: researcher 3 + explore 1 (gh search repos)
+Phase 4: 리포트 → .claude/research/02.실시간_통신_기술_비교.md
+
+Executive Summary:
+gRPC가 처리량/레이턴시 우위(HTTP/2)이나 브라우저 미지원.
+웹 → WebSocket, 단방향 → SSE, 마이크로서비스 → gRPC.
+
+| 기준 | WebSocket | SSE | gRPC |
+|------|-----------|-----|------|
+| 방향 | 양방향 | 서버→클라 | 양방향 |
+| 브라우저 | ✅ | ✅ | ❌ |
+| 복잡도 | 중간 | 낮음 | 높음 |
+```
+
+**deep 예시:** `/research --deep 한국 AI SaaS 시장 2026` → researcher 5 + explore 1 + Phase 3 analyst 갭분석 → .claude/research/03.한국_AI_SaaS_시장_2026.md (~5000자)
+
+</examples>
+
+---
+
+<validation>
+
+| 단계 | 체크 |
+|------|------|
+| **실행 전** | ARGUMENT, 주제 분류, MCP 감지, 깊이 확인 |
+| **수집 후** | 최소 소스 충족 (5/10/20), 출처 URL, 다각도 수집, **출처 등급 S/A/B/C 분류**, **교차 검증 확인** (핵심 주장 2개+ 소스) |
+| **리포트** | Exec Summary 250-400자, 출처, 비교 테이블, 권장사항, 참고자료, 메타데이터 |
+| **저장** | .claude/research/ 저장, 터미널 출력, 경로 안내 |
+
+**절대 금지:** 출처 없는 주장 / 단일 소스 리포트 / Exec Summary 누락 / 권장사항 누락 / 저장 안 함 / 라이브러리 주제 (→ docs-fetch) / **연도 없는 검색** / **출처 등급 미표기**
+
+</validation>

package/templates/.claude/skills/research/report-template.md

@@ -0,0 +1,88 @@
+# 리포트 템플릿
+
+```markdown
+# [주제] 조사 리포트
+
+> **조사일:** YYYY-MM-DD | **깊이:** quick/standard/deep | **소스:** N개 검토, M개 인용
+
+---
+
+## Executive Summary
+
+[250-400자. 가장 중요한 결론을 첫 문장에 배치 (McKinsey Pyramid Principle).
+핵심 발견사항 3-5개를 결론 우선으로 서술.]
+
+---
+
+## 1. 조사 개요
+
+### 1.1 배경
+[왜 이 조사가 필요한가]
+
+### 1.2 조사 범위
+[포함/제외 범위, 시간 범위, 지역]
+
+### 1.3 방법론
+[사용한 검색 채널, 수집 소스 수, 검색 쿼리 개수]
+
+---
+
+## 2. 핵심 발견사항
+
+### 2.1 [발견사항 1 제목]
+
+**핵심:** [한 문장 요약]
+
+[상세 설명. 데이터, 수치, 사례 포함.]
+
+> 출처: [제목](URL)
+
+(발견사항 개수: quick 3개 / standard 5개 / deep 7개+)
+
+---
+
+## 3. 비교 분석
+(비교 대상이 있을 때만 포함)
+
+| 기준 | 옵션 A | 옵션 B | 옵션 C |
+|------|--------|--------|--------|
+| [기준 1] | ... | ... | ... |
+| **종합 평가** | ... | ... | ... |
+
+---
+
+## 4. 트렌드 및 시사점
+
+- **트렌드 1:** [설명] ([출처](URL))
+
+---
+
+## 5. 결론 및 권장사항
+
+### 핵심 결론
+[Executive Summary의 확장. 최종 판단.]
+
+### 권장사항
+1. **[권장 1]:** [구체적이고 실행 가능한 액션]
+
+### 추가 조사 필요 영역
+- [커버하지 못한 영역]
+
+---
+
+## 참고자료
+
+### 공식 문서 / 1차 자료
+- [제목](URL) - [핵심 내용 1줄]
+
+### 기술 블로그 / 분석
+- [제목](URL) - [핵심 내용 1줄]
+
+---
+
+**메타데이터**
+- 생성일: YYYY-MM-DD
+- 검색 채널: [사용한 도구 목록]
+- 검색 쿼리: N개
+- 검토 소스: N개 / 인용 소스: M개
+```