@kood/claude-code 0.5.1 → 0.5.3

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

@@ -8,6 +8,12 @@ metadata:
   adapted_for: tanstack-start
 ---
 
+@../../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
+
 # TanStack Start React 베스트 프랙티스
 
 React와 TanStack Start 애플리케이션 성능 최적화 가이드. 7개 카테고리, 38개 규칙 포함. 영향도별 우선순위로 자동 리팩토링과 코드 생성 가이드 제공.
@@ -30,6 +36,149 @@ React와 TanStack Start 애플리케이션 성능 최적화 가이드. 7개 카
 
 ---
 
+<parallel_agent_execution>
+
+## 병렬 에이전트 실행
+
+**ULTRAWORK MODE:** TanStack Start 최적화 작업 시 여러 규칙을 동시에 적용하여 5-15배 성능 향상.
+
+### 기본 원칙
+
+| 원칙 | 실행 방법 | 효과 |
+|------|----------|------|
+| **PARALLEL** | 독립 작업을 단일 메시지에서 동시 실행 | 5-15배 속도 향상 |
+| **DELEGATE** | 전문 에이전트에게 즉시 위임 | 품질 향상, 컨텍스트 격리 |
+| **SMART MODEL** | 복잡도별 모델 선택 (haiku/sonnet/opus) | 비용 최적화 |
+
+### Phase별 에이전트 활용
+
+| Phase | 작업 | 에이전트 | 병렬 실행 |
+|-------|------|---------|----------|
+| **1. 코드베이스 분석** | 라우트 구조, Server Functions, 컴포넌트 파악 | explore (haiku) | ✅ 여러 도메인 동시 탐색 |
+| **2. 규칙 적용** | waterfall 제거, 번들 최적화, re-render 최적화 | implementation-executor (sonnet) | ✅ 독립 라우트/컴포넌트 동시 수정 |
+| **3. 검증** | typecheck/lint/build, 성능/보안 리뷰 | lint-fixer (sonnet), code-reviewer (opus) | ❌ lint-fixer 순차, code-reviewer 병렬 |
+| **4. 완료** | git commit | git-operator (sonnet) | ❌ 순차 |
+
+### 에이전트별 역할
+
+| 에이전트 | 모델 | TanStack Start 작업 | 병렬 실행 |
+|---------|------|---------------------|----------|
+| **explore** | haiku | 라우트/Server Functions/컴포넌트 구조 분석 | ✅ |
+| **implementation-executor** | sonnet | 규칙 적용 (async-parallel, bundle-lazy-routes 등) | ✅ |
+| **code-reviewer** | opus | 성능/보안 검토 (server-cache-lru, client-tanstack-query) | ✅ |
+| **lint-fixer** | sonnet | tsc/eslint 에러 자동 수정 | ❌ (순차) |
+
+### 실전 패턴
+
+#### 패턴 1: 독립 라우트 병렬 최적화
+
+```typescript
+// 시나리오: 여러 라우트에 async-parallel, bundle-lazy-routes 적용
+
+// ❌ 순차 실행 (느림)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="/posts 라우트 최적화: async-parallel, bundle-lazy-routes")
+// 60초 대기
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="/users 라우트 최적화: async-parallel, bundle-lazy-routes")
+// 총 120초
+
+// ✅ 병렬 실행 (빠름)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`/posts 라우트 최적화:
+     - async-parallel: loader에서 Promise.all()
+     - bundle-lazy-routes: 무거운 컴포넌트 lazy()`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`/users 라우트 최적화:
+     - async-parallel: loader에서 Promise.all()
+     - bundle-lazy-routes: 무거운 컴포넌트 lazy()`)
+// 총 60초 (가장 긴 작업 기준)
+```
+
+#### 패턴 2: Server Function + UI 동시 구현
+
+```typescript
+// 시나리오: 새 기능 추가 (API + UI + 테스트)
+
+// ✅ Fan-Out: 병렬 실행
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`createServerFn으로 Comment API 구현:
+     - getComments (GET)
+     - createComment (POST + inputValidator)
+     - server-parallel-fetching 적용`)
+
+Task(subagent_type="designer", model="sonnet",
+     prompt=`Comment UI 구현:
+     - client-tanstack-query 사용
+     - rerender-memo로 최적화
+     - bundle-barrel-imports 준수 (직접 import)`)
+
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`Comment 통합 테스트:
+     - API 테스트
+     - UI 테스트`)
+
+// Fan-In: 결과 수집 후 통합
+Read("functions/comments.ts")
+Read("components/Comments.tsx")
+Read("tests/comments.test.ts")
+```
+
+#### 패턴 3: 대규모 리팩토링 (배치 처리)
+
+```typescript
+// 시나리오: 10개 컴포넌트에 rerender-memo, rerender-dependencies 적용
+
+// ✅ 배치 처리 (토큰 70-90% 절감)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`다음 컴포넌트들에 re-render 최적화 적용:
+
+     파일 목록:
+     - components/UserList.tsx
+     - components/PostList.tsx
+     - ... (10개)
+
+     공통 규칙:
+     1. rerender-memo: 비싼 작업 → React.memo() 추출
+     2. rerender-dependencies: effect 의존성 → 원시값 사용
+     3. rerender-functional-setstate: setState → 함수형 업데이트
+
+     패턴:
+     ❌ setItems([...items, newItem])
+     ✅ setItems(curr => [...curr, newItem])`)
+```
+
+### Model Routing
+
+**원칙:** 작업 복잡도에 따라 모델 선택.
+
+| 복잡도 | 모델 | TanStack Start 작업 예시 | 비용 | 속도 |
+|--------|------|------------------------|------|------|
+| **LOW** | haiku | 라우트 구조 파악, Server Functions 위치 확인 | 💰 | ⚡⚡⚡ |
+| **MEDIUM** | sonnet | async-parallel 적용, bundle-lazy-routes 구현 | 💰💰 | ⚡⚡ |
+| **HIGH** | opus | 아키텍처 설계, server-cache-lru 전략, 보안 검토 | 💰💰💰 | ⚡ |
+
+### 체크리스트
+
+**실행 전 확인:**
+
+- [ ] 독립 작업 파악 → 병렬 실행 (여러 라우트, 컴포넌트)
+- [ ] 10개 이상 유사 작업 → 배치 처리 (동일 규칙 적용)
+- [ ] 복잡도별 모델 선택 (탐색=haiku, 구현=sonnet, 리뷰=opus)
+- [ ] Phase별 실행 (분석 → 구현 → 검증 → 완료)
+- [ ] 의존성 확인 (Server Function 완료 후 UI 통합)
+
+**효율 목표:**
+
+- 순차 실행 대비 5-15배 속도 향상
+- 토큰 사용 70-90% 절감 (배치 처리)
+- 병렬도 3-10개 (과도한 병렬 방지)
+
+</parallel_agent_execution>
+
+---
+
 <categories>
 
 ## 카테고리별 우선순위

