@kood/claude-code 0.5.0 → 0.5.3

package/templates/.claude/commands/version-update.md

@@ -4,7 +4,8 @@ allowed-tools: Bash, Read, Edit
 argument-hint: <new-version | +1 | +minor | +major>
 ---
 
-@../instructions/git-rules.md
+@../instructions/multi-agent/coordination-guide.md
+@../instructions/multi-agent/execution-patterns.md
 
 # Version Update Command
 
@@ -59,92 +60,196 @@ argument-hint: <new-version | +1 | +minor | +major>
 
 </workflow>
 
-<parallel_agent_execution>
+---
+
+<parallel_execution_critical>
 
-## Recommended Agents
+## ⚠️ CRITICAL: 병렬 작업 패턴
 
-| Agent | Model | 용도 |
-|-------|-------|------|
-| @git-operator | haiku | 버전 커밋 및 태그 |
-| @document-writer | haiku | CHANGELOG 작성 |
-| @code-reviewer | haiku | 변경사항 검토 |
+### 병렬 실행 가능 작업
 
-## Parallel Execution Patterns
+**1. 버전 파일 병렬 탐색:**
 
 ```typescript
-// ✅ 문서 작성 병렬 (독립적 작업)
-Task({
-  subagent_type: "document-writer",
-  model: "haiku",
-  prompt: "CHANGELOG.md에 버전 X.X.X 변경사항 추가"
-})
-Task({
-  subagent_type: "document-writer",
-  model: "haiku",
-  prompt: "README.md 버전 정보 업데이트"
-})
+// ✅ 단일 메시지에서 동시 탐색
+Bash({ command: "fd -t f 'package.json' -E node_modules", description: "Find package.json files" })
+Bash({ command: "rg \"\\.version\\(['\\\"]\" --type ts --type js -l", description: "Find version code" })
+```
 
-// ✅ 검토 + 문서 병렬
-Task({
-  subagent_type: "code-reviewer",
-  model: "haiku",
-  prompt: "버전 업데이트 변경사항 검토"
-})
-Task({
-  subagent_type: "document-writer",
-  model: "haiku",
-  prompt: "CHANGELOG 작성"
-})
+**이렇게 하면:**
+- 2개의 탐색이 동시에 실행됨
+- 총 실행 시간 = max(fd 시간, rg 시간)
+- 순차 실행 대비 약 50% 시간 단축
+
+**2. 버전 파일 병렬 읽기:**
 
-// ❌ Git 작업은 순차 필수
-// 버전 커밋 → 태그 생성 → 푸시 순서 보장
-git commit → git tag → git push
+```typescript
+// ✅ 발견된 파일들 동시 읽기
+Read({ file_path: "./package.json" })
+Read({ file_path: "./packages/core/package.json" })
+Read({ file_path: "./packages/core/src/index.ts" })
 ```
 
-## Model Routing
+**3. 문서 작성 병렬:**
 
-| 복잡도 | 버전 유형 | 모델 | 이유 |
-|--------|----------|------|------|
-| **LOW** | patch (+1) | haiku | 단순 숫자 증가 |
-| **MEDIUM** | minor (+minor) | haiku/sonnet | 기능 추가, 문서 업데이트 |
-| **HIGH** | major (+major) | sonnet | Breaking changes, 마이그레이션 가이드 |
+```typescript
+// ✅ CHANGELOG + README 동시 작성
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'CHANGELOG.md에 버전 X.X.X 변경사항 추가' })
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'README.md 버전 정보 업데이트' })
+```
 
-## Practical Examples
+### 순차 실행 필수 작업
+
+**Git 작업은 반드시 순차로 실행:**
+
+```typescript
+// ❌ Git 병렬 실행 금지
+Task({ prompt: 'git add [files]' })
+Task({ prompt: 'git commit' })  // 충돌 위험!
+
+// ✅ Git 순차 실행
+// 1. git add [files]
+// 2. git commit -m "chore: 버전 X.X.X로 업데이트"
+// 3. git tag vX.X.X
+// 4. git push origin main
+// 5. git push origin vX.X.X
+```
+
+### 병렬 실행 체크리스트
+
+버전 업데이트 전 확인:
+
+- [ ] 파일 탐색을 병렬로 실행하는가? (fd + rg 동시)
+- [ ] 발견된 파일들을 병렬로 읽는가?
+- [ ] 문서 작성을 병렬로 진행하는가? (CHANGELOG + README)
+- [ ] Git 작업은 순차로 진행하는가?
+- [ ] 태그 생성 전 커밋이 완료되었는가?
+
+**모든 항목이 체크되어야 올바른 버전 업데이트입니다.**
+
+### 복잡도별 병렬 패턴
+
+**Patch 버전 (+1):**
+```typescript
+// 간단함 → haiku 병렬
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'CHANGELOG: 버그 수정 내역' })
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'README: 버전 번호 업데이트' })
+```
+
+**Minor 버전 (+minor):**
+```typescript
+// 중간 → haiku/sonnet 병렬
+Task({ subagent_type: 'document-writer', model: 'sonnet',
+       prompt: 'CHANGELOG: 새 기능 문서화' })
+Task({ subagent_type: 'code-reviewer', model: 'haiku',
+       prompt: 'API 변경사항 검토' })
+```
 
