@kood/claude-code 0.6.0 → 0.6.2

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

@@ -7,6 +7,9 @@ user-invocable: true
 @../../instructions/workflow-patterns/sequential-thinking.md
 @../../instructions/agent-patterns/parallel-execution.md
 @../../instructions/agent-patterns/model-routing.md
+@../../instructions/context-optimization/phase-based-execution.md
+@../../instructions/context-optimization/sub-agent-distribution.md
+@../../instructions/validation/scope-completeness.md
 @../../instructions/validation/forbidden-patterns.md
 @../../instructions/validation/required-behaviors.md
 
@@ -146,664 +149,17 @@ $ARGUMENTS 있음 → 다음 단계 진행
 
 <parallel_agent_execution>
 
-## 병렬 Agent 실행
+## 병렬 에이전트 실행
 
-**복잡한 리팩토링은 여러 Agent를 병렬로 실행하여 효율 향상.**
-
-### 권장 Agent
-
-| Agent | Model | 역할 |
-|-------|-------|------|
-| **@refactor-advisor** | sonnet | 리팩토링 계획 수립, 우선순위 분석 |
-| **@architect** | opus | 아키텍처 분석, 구조 개선 방향 제시 (READ-ONLY) |
-| **@implementation-executor** | sonnet | 리팩토링 구현 실행 |
-| **@code-reviewer** | opus | 리팩토링 후 품질 검증 |
-| **@analyst** | sonnet | 코드 메트릭 분석, 엣지 케이스 검증 |
-| **@explore** | haiku | 코드베이스 탐색, 의존성 파악 |
-| **@document-writer** | haiku/sonnet | 리팩토링 계획 및 결과 문서화 |
-| **@security-reviewer** | opus | 리팩토링 후 보안 취약점 검증 |
-| **@build-fixer** | sonnet | 리팩토링 후 빌드/타입 오류 수정 |
-
-### 병렬 실행 패턴
-
-### Read 도구 병렬화
-
-**프로젝트 분석 시 파일 병렬 읽기:**
-
-```typescript
-// ❌ 순차 읽기 (느림)
-Read({ file_path: "src/file1.ts" })
-// 대기...
-Read({ file_path: "src/file2.ts" })
-
-// ✅ 병렬 읽기 (빠름)
-Read({ file_path: "src/file1.ts" })
-Read({ file_path: "src/file2.ts" })
-Read({ file_path: "src/file3.ts" })
-Read({ file_path: "docs/api.md" })
-```
-
-**복잡한 탐색은 explore 에이전트 활용:**
-
-```typescript
-// 여러 영역 동시 탐색
-Task(subagent_type="explore", model="haiku",
-     prompt="영역 1 파일 구조 및 패턴 분석")
-Task(subagent_type="explore", model="haiku",
-     prompt="영역 2 의존성 및 관계 분석")
-```
-
----
-
-#### 1. 독립적 모듈 병렬 리팩토링
-
-```typescript
-// ✅ 여러 모듈을 동시에 리팩토링
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "User 모듈 리팩토링: 복잡도 감소, 중복 제거"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Product 모듈 리팩토링: 타입 안정성 개선"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Order 모듈 리팩토링: 함수 분리"
-})
-```
-
-#### 2. 분석 + 계획 병렬
-
-```typescript
-// ✅ 아키텍처 분석과 리팩토링 계획을 동시에
-Task({
-  subagent_type: "architect",
-  model: "opus",
-  prompt: "현재 아키텍처 문제점 및 개선 방향 분석 (READ-ONLY)"
-})
-
-Task({
-  subagent_type: "refactor-advisor",
-  model: "sonnet",
-  prompt: "리팩토링 우선순위 계획 및 단계별 전략"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "코드 복잡도, 중복률, 결합도 메트릭 분석"
-})
-```
-
-#### 3. 의존성 분석 + 수정 병렬
-
-```typescript
-// ✅ 의존성 파악과 독립 모듈 리팩토링 동시 진행
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "모듈 간 의존성 그래프 분석 및 순환 의존성 탐지"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "독립 유틸리티 함수 리팩토링 (의존성 없음)"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "타입 정의 개선 (다른 모듈에 영향 없음)"
-})
-```
-
-#### 4. 리팩토링 + 테스트 + 문서 병렬
-
-```typescript
-// ✅ 구현, 테스트, 문서를 동시에
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "API 레이어 리팩토링 실행"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "리팩토링된 함수에 대한 단위 테스트 작성"
-})
-
-Task({
-  subagent_type: "document-writer",
-  model: "haiku",
-  prompt: "리팩토링 변경 사항 및 마이그레이션 가이드 문서화"
-})
-```
-
-#### 5. 다중 관점 코드 리뷰 (병렬)
-
-```typescript
-// ✅ 리팩토링 후 여러 관점에서 동시 검증
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "성능 검토: 불필요한 리렌더, N+1 쿼리, 메모이제이션"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "보안 검토: 타입 안정성, 입력 검증, 인증/인가 로직"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "가독성 검토: 명명 규칙, 함수 길이, 주석 품질"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "유지보수성 검토: 테스트 커버리지, 의존성 관리, 확장성"
-})
-```
-
-#### 5-1. 리팩토링 후 보안 + 빌드 검증 병렬
-
-```typescript
-// ✅ 리팩토링 후 보안 + 빌드 검증 병렬
-Task({
-  subagent_type: "security-reviewer",
-  model: "opus",
-  prompt: "리팩토링 후 보안 취약점 검토"
-})
-
-Task({
-  subagent_type: "build-fixer",
-  model: "sonnet",
-  prompt: "리팩토링으로 발생한 빌드/타입 오류 수정"
-})
-```
-
-#### 6. 점진적 마이그레이션 병렬화
-
-```typescript
-// ✅ 레거시 + 신규 시스템 공존 리팩토링
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "새 인증 시스템 구현 (기존과 독립)"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "레거시 API 어댑터 구현 (호환성 유지)"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "haiku",
-  prompt: "Feature flag 설정 및 점진적 전환 로직"
-})
-
-Task({
-  subagent_type: "document-writer",
-  model: "sonnet",
-  prompt: "마이그레이션 플랜 및 롤백 가이드 작성"
-})
-```
-
-### Model Routing (복잡도별)
-
-| 복잡도 | 리팩토링 유형 | Model | Agent | 예시 |
-|--------|--------------|-------|-------|------|
-| **LOW** | 단순 개선 | haiku | implementation-executor | 변수명 변경, 코드 포맷팅, 주석 정리 |
-| **MEDIUM** | 일반 리팩토링 | sonnet | implementation-executor, refactor-advisor | 함수 분리, 중복 제거, 타입 개선 |
-| **HIGH** | 복잡한 구조 변경 | opus | architect, code-reviewer | 아키텍처 재설계, 모듈 분리, 디자인 패턴 적용 |
-
-**Agent별 모델 선택 원칙:**
-
-| Agent | 권장 모델 | 이유 |
-|-------|----------|------|
-| **architect** | **opus** | 아키텍처 분석은 높은 사고력 필요 |
-| **implementation-executor** | **sonnet** | 균형 잡힌 품질/속도 (haiku: 단순 작업) |
-| **code-reviewer** | **opus** | 품질 검증은 세밀한 분석 필요 |
-| **refactor-advisor** | **sonnet** | 계획 수립은 중간 복잡도 |
-| **explore** | **haiku** | 단순 탐색은 빠른 응답 우선 |
-| **analyst** | **sonnet** | 메트릭 분석은 중간 복잡도 |
-| **document-writer** | **haiku/sonnet** | 간단한 문서는 haiku, 상세 문서는 sonnet |
-
-### 병렬 실행 전략
-
-#### 언제 병렬 실행하는가
-
-| 조건 | 병렬 실행 | 순차 실행 |
-|------|----------|----------|
-| **독립성** | ✅ 서로 다른 파일/모듈 | ❌ 같은 파일 수정 |
-| **의존성** | ✅ 의존성 없음 | ❌ 순차 의존성 있음 |
-| **작업 유형** | ✅ 읽기 전용 (분석/탐색) | ❌ 결과가 다음 입력 |
-| **컨텍스트** | ✅ 독립 컨텍스트 | ❌ 공유 컨텍스트 필요 |
-
-#### 병렬 실행 체크리스트
-
-실행 전 확인:
-
-```text
-- [ ] 이 작업들은 독립적인가? (서로 다른 파일/모듈)
-- [ ] 순차 의존성이 없는가? (A 결과 → B 입력 아님)
-- [ ] 같은 파일을 동시에 수정하지 않는가?
-- [ ] 컨텍스트 분리가 가능한가? (각 에이전트가 독립적으로 작업)
-- [ ] 적절한 모델을 선택했는가? (복잡도에 맞게)
-```
-
-**모든 항목 ✅ → 병렬 실행 / 하나라도 ❌ → 순차 실행**
-
-### 실전 시나리오
-
-#### 시나리오 1: 레거시 → 최신 프레임워크 전환
-
-**배경:** 레거시 React 클래스 컴포넌트를 TanStack Start로 전환
-
-```typescript
-// 1단계: 분석 (병렬)
-Task({
-  subagent_type: "architect",
-  model: "opus",
-  prompt: "레거시 아키텍처 분석 및 TanStack Start 전환 전략"
-})
-
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "레거시 컴포넌트 목록 및 의존성 파악"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "전환 리스크 분석: 상태 관리, 라우팅, 데이터 페칭 차이점"
-})
-
-// 2단계: 점진적 전환 (병렬 - 독립 컴포넌트)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Profile 페이지 전환: createFileRoute + Server Functions"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Settings 페이지 전환: createFileRoute + Server Functions"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Dashboard 페이지 전환: createFileRoute + Server Functions"
-})
-
-// 3단계: 검증 + 문서 (병렬)
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "전환된 코드 품질 검증: 라우팅, 상태, 데이터 페칭"
-})
-
-Task({
-  subagent_type: "document-writer",
-  model: "sonnet",
-  prompt: "마이그레이션 가이드 작성: 패턴 비교, 주의사항, 롤백 절차"
-})
-```
-
-#### 시나리오 2: 아키텍처 개선 (모놀리식 → 레이어드)
-
-**배경:** 모든 로직이 혼재된 파일을 레이어드 아키텍처로 분리
-
-```typescript
-// 1단계: 현재 상태 분석 (병렬)
-Task({
-  subagent_type: "architect",
-  model: "opus",
-  prompt: "현재 아키텍처 문제점 분석: 순환 의존성, 결합도, 테스트 어려움"
-})
-
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "모듈 간 의존성 그래프 생성 및 순환 의존성 식별"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "복잡도 메트릭 분석: 파일 크기, 함수 길이, 중첩 깊이"
-})
-
-// 2단계: 레이어 분리 계획
-Task({
-  subagent_type: "refactor-advisor",
-  model: "sonnet",
-  prompt: "레이어드 아키텍처 전환 계획: Presentation → Service → Domain → Data"
-})
-
-// 3단계: 레이어별 구현 (순차적 - 의존성 있음)
-// 먼저 Domain Layer (의존성 없음)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Domain Layer 분리: 엔티티, Value Object, 비즈니스 로직"
-})
-
-// 이후 상위 레이어 (병렬 가능)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Data Layer 구현: Repository, Prisma 연동"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Service Layer 구현: 비즈니스 로직 조율, 트랜잭션 관리"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Presentation Layer 구현: Server Functions, 입력 검증"
-})
-
-// 4단계: 다중 관점 검증 (병렬)
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "아키텍처 검증: 레이어 분리 원칙 준수, 의존성 방향"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "테스트 용이성 검증: 단위 테스트 가능성, Mock 필요성"
-})
-```
-
-#### 시나리오 3: 성능 최적화 리팩토링
-
-**배경:** 느린 렌더링, N+1 쿼리 문제 해결
-
-```typescript
-// 1단계: 성능 문제 분석 (병렬)
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "성능 병목 지점 분석: React Profiler 데이터, DB 쿼리 로그"
-})
-
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "불필요한 리렌더 발생 컴포넌트 탐색"
-})
-
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "N+1 쿼리 발생 지점 탐색 (Prisma 쿼리 분석)"
-})
-
-// 2단계: 최적화 실행 (병렬 - 독립 영역)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "React 최적화: useMemo, useCallback, React.memo 적용"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "Prisma 쿼리 최적화: include 정리, select 최소화, 배치 쿼리"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "TanStack Query 최적화: 캐싱 전략, staleTime/cacheTime 조정"
-})
-
-// 3단계: 성능 검증 (병렬)
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "성능 개선 검증: 렌더 횟수, 쿼리 실행 시간, 번들 크기"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "Before/After 메트릭 비교: 응답 시간, 메모리 사용량"
-})
-
-Task({
-  subagent_type: "document-writer",
-  model: "haiku",
-  prompt: "성능 최적화 가이드 작성: 적용 패턴, 측정 방법"
-})
-```
-
-#### 시나리오 4: 타입 안정성 개선 (any 제거)
-
-**배경:** 프로젝트 전반에 any 타입 남용, 런타임 에러 빈발
-
-```typescript
-// 1단계: any 사용 분석 (병렬)
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "any 타입 사용 지점 전수 조사 (ast-grep 활용)"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "any 사용 우선순위 분석: 영향 범위, 수정 난이도"
-})
-
-Task({
-  subagent_type: "architect",
-  model: "opus",
-  prompt: "타입 설계 개선 방향: Generic, Utility Types, Type Guards"
-})
-
-// 2단계: 타입 정의 개선 (병렬 - 독립 모듈)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "API 응답 타입 정의: Zod 스키마 → TypeScript 타입"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "이벤트 핸들러 타입 정의: React.MouseEvent, React.ChangeEvent"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "유틸리티 함수 타입 정의: Generic, Overload"
-})
-
-// 3단계: 타입 안정성 검증 (병렬)
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "타입 안정성 검토: unknown vs any, Type Guards 필요성"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "타입 에러 검증: tsc --noEmit, 런타임 에러 가능성"
-})
-```
-
-#### 시나리오 5: 코드 중복 제거 (DRY 원칙)
-
-**배경:** 여러 파일에 유사한 로직 반복, 유지보수 어려움
-
-```typescript
-// 1단계: 중복 패턴 분석 (병렬)
-Task({
-  subagent_type: "explore",
-  model: "haiku",
-  prompt: "중복 코드 패턴 탐색: 유사 함수, 중복 로직 (jscpd 등 활용)"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "중복률 분석 및 우선순위: 중복 라인 수, 파일 개수, 수정 빈도"
-})
-
-// 2단계: 공통 모듈 추출 계획
-Task({
-  subagent_type: "refactor-advisor",
-  model: "sonnet",
-  prompt: "공통 모듈 추출 전략: 유틸리티 vs 훅 vs 컴포넌트"
-})
-
-// 3단계: 모듈 추출 및 교체 (병렬 - 독립 영역)
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "공통 유틸리티 함수 추출: src/lib/utils/ 구성"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "커스텀 훅 추출: src/hooks/ 구성"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "sonnet",
-  prompt: "공통 UI 컴포넌트 추출: src/components/ui/ 구성"
-})
-
-// 4단계: 기존 코드 교체 (병렬 - 독립 파일)
-Task({
-  subagent_type: "implementation-executor",
-  model: "haiku",
-  prompt: "components/ 내 중복 코드 → 공통 모듈 참조로 교체"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "haiku",
-  prompt: "routes/ 내 중복 코드 → 공통 모듈 참조로 교체"
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "haiku",
-  prompt: "functions/ 내 중복 코드 → 공통 모듈 참조로 교체"
-})
-
-// 5단계: 검증 (병렬)
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",
-  prompt: "중복 제거 검증: 기존 기능 유지, 새로운 중복 발생 여부"
-})
-
-Task({
-  subagent_type: "analyst",
-  model: "sonnet",
-  prompt: "Before/After 중복률 측정: 개선 효과 정량화"
-})
-```
-
-### 병렬 실행 시 주의사항
-
-```text
-✅ 권장:
-- 독립적인 모듈/파일 → 병렬 실행
-- 분석 작업 (읽기 전용) → 병렬 실행
-- 다중 관점 검증 → 병렬 실행
-- 테스트 + 문서 작성 → 병렬 실행
-- 레거시 + 신규 시스템 공존 → 병렬 실행
-
-❌ 금지:
-- 같은 파일 동시 수정 (충돌 발생)
-- 순차 의존성 있는 작업 병렬화 (A → B → C)
-- 공유 상태/컨텍스트 필요한 작업
-- 결과가 다음 작업의 입력인 경우
-```
-
-### Model 선택 가이드
-
-```typescript
-// ✅ 적절한 모델 선택
-Task({
-  subagent_type: "implementation-executor",
-  model: "haiku",        // 단순 작업: 변수명 변경, 주석 정리
-  prompt: "변수명을 camelCase로 통일"
-})
-
-Task({
-  subagent_type: "refactor-advisor",
-  model: "sonnet",       // 일반 작업: 함수 분리 계획, 중복 제거
-  prompt: "함수 복잡도 감소 계획 수립"
-})
-
-Task({
-  subagent_type: "architect",
-  model: "opus",         // 복잡한 작업: 아키텍처 재설계
-  prompt: "레이어드 아키텍처 전환 전략 분석"
-})
-
-Task({
-  subagent_type: "code-reviewer",
-  model: "opus",         // 품질 검증: 세밀한 검토 필요
-  prompt: "리팩토링 후 보안/성능/가독성 종합 검토"
-})
-
-// ❌ 잘못된 모델 선택
-Task({
-  subagent_type: "architect",
-  model: "haiku",        // 복잡한 작업에 haiku 사용 금지
-  prompt: "아키텍처 재설계..."
-})
-
-Task({
-  subagent_type: "implementation-executor",
-  model: "opus",         // 단순 작업에 opus 낭비
-  prompt: "변수명 변경..."
-})
-```
+@../../instructions/agent-patterns/delegation-patterns.md
+@../../instructions/agent-patterns/parallel-execution.md
+@../../instructions/agent-patterns/model-routing.md
 
