@kood/claude-code 0.5.0 → 0.5.3

package/templates/.claude/skills/nextjs-react-best-practices/SKILL.md

@@ -7,6 +7,12 @@ metadata:
   version: "1.0.0"
 ---
 
+@../../instructions/agent-patterns/read-parallelization.md
+@../../instructions/validation/forbidden-patterns.md
+@../../instructions/validation/required-behaviors.md
+@../../instructions/multi-agent/coordination-guide.md
+@../../instructions/multi-agent/execution-patterns.md
+
 # Next.js React 베스트 프랙티스
 
 Vercel에서 관리하는 React와 Next.js 애플리케이션 종합 성능 최적화 가이드. 8개 카테고리, 45개 규칙 포함. 영향도별 우선순위로 자동 리팩토링과 코드 생성 가이드 제공.
@@ -29,6 +35,177 @@ Vercel에서 관리하는 React와 Next.js 애플리케이션 종합 성능 최
 
 ---
 
+<parallel_agent_execution>
+
+## 병렬 에이전트 실행 (ULTRAWORK MODE)
+
+### 기본 원칙
+
+| 원칙 | 실행 방법 | 기대 효과 |
+|------|----------|----------|
+| **PARALLEL** | 단일 메시지에서 여러 Tool 동시 호출 | 5-15배 속도 향상 |
+| **DELEGATE** | 전문 에이전트에게 즉시 위임 | 컨텍스트 격리, 품질 향상 |
+| **SMART MODEL** | 복잡도에 따라 haiku/sonnet/opus 선택 | 비용 최적화 |
+
+**핵심 룰:**
+```typescript
+// ❌ 순차 실행 (느림)
+Task(...) // 60초 대기
+Task(...) // 60초 대기
+// 총 120초
+
+// ✅ 병렬 실행 (빠름)
+Task(...) // 단일 메시지에서
+Task(...) // 동시 호출
+// 총 60초 (가장 긴 작업 기준)
+```
+
+### Phase별 에이전트 활용
+
+| Phase | 작업 | 에이전트 | 모델 | 병렬 실행 |
+|-------|------|---------|------|----------|
+| **1. 코드베이스 분석** | 기존 패턴 탐색 | explore | haiku | ✅ (여러 영역) |
+| **1. 코드베이스 분석** | 성능 이슈 식별 | explore | haiku | ✅ (규칙별) |
+| **2. 규칙 적용** | Waterfall 제거 | implementation-executor | sonnet | ✅ (독립 파일) |
+| **2. 규칙 적용** | 번들 최적화 | implementation-executor | sonnet | ✅ (독립 파일) |
+| **2. 규칙 적용** | Re-render 최적화 | implementation-executor | sonnet | ✅ (독립 파일) |
+| **3. 검증** | 보안 검토 | code-reviewer | opus | ✅ (다중 관점) |
+| **3. 검증** | 성능 검토 | code-reviewer | opus | ✅ (다중 관점) |
+| **4. 수정** | 린트/타입 오류 | lint-fixer | sonnet | ❌ (순차) |
+
+### 에이전트별 역할
+
+| 에이전트 | 모델 | 용도 | 병렬 가능 |
+|---------|------|------|----------|
+| **explore** | haiku | 규칙 위반 코드 탐색, 패턴 분석 | ✅ |
+| **implementation-executor** | sonnet | 규칙 적용, 리팩토링 실행 | ✅ |
+| **code-reviewer** | opus | 성능/보안/접근성 검토 | ✅ |
+| **lint-fixer** | sonnet | 적용 후 오류 수정 | ❌ |
+
+### 실전 패턴
+
+**패턴 1: 독립 파일 병렬 최적화**
+
+```typescript
+// 목표: 여러 컴포넌트에 re-render 최적화 규칙 적용
+
+// ❌ 순차 실행 (느림)
+Edit("ComponentA.tsx", ...) // 대기...
+Edit("ComponentB.tsx", ...) // 대기...
+Edit("ComponentC.tsx", ...) // 대기...
+
+// ✅ 병렬 실행 (빠름)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`ComponentA.tsx에 다음 규칙 적용:
+     - rerender-functional-setstate
+     - rerender-memo
+     - rerender-defer-reads`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`ComponentB.tsx에 다음 규칙 적용:
+     - rerender-functional-setstate
+     - rerender-memo
+     - rerender-defer-reads`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`ComponentC.tsx에 다음 규칙 적용:
+     - rerender-functional-setstate
+     - rerender-memo
+     - rerender-defer-reads`)
+```
+
+**패턴 2: Waterfall 제거 + 번들 최적화 동시**
+
+```typescript
+// 독립적인 카테고리 병렬 처리
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`src/routes/users/ 전체에 Waterfall 제거:
+     - async-parallel: 독립 fetch는 Promise.all()
+     - async-defer-await: await를 실제 사용 지점으로`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`src/components/ 전체에 번들 최적화:
+     - bundle-barrel-imports: lucide-react 직접 import
+     - bundle-dynamic-imports: Chart 컴포넌트 next/dynamic`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`src/lib/ 전체에 서버 성능:
+     - server-cache-react: React.cache()로 중복 제거
+     - server-serialization: 클라이언트 데이터 최소화`)
+```
+
+**패턴 3: 다중 관점 검증**
+
+```typescript
+// 코드 수정 완료 후 병렬 검토
+Task(subagent_type="code-reviewer", model="opus",
+     prompt=`성능 검토:
+     - Waterfall 제거 확인
+     - 불필요한 re-render
+     - N+1 쿼리`)
+
+Task(subagent_type="code-reviewer", model="opus",
+     prompt=`번들 크기 검토:
+     - barrel import 사용 여부
+     - 무거운 라이브러리 dynamic import
+     - tree-shaking 가능 여부`)
+
+Task(subagent_type="code-reviewer", model="opus",
+     prompt=`타입 안정성 검토:
+     - any 사용 금지
+     - 명시적 return type
+     - 타입 가드 적절성`)
+```
+
+**패턴 4: 코드베이스 탐색 병렬**
+
+```typescript
+// 프로젝트 초기 분석 시 여러 영역 동시 탐색
+Task(subagent_type="explore", model="haiku",
+     prompt="Waterfall 패턴 탐색: 순차 await, Promise.all() 누락")
+
+Task(subagent_type="explore", model="haiku",
+     prompt="barrel import 탐색: lucide-react, @radix-ui 등")
+
+Task(subagent_type="explore", model="haiku",
+     prompt="re-render 이슈 탐색: useCallback 의존성, useMemo 누락")
+
+Task(subagent_type="explore", model="haiku",
+     prompt="서버 캐싱 누락: React.cache() 미사용 중복 호출")
+```
+
+### Model Routing
+
+| 복잡도 | 모델 | 작업 예시 | 비용 | 속도 |
+|--------|------|----------|------|------|
+| **LOW** | haiku | 패턴 탐색, 규칙 위반 검색 | 💰 | ⚡⚡⚡ |
+| **MEDIUM** | sonnet | 규칙 적용, 리팩토링 실행 | 💰💰 | ⚡⚡ |
+| **HIGH** | opus | 복잡한 성능 분석, 아키텍처 검토 | 💰💰💰 | ⚡ |
+
+**모델 명시 예시:**
+```typescript
+Task(subagent_type="explore", model="haiku", ...)           // 빠르고 저렴
+Task(subagent_type="implementation-executor", model="sonnet", ...)
+Task(subagent_type="code-reviewer", model="opus", ...)      // 고품질 검토
+```
+
+### 체크리스트
+
+작업 시작 전 확인:
+
+- [ ] 독립적인 파일/컴포넌트 → 병렬 executor 실행
+- [ ] 여러 카테고리 규칙 적용 → 카테고리별 병렬
+- [ ] 코드베이스 탐색 필요 → 영역별 explore 병렬
+- [ ] 다중 관점 검증 필요 → code-reviewer 병렬
+- [ ] 복잡도별 모델 선택 (haiku/sonnet/opus)
+- [ ] 10개 이상 파일 → 배치 처리 고려
+
+**적극적으로 에이전트 활용. 혼자 하지 말 것.**
+
+</parallel_agent_execution>
+
+---
+
 <categories>
 
 ## 카테고리별 우선순위