+**Major 버전 (+major):**
 ```typescript
-// 패치 버전 (haiku 병렬)
-Task({ subagent_type: "document-writer", model: "haiku",
-       prompt: "CHANGELOG: 버그 수정 내역 추가" })
-Task({ subagent_type: "git-operator", model: "haiku",
-       prompt: "버전 0.1.14 커밋" })
-
-// 마이너 버전 (haiku/sonnet 병렬)
-Task({ subagent_type: "document-writer", model: "sonnet",
-       prompt: "CHANGELOG: 새 기능 문서화" })
-Task({ subagent_type: "code-reviewer", model: "haiku",
-       prompt: "API 변경사항 검토" })
-
-// 메이저 버전 (sonnet 순차)
+// 복잡함 → sonnet 순차
 // 1. Breaking changes 분석 (sonnet)
 // 2. 마이그레이션 가이드 작성 (sonnet)
-// 3. 버전 커밋 (git-operator)
+// 3. 문서화 + 검토 병렬
+// 4. 버전 커밋 (git-operator 순차)
+```
+
+### 실제 버전 업데이트 워크플로우
+
+**Step 1: 병렬 파일 탐색**
+
+```typescript
+// 커맨드 시작 시 즉시 병렬 실행
+Bash({
+  command: "fd -t f 'package.json' -E node_modules",
+  description: "Find all package.json files"
+})
+Bash({
+  command: "rg \"\\.version\\(['\\\"]\" --type ts --type js -l",
+  description: "Find version code files"
+})
 ```
 
-## Git 작업 순서 (순차 필수)
+**Step 2: 병렬 파일 읽기**
+
+```typescript
+// 발견된 파일들 동시 읽기
+Read({ file_path: "./package.json" })
+Read({ file_path: "./packages/core/package.json" })
+Read({ file_path: "./packages/cli/package.json" })
+Read({ file_path: "./packages/core/src/index.ts" })
+```
+
+**Step 3: 새 버전 계산 및 업데이트**
+
+- $ARGUMENTS 분석 (+1, +minor, +major, 또는 직접 버전)
+- 모든 파일 Edit로 업데이트
+
+**Step 4: 병렬 문서 작성**
+
+```typescript
+// 문서 업데이트 동시 진행
+Task({
+  subagent_type: 'document-writer',
+  model: 'haiku',
+  description: 'CHANGELOG 업데이트',
+  prompt: 'CHANGELOG.md에 버전 0.5.2 변경사항 추가'
+})
+Task({
+  subagent_type: 'document-writer',
+  model: 'haiku',
+  description: 'README 버전 업데이트',
+  prompt: 'README.md 설치 섹션 버전 번호 업데이트'
+})
+```
+
+**Step 5: Git 작업 (순차 필수)**
 
 ```bash
-# ✅ 올바른 순서
-1. git add [files]
-2. git commit -m "chore: 버전 X.X.X로 업데이트"
-3. git tag vX.X.X
-4. git push origin main
-5. git push origin vX.X.X
-
-# ❌ 병렬 실행 금지
-# Git 작업은 상태 의존성이 있어 순차 실행 필수
+# 반드시 순차로 실행
+git add package.json packages/*/package.json packages/*/src/index.ts
+git commit -m "chore: 버전 0.5.2로 업데이트"
+git tag v0.5.2
+git push origin main
+git push origin v0.5.2
 ```
 