-### 병렬 실행 최적화 팁
+### Refactor 스킬 고유 패턴
 
-| 팁 | 설명 | 예시 |
-|----|------|------|
-| **독립성 우선** | 의존성 없는 작업부터 병렬 실행 | 여러 모듈 동시 리팩토링 |
-| **읽기 병렬화** | 분석/탐색 작업은 항상 병렬 | architect + explore + analyst |
-| **쓰기 격리** | 파일 수정은 충돌 없도록 분리 | 각 모듈별로 다른 executor |
-| **검증 병렬화** | 다중 관점 코드 리뷰 동시 실행 | 성능/보안/가독성/유지보수성 |
-| **문서 병렬화** | 리팩토링과 문서 작성 동시 진행 | implementation + document-writer |
-| **모델 적정화** | 복잡도에 맞는 모델 선택 | haiku(단순) / sonnet(일반) / opus(복잡) |
+- **코드 분석 병렬화**: refactor-advisor + architect 에이전트로 코드 구조 분석과 아키텍처 검토를 동시 실행
+- **영향도 평가**: 여러 리팩토링 옵션에 대해 code-reviewer 에이전트로 각각 영향도를 병렬 평가
+- **구현 + 검증 분리**: implementation-executor로 리팩토링 실행, deployment-validator로 동시에 기존 테스트 검증
 
 </parallel_agent_execution>