package/templates/.claude/commands/bug-fix.md

@@ -1,510 +0,0 @@
----
-description: 버그 원인 분석 및 수정. sequential thinking 3-5 + Task (Explore) 필수.
-allowed-tools: Read, Grep, Glob, Task, Edit, Bash(npm:*, yarn:*), mcp__sequential-thinking__sequentialthinking
-argument-hint: <버그 설명 또는 에러 메시지>
----
-
-# Bug Fix Command
-
-> 버그 원인 분석, 수정 옵션 제시, 구현까지 처리하는 커맨드.
-
-**버그 대상**: $ARGUMENTS
-
----
-
-<argument_validation>
-
-## ARGUMENT 필수 확인
-
-```
-$ARGUMENTS 없음 → 즉시 질문:
-
-"어떤 버그를 수정해야 하나요? 구체적으로 알려주세요.
-
-예시:
-- 에러 메시지 및 발생 위치
-- 예상 동작 vs 실제 동작
-- 재현 방법
-- 관련 파일 경로"
-
-$ARGUMENTS 있음 → 다음 단계 진행
-```
-
-</argument_validation>
-
----
-
-<workflow>
-
-## 실행 흐름
-
-| 단계 | 작업 | 도구 |
-|------|------|------|
-| 1. 입력 확인 | ARGUMENT 검증, 없으면 질문 | - |
-| 2. 복잡도 판단 | Sequential Thinking으로 분석 범위 결정 | sequentialthinking (1단계) |
-| 3. 버그 재현 | 에러 재현, 관련 파일 파악 | Read/Grep/Glob |
-| 4. 원인 분석 | Task (Explore)로 관련 코드 탐색 | Task (Explore) |
-| 5. 옵션 도출 | 수정 방법 2-3개 도출 | sequentialthinking (2-4단계) |
-| 6. 옵션 제시 | 장단점, 영향 범위 제시 | - |
-| 7. 사용자 선택 | 수정 방법 선택 대기 | - |
-| 8. 구현 | 선택된 방법으로 코드 수정 | Edit |
-| 9. 검증 | 테스트 실행, 빌드 확인 | Bash |
-
-</workflow>
-
----
-
-<thinking_strategy>
-
-## Sequential Thinking 가이드
-
-### 복잡도 판단 (thought 1)
-
-```
-thought 1: 복잡도 판단
-- 에러 유형: syntax/runtime/logic/type
-- 영향 범위: 단일 파일 vs 다중 파일
-- 의존성: 외부 라이브러리, API 연동
-- 재현 가능성: 항상 발생 vs 간헐적
-```
-
-### 복잡도별 전략
-
-| 복잡도 | 사고 횟수 | 판단 기준 | 사고 패턴 |
-|--------|----------|----------|------------|
-| **간단** | 3 | 명확한 에러, 1-2 파일 | 복잡도 판단 → 원인 분석 → 수정 방법 |
-| **보통** | 5 | 논리 오류, 3-5 파일 | 복잡도 판단 → 재현 → 원인 분석 → 옵션 비교 → 추천안 |
-| **복잡** | 7+ | 간헐적 오류, 다중 모듈 | 복잡도 판단 → 재현 시도 → 심층 분석 → 옵션 탐색 → 비교 → 추천안 |
-
-### 보통 복잡도 패턴 (5단계)
-
-```
-thought 1: 복잡도 판단 및 분석 범위
-thought 2: 버그 재현 및 에러 메시지 분석
-thought 3: 관련 코드 탐색 및 원인 파악
-thought 4: 수정 방법 2-3개 비교 분석
-thought 5: 최종 추천안 및 근거
-```
-
-### 핵심 원칙
-
-```text
-✅ 사고 과정을 출력해야 실제로 생각이 일어남
-✅ 복잡도가 불확실하면 높게 책정 (3→5로 확장 가능)
-✅ 각 thought에서 구체적 분석 필요 (추상적 설명 금지)
-✅ 필요 시 isRevision으로 이전 사고 수정
-```
-
-</thinking_strategy>
-
----
-
-<exploration>
-
-## Task (Explore) 활용
-
-### 탐색 전략
-
-| 버그 유형 | 탐색 대상 | prompt 예시 |
-|----------|----------|-------------|
-| **타입 에러** | 타입 정의, 사용처 | "타입 X 정의 위치 및 사용 파일 탐색" |
-| **런타임 에러** | 함수 호출 체인 | "함수 Y 호출 경로 및 관련 파일" |
-| **논리 오류** | 상태 관리, 데이터 흐름 | "상태 Z 변경 위치 및 영향 범위" |
-| **API 에러** | 엔드포인트, 요청/응답 | "API /path 관련 코드 구조" |
-
-### Task 호출 패턴
-
-**단일 탐색:**
-
-```typescript
-Task({
-  subagent_type: 'Explore',
-  description: '에러 관련 코드 탐색',
-  prompt: `
-    에러 발생 관련 코드 구조 파악:
-    - 에러가 발생하는 정확한 위치
-    - 관련 함수/컴포넌트
-    - 의존하는 모듈/라이브러리
-    - 최근 수정 이력 (git blame)
-  `
-})
-```
-
-**병렬 탐색 (복잡한 경우):**
-
-```typescript
-// 단일 메시지에 다중 Task 호출
-Task({
-  subagent_type: 'Explore',
-  prompt: '프론트엔드 에러 발생 컴포넌트 분석'
-})
-
-Task({
-  subagent_type: 'Explore',
-  prompt: '백엔드 API 엔드포인트 분석'
-})
-
-Task({
-  subagent_type: 'Explore',
-  prompt: '타입 정의 및 인터페이스 분석'
-})
-
-// → 결과 취합 후 원인 파악
-```
-
-### 탐색 체크리스트
-
-```text
-✅ 에러 발생 정확한 위치
-✅ 관련 함수/클래스/컴포넌트
-✅ 데이터 흐름 및 상태 변경
-✅ 외부 의존성 (라이브러리, API)
-✅ 최근 변경 사항 (git log/blame)
-```
-
-</exploration>
-
----
-
-<option_presentation>
-
-## 옵션 제시 형식
-
-### 옵션 2-3개 제시
-
-```markdown
-## 버그 분석 결과
-
-**원인:** [원인 설명]
-
-**영향 범위:** [파일 및 모듈 목록]
-
----
-
-### 옵션 1: [수정 방법] (추천)
-
-**수정 내용:**
-- 변경 사항 1
-- 변경 사항 2
-
-| 장점 | 단점 |
-|------|------|
-| 장점 1 | 단점 1 |
-| 장점 2 | 단점 2 |
-
-**수정 파일:**
-- `src/file1.ts:line`
-- `src/file2.ts:line`
-
-**리스크:** 낮음
-
----
-
-### 옵션 2: [수정 방법]
-
-**수정 내용:**
-...
-
-| 장점 | 단점 |
-|------|------|
-| ... | ... |
-
-**수정 파일:**
-...
-
-**리스크:** 중간
-
----
-
-### 옵션 3: [수정 방법] (임시 해결)
-
-**수정 내용:**
-...
-
-**리스크:** 높음 (근본 해결 아님)
-
----
-
-## 추천 및 근거
-
-옵션 1을 추천합니다.
-- 근거 1
-- 근거 2
-
-어떤 옵션으로 수정하시겠습니까? (1/2/3)
-```
-
-</option_presentation>
-
----
-
-<implementation>
-
-## 구현 가이드
-
-### 수정 단계
-
-```
-1. 사용자 옵션 선택 대기
-2. Edit 도구로 코드 수정
-3. 수정 내용 설명
-4. 테스트/빌드 실행 (선택)
-5. 결과 확인
-```
-
-### 수정 후 검증
-
-```bash
-# 타입 체크
-npm run typecheck
-# 또는
-tsc --noEmit
-
-# 테스트 실행
-npm test
-# 또는
-npm test -- <관련 테스트 파일>
-
-# 빌드 확인
-npm run build
-```
-
-### 검증 체크리스트
-
-```text
-✅ 에러 해결 확인
-✅ 기존 기능 영향 없음
-✅ 타입 에러 없음
-✅ 테스트 통과
-✅ 빌드 성공
-```
-
-</implementation>
-
----
-
-<parallel_agent_execution>
-
-## Parallel Agent Execution
-
-### Recommended Agents
-
-| Agent | Model | 용도 |
-|-------|-------|------|
-| **@explore** | haiku/sonnet | 버그 재현 경로 탐색 |
-| **@architect** | sonnet | 버그 원인 분석 및 설계 논의 |
-| **@implementation-executor** | sonnet | 버그 수정 구현 |
-| **@code-reviewer** | haiku | 수정 후 검증 |
-
-### Parallel Execution Patterns
-
-**여러 버그 동시 수정:**
-- 각 버그마다 별도 executor 할당
-- 독립적인 파일/모듈 수정 시 병렬 실행
-
-**탐색 + 분석 병렬:**
-- explore와 architect 동시 실행
-- 재현 경로 파악과 근본 원인 분석을 동시에 진행
-
-**수정 + 문서화 병렬:**
-- executor와 document-writer 동시 실행
-- 코드 수정과 동시에 변경 사항 문서화
-
-### Model Routing
-
-| 복잡도 | 버그 유형 | 모델 |
-|--------|----------|------|
-| **LOW** | 단순 버그 (오타, 명백한 로직 오류) | haiku |
-| **MEDIUM** | 일반 버그 (기능 오작동) | sonnet |
-| **HIGH** | 복잡한 버그 (아키텍처, 성능) | opus |
-
-### Practical Examples
-
-**여러 버그 병렬 수정:**
-
-```typescript
-// ✅ 각 버그를 독립적으로 수정
-Task({
-  subagent_type: 'implementation-executor',
-  model: 'sonnet',
-  prompt: '로그인 버그 수정: src/auth/login.ts에서 토큰 만료 처리 누락'
-})
-
-Task({
-  subagent_type: 'implementation-executor',
-  model: 'sonnet',
-  prompt: '결제 버그 수정: src/payment/checkout.ts에서 금액 계산 오류'
-})
-
-// → 두 버그가 동시에 수정됨
-```
-
-**탐색 + 분석 병렬:**
-
-```typescript
-// ✅ 재현과 분석을 동시에 진행
-Task({
-  subagent_type: 'explore',
-  model: 'haiku',
-  prompt: '간헐적 500 에러 재현 경로 탐색 및 재현 조건 파악'
-})
-
-Task({
-  subagent_type: 'architect',
-  model: 'sonnet',
-  prompt: '500 에러 패턴 분석 및 근본 원인 파악 (로그, 스택 트레이스 기반)'
-})
-
-// → 탐색 결과와 분석 결과를 종합하여 수정 방향 결정
-```
-
-**복잡도별 모델 선택:**
-
-```typescript
-// ✅ LOW: 단순 오타 수정
-Task({
-  subagent_type: 'implementation-executor',
-  model: 'haiku',
-  prompt: 'typo 수정: src/utils/format.ts의 함수명 오타'
-})
-
-// ✅ MEDIUM: 일반 버그 수정
-Task({
-  subagent_type: 'implementation-executor',
-  model: 'sonnet',
-  prompt: '사용자 목록 중복 렌더링 버그 수정'
-})
-
-// ✅ HIGH: 복잡한 성능 이슈
-Task({
-  subagent_type: 'architect',
-  model: 'opus',
-  prompt: 'N+1 쿼리 문제 분석 및 최적화 방안 설계'
-})
-```
-
-</parallel_agent_execution>
-
----
-
-<validation>
-
-## 검증 체크리스트
-
-실행 전 확인:
-
-```text
-✅ ARGUMENT 확인 (없으면 질문)
-✅ Sequential Thinking 최소 3단계
-✅ Task (Explore)로 코드 탐색
-✅ 원인 분석 명확히
-✅ 옵션 최소 2개, 권장 3개
-✅ 각 옵션에 장단점 명시
-✅ 수정 파일 위치 명시 (line 포함)
-```
-
-절대 금지:
-
-```text
-❌ ARGUMENT 없이 분석 시작
-❌ Sequential Thinking 3단계 미만
-❌ 코드 탐색 없이 추측으로 수정
-❌ 옵션 1개만 제시
-❌ 사용자 선택 없이 수정 시작
-❌ 수정 후 검증 생략
-❌ 장단점 없이 수정 방법만 나열
-```
-
-</validation>
-
----
-
-<examples>
-
-## 실전 예시
-
-### 예시 1: 타입 에러
-
-```bash
-사용자: /bug-fix Property 'name' does not exist on type 'User'
-
-1. Sequential Thinking (3단계):
-   thought 1: "타입 에러 - 간단, User 타입 정의 확인"
-   thought 2: "User 타입 및 사용처 탐색 필요"
-   thought 3: "옵션 2개: 타입 정의 수정 vs 사용처 수정"
-
-2. Task 탐색:
-   Task (Explore): "User 타입 정의 위치 및 사용 파일 탐색"
-   → src/types/user.ts, src/components/UserProfile.tsx 파악
-
-3. 원인 분석:
-   User 타입에 name 속성 누락
-
-4. 옵션 제시:
-   옵션 1: User 타입에 name 속성 추가 (추천)
-   - 장점: 근본 해결
-   - 단점: 없음
-
-   옵션 2: 사용처에서 name 제거
-   - 장점: 빠른 수정
-   - 단점: 기능 손실
-
-5. 사용자 선택: 1
-
-6. Edit:
-   src/types/user.ts:3
-   + name: string;
-
-7. 검증:
-   npm run typecheck → 성공
-```
-
-### 예시 2: 런타임 에러
-
-```bash
-사용자: /bug-fix Cannot read property 'data' of undefined
-
-1. Sequential Thinking (5단계):
-   thought 1: "런타임 에러 - 보통 복잡도, null/undefined 체크 누락"
-   thought 2: "에러 발생 위치 파악 필요, 스택 트레이스 확인"
-   thought 3: "관련 코드 탐색: API 호출, 데이터 접근 패턴"
-   thought 4: "수정 방법: optional chaining, null 체크, 초기화"
-   thought 5: "optional chaining 추천 - 간결하고 안전"
-
-2. Task 탐색:
-   Task (Explore): "undefined 에러 발생 코드 및 데이터 흐름 분석"
-   → src/hooks/useUserData.ts:15, API 응답 체크 누락
-
-3. 원인 분석:
-   API 응답 실패 시 response가 undefined
-
-4. 옵션:
-   옵션 1: optional chaining 사용 (추천)
-   옵션 2: if 문으로 null 체크
-   옵션 3: try-catch로 감싸기
-
-5. 선택 후 구현 → 검증
-```
-
-### 예시 3: 논리 오류
-
-```bash
-사용자: /bug-fix 사용자 목록이 중복으로 표시됨
-
-1. Sequential Thinking (5단계):
-   thought 1: "논리 오류 - 보통 복잡도, 상태 관리 이슈"
-   thought 2: "리렌더링 또는 데이터 fetch 중복 추측"
-   thought 3: "관련 컴포넌트 및 상태 관리 코드 탐색"
-   thought 4: "옵션: useEffect 의존성 수정, 중복 제거 로직 추가"
-   thought 5: "useEffect 의존성 수정 추천"
-
-2. Task 탐색:
-   Task (Explore): "사용자 목록 렌더링 컴포넌트 및 상태 관리"
-   → UserList.tsx, useEffect 의존성 배열 문제 발견
-
-3. 원인: useEffect 의존성 배열 누락으로 매번 fetch
-
-4. 옵션 제시 → 선택 → 구현 → 검증
-```
-
-</examples>