-</parallel_agent_execution>
+**전체 실행 시간:**
+- 순차: 탐색1(1초) + 탐색2(1초) + 읽기(4초) + 문서1(2초) + 문서2(2초) + git(3초) = 13초
+- 병렬: 탐색(1초) + 읽기(1초) + 문서(2초) + git(3초) = 7초
+- **개선: 46% 시간 단축**
+
+**복잡도별 예시:**
+
+```typescript
+// Patch (+1): 전체 haiku 병렬
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'CHANGELOG: 버그 수정 기록' })
+Task({ subagent_type: 'document-writer', model: 'haiku',
+       prompt: 'README: 버전 0.5.2 표시' })
+// → 총 2초 (병렬)
+
+// Minor (+minor): haiku/sonnet 병렬
+Task({ subagent_type: 'document-writer', model: 'sonnet',
+       prompt: 'CHANGELOG: 새 기능 상세 문서화' })
+Task({ subagent_type: 'code-reviewer', model: 'haiku',
+       prompt: 'API 변경사항 영향도 검토' })
+// → 총 3초 (병렬)
+
+// Major (+major): sonnet 순차 + 병렬 조합
+// 1. Breaking changes 분석 (sonnet, 5초)
+// 2. 마이그레이션 가이드 + 문서 병렬 (sonnet, 4초)
+// 3. git 작업 (3초)
+// → 총 12초
+```
+
+</parallel_execution_critical>
+
+---
 
 <update_targets>
 

package/templates/.claude/instructions/agent-patterns/agent-coordination.md

@@ -0,0 +1,208 @@
+# Agent Coordination Patterns
+
+**목적**: 여러 에이전트 간 효율적인 협업 전략
+
+## 에이전트 역할 분류
+
+### Tier 1: 계획 및 분석
+| Agent | 모델 | 역할 | READ-ONLY |
+|-------|------|------|-----------|
+| planner | opus | 아키텍처 설계, 계획 검증 | ❌ |
+| analyst | sonnet | 요구사항 분석, 가정 검증 | ✅ |
+| architect | sonnet/opus | 아키텍처 분석, 디버깅 조언 | ✅ |
+
+### Tier 2: 실행 및 구현
+| Agent | 모델 | 역할 | READ-ONLY |
+|-------|------|------|-----------|
+| implementation-executor | sonnet | 기능 구현, 버그 수정 | ❌ |
+| designer | sonnet/opus | UI/UX 구현 | ❌ |
+| lint-fixer | sonnet | tsc/eslint 오류 수정 | ❌ |
+
+### Tier 3: 검증 및 지원
+| Agent | 모델 | 역할 | READ-ONLY |
+|-------|------|------|-----------|
+| code-reviewer | opus | 코드 품질/보안 검토 | ✅ |
+| deployment-validator | sonnet | typecheck/lint/build 검증 | ❌ |
+| refactor-advisor | sonnet | 리팩토링 조언 | ✅ |
+
+### Tier 4: 유틸리티
+| Agent | 모델 | 역할 | READ-ONLY |
+|-------|------|------|-----------|
+| explore | haiku | 코드베이스 탐색 | ✅ |
+| document-writer | haiku/sonnet | 기술 문서 작성 | ❌ |
+| git-operator | haiku | Git 커밋/푸시 | ❌ |
+| dependency-manager | sonnet | 의존성 분석/업데이트 | ❌ |
+| ko-to-en-translator | haiku | 한글→영어 번역 | ❌ |
+
+## 협업 패턴
+
+### 패턴 1: 계획 → 실행 → 검증
+
+```typescript
+// 1. 분석 및 계획 (병렬)
+Task(subagent_type="analyst", model="sonnet",
+     prompt="요구사항 분석 및 가정 검증")
+Task(subagent_type="architect", model="opus",
+     prompt="아키텍처 분석 및 설계 조언")
+
+// 2. 구현 (병렬)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="백엔드 API 구현")
+Task(subagent_type="designer", model="sonnet",
+     prompt="프론트엔드 UI 구현")
+
+// 3. 검증 (병렬)
+Task(subagent_type="code-reviewer", model="opus",
+     prompt="보안 및 성능 검토")
+Task(subagent_type="deployment-validator", model="sonnet",
+     prompt="빌드 및 타입 검증")
+```
+
+### 패턴 2: 탐색 → 분석 → 구현
+
+```typescript
+// 1. 탐색 (병렬, haiku)
+Task(subagent_type="explore", model="haiku",
+     prompt="인증 관련 파일 탐색")
+Task(subagent_type="explore", model="haiku",
+     prompt="DB 스키마 분석")
+
+// 2. 분석 (순차, sonnet/opus)
+Task(subagent_type="analyst", model="sonnet",
+     prompt="현재 구조 분석 및 개선 방향")
+
+// 3. 구현 (병렬, sonnet)
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="개선 사항 적용")
+```
+
+### 패턴 3: 동시 다발 작업 (풀스택)
+
+```typescript
+// 백엔드 + 프론트엔드 + 문서 동시 진행
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="User API CRUD 구현")
+Task(subagent_type="designer", model="sonnet",
+     prompt="User Profile UI 구현")
+Task(subagent_type="document-writer", model="haiku",
+     prompt="User API 문서 작성")
+```
+
+### 패턴 4: 다중 검토 (여러 관점)
+
+```typescript
+// 보안 + 성능 + 접근성 동시 검토
+Task(subagent_type="code-reviewer", model="opus",
+     prompt="보안 취약점 검토: XSS, SQL Injection, CSRF")
+Task(subagent_type="code-reviewer", model="opus",
+     prompt="성능 검토: N+1 쿼리, 불필요한 리렌더")
+Task(subagent_type="code-reviewer", model="opus",
+     prompt="접근성 검토: ARIA, 키보드 네비게이션")
+```
+
+## 병렬 vs 순차 결정
+
+| 조건 | 실행 방식 | 이유 |
+|------|----------|------|
+| 독립적인 작업 | ✅ 병렬 | 시간 단축 |
+| 다른 파일/영역 | ✅ 병렬 | 충돌 없음 |
+| 다른 도메인 (백엔드/프론트) | ✅ 병렬 | 완전히 분리 |
+| 순차 의존성 | ❌ 순차 | 이전 결과 필요 |
+| 같은 파일 수정 | ❌ 순차 | 충돌 방지 |
+| Git 작업 | ❌ 순차 | 커밋 순서 중요 |
+
+## 에이전트 위임 원칙
+
+### 언제 위임하는가
+
+- [ ] 작업이 독립적인가?
+- [ ] 새 컨텍스트가 필요한가?
+- [ ] 전문 지식이 필요한가?
+- [ ] 10분 이상 소요될까?
+
+**하나라도 Yes → 에이전트 위임**
+
+### 위임 금지 케이스
+
+- 간단한 파일 읽기 (직접 Read)
+- 1-2줄 수정 (직접 Edit)
+- 즉각적인 Bash 명령어
+
+## READ-ONLY 에이전트 활용
+
+**READ-ONLY 에이전트**: analyst, architect, code-reviewer, refactor-advisor, explore
+
+**특징:**
+- 파일 수정 불가
+- 조언 및 분석만 제공
+- 병렬 실행 안전 (충돌 없음)
+
+**활용 패턴:**
+```typescript
+// 여러 READ-ONLY 에이전트 병렬 실행 (안전)
+Task(subagent_type="analyst", model="sonnet", ...)
+Task(subagent_type="architect", model="opus", ...)
+Task(subagent_type="code-reviewer", model="opus", ...)
+Task(subagent_type="explore", model="haiku", ...)
+```
+
+## 실전 시나리오
+
+### 시나리오 1: 새 기능 구현
+
+```
+Phase 1: 분석 (병렬)
+  ├─ analyst: 요구사항 명확화
+  ├─ architect: 아키텍처 분석
+  └─ explore: 관련 코드 탐색
+
+Phase 2: 구현 (병렬)
+  ├─ implementation-executor: 백엔드
+  ├─ designer: 프론트엔드
+  └─ document-writer: 문서
+
+Phase 3: 검증 (병렬)
+  ├─ code-reviewer: 품질 검토
+  └─ deployment-validator: 빌드 검증
+```
+
+### 시나리오 2: 버그 수정
+
+```
+Phase 1: 조사 (병렬)
+  ├─ explore: 버그 관련 코드 탐색
+  └─ architect: 원인 분석
+
+Phase 2: 수정 (순차)
+  └─ implementation-executor: 버그 수정
+
+Phase 3: 검증 (순차)
+  └─ deployment-validator: 테스트 실행
+```
+
+### 시나리오 3: 리팩토링
+
+```
+Phase 1: 분석 (병렬)
+  ├─ refactor-advisor: 개선 방향 제시
+  ├─ code-reviewer: 현재 문제점 식별
+  └─ explore: 영향 범위 파악
+
+Phase 2: 실행 (순차)
+  └─ implementation-executor: 리팩토링
+
+Phase 3: 검증 (병렬)
+  ├─ code-reviewer: 품질 향상 확인
+  └─ deployment-validator: 회귀 테스트
+```
+
+## 체크리스트
+
+작업 시작 전:
+
+- [ ] 어떤 에이전트가 필요한가?
+- [ ] 병렬 실행 가능한가?
+- [ ] 적절한 모델 선택했는가?
+- [ ] READ-ONLY 제약 확인했는가?
+
+**에이전트 협업으로 시간 단축 + 품질 향상**