@kood/claude-code 0.5.0 → 0.5.3

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

@@ -0,0 +1,264 @@
+# Agent Patterns
+
+에이전트 활용 및 협업 패턴 - 효율적인 멀티 에이전트 시스템 운영
+
+---
+
+## 파일 구조
+
+| 파일 | 설명 | 토큰 효율 |
+|------|------|---------|
+| [parallel-execution.md](./parallel-execution.md) | 병렬 실행 패턴 - 독립 작업 동시 처리 | 빠른 결정 |
+| [read-parallelization.md](./read-parallelization.md) | Read 도구 병렬화 - 파일 읽기 최적화 | 67-90% 단축 |
+| [model-routing.md](./model-routing.md) | 모델 라우팅 - haiku/sonnet/opus 선택 | 40-60% 절감 |
+| [agent-coordination.md](./agent-coordination.md) | 에이전트 협업 - 역할 분류 및 패턴 | 체계화된 구조 |
+
+---
+
+## Quick Reference
+
+### 병렬화 기본 원칙
+
+```text
+독립 작업 → 병렬 (단일 메시지)
+의존성 있음 → 순차 (대기 필요)
+```
+
+### 모델 선택 (복잡도)
+
+| 복잡도 | 모델 | 용도 | 예시 |
+|--------|------|------|------|
+| **Low** | haiku | 탐색, 문서, Git | Explore, DocumentWriter |
+| **Med** | sonnet | 구현, 수정, 테스트 | ImplementationExecutor |
+| **High** | opus | 설계, 리뷰, 검증 | Planner, CodeReviewer |
+
+### 에이전트 Tier
+
+```
+Tier 1 [계획/분석] → Tier 2 [실행] → Tier 3 [검증]
+Tier 4 [유틸리티 - 모든 단계에서 사용 가능]
+```
+
+---
+
+## 사용 패턴
+
+### 패턴 1: 분석 → 실행 → 검증 (3단계)
+
+```typescript
+// Step 1: 분석 [병렬]
+Task(analyst, sonnet, "요구사항 분석")
+Task(architect, opus, "아키텍처 설계")
+Task(explore, haiku, "코드 탐색")
+
+// Step 2: 실행 [병렬]
+Task(implementation-executor, sonnet, "기능 구현")
+Task(designer, sonnet, "UI 구현")
+Task(document-writer, haiku, "문서 작성")
+
+// Step 3: 검증 [병렬]
+Task(code-reviewer, opus, "품질 검토")
+Task(deployment-validator, sonnet, "빌드 검증")
+```
+
+### 패턴 2: 탐색 → 분석 → 구현 (병렬 최적화)
+
+```typescript
+// [병렬] Haiku 탐색 (저비용)
+Task(explore, haiku, "인증 구조 분석")
+Task(explore, haiku, "DB 스키마 분석")
+
+// [순차] Sonnet/Opus 분석 (결과 필요)
+Task(analyst, sonnet, "현재 상태 분석")
+
+// [병렬] 구현 (독립)
+Task(implementation-executor, sonnet, "개선 적용")
+```
+
+### 패턴 3: 동시 다발 작업 (Full-Stack)
+
+```typescript
+// 백엔드 + 프론트엔드 + 문서 [병렬]
+Task(implementation-executor, sonnet, "API 구현")
+Task(designer, sonnet, "UI 구현")
+Task(document-writer, haiku, "API 문서")
+```
+
+---
+
+## 체크리스트
+
+### 병렬 실행 전 확인
+
+- [ ] 독립적인 작업인가? (A의 결과가 B의 입력이 아닌가)
+- [ ] 같은 파일 수정하지 않는가?
+- [ ] 순서가 중요하지 않은가?
+- [ ] 각 작업의 컨텍스트 분리 가능한가?
+
+### 모델 선택 전 확인
+
+- [ ] 파일 몇 개 다루는가? (1-3:haiku, 4-10:sonnet, 10+:opus)
+- [ ] 로직 복잡도는? (CRUD:haiku, 일반:sonnet, 아키텍처:opus)
+- [ ] 보안/성능 중요한가? → opus
+- [ ] 비용 효율은? (haiku 먼저 시도)
+
+### 에이전트 위임 기준
+
+위임 필요한 경우:
+- [ ] 작업이 독립적인가?
+- [ ] 새 컨텍스트 필요한가?
+- [ ] 전문 지식 필요한가?
+- [ ] 10분 이상 소요될 예상인가?
+
+위임 불필요:
+- ❌ 간단한 파일 읽기 (직접 Read)
+- ❌ 1-2줄 수정 (직접 Edit)
+- ❌ 단순 Bash 명령
+
+---
+
+## 성능 개선 수치
+
+### Read 병렬화
+
+| 파일 수 | 순차 | 병렬 | 개선율 |
+|--------|------|------|--------|
+| 3개 | 6초 | 2초 | 67% |
+| 5개 | 10초 | 2초 | 80% |
+| 10개 | 20초 | 2초 | 90% |
+
+### 에이전트 협업
+
+| 시나리오 | 순차 | 병렬 | 개선 |
+|---------|------|------|------|
+| 3개 에이전트 | 3T | T | 66% |
+| 5개 에이전트 | 5T | T | 80% |
+
+### 비용 최적화
+
+**기본 전략:** Haiku(탐색) → Sonnet(구현) → Opus(검증)
+
+**예상 절감:** 40-60%
+
+---
+
+## 에이전트 역할 매트릭스
+
+| Agent | 모델 | 주 역할 | READ-ONLY | 병렬 가능 |
+|-------|------|--------|-----------|---------|
+| **planner** | opus | 계획 검증 | ❌ | ⚠️ |
+| **analyst** | sonnet | 요구사항 분석 | ✅ | ✅ |
+| **architect** | sonnet/opus | 아키텍처 분석 | ✅ | ✅ |
+| **implementation-executor** | sonnet | 기능 구현 | ❌ | ✅* |
+| **designer** | sonnet/opus | UI 구현 | ❌ | ✅* |
+| **code-reviewer** | opus | 품질 검토 | ✅ | ✅ |
+| **deployment-validator** | sonnet | 빌드 검증 | ❌ | ⚠️ |
+| **explore** | haiku | 코드 탐색 | ✅ | ✅ |
+| **document-writer** | haiku/sonnet | 문서 작성 | ❌ | ✅* |
+| **git-operator** | haiku | Git 작업 | ❌ | ❌ |
+| **lint-fixer** | sonnet | 오류 수정 | ❌ | ⚠️ |
+| **refactor-advisor** | sonnet | 리팩토링 조언 | ✅ | ✅ |
+| **dependency-manager** | sonnet | 의존성 관리 | ❌ | ⚠️ |
+| **ko-to-en-translator** | haiku | 번역 | ❌ | ✅ |
+
+**범례:** ✅ 완전 가능, ⚠️ 제약 있음, ❌ 불가능
+- *: 다른 파일/도메인 다룰 때만 병렬
+
+---
+
+## 의존성 흐름
+
+### 데이터 의존성
+
+```
+[탐색] (explore, haiku)
+   ↓
+[분석] (analyst/architect, sonnet/opus)
+   ↓
+[구현] (implementation-executor/designer, sonnet) [병렬]
+   ↓
+[검증] (code-reviewer/deployment-validator, opus/sonnet) [병렬]
+   ↓
+[배포] (git-operator, haiku)
+```
+
+### 파일 의존성
+
+- **같은 파일** → 순차 필수
+- **다른 파일** → 병렬 안전
+- **다른 모듈** → 병렬 권장
+- **다른 도메인** (백/프론) → 병렬 필수
+
+---
+
+## 문제 해결
+
+| 상황 | 원인 | 해결책 |
+|------|------|--------|
+| 병렬 작업 충돌 | 같은 파일 수정 | 순차 실행으로 변경 |
+| 느린 성능 | 순차 읽기 | 병렬 읽기로 변경 |
+| 높은 비용 | Opus 과다 사용 | Haiku/Sonnet으로 변경 |
+| 낮은 품질 | Haiku로 복잡 작업 | Sonnet/Opus 상향 |
+| 무한 대기 | 의존성 누락 | 데이터 흐름 재검토 |
+
+---
+
+## 통합 사용법
+
+### 실전 예시: User CRUD API
+
+```typescript
+// Phase 1: 분석 [병렬, 5분]
+Task(analyst, sonnet, "User 요구사항 분석")
+Task(explore, haiku, "현재 User 관련 코드 탐색")
+// → 요구사항 명확화, 구현 전략 수립
+
+// Phase 2: 구현 [병렬, 15분]
+Task(implementation-executor, sonnet, "User API CRUD 구현")
+Task(designer, sonnet, "User 관리 페이지 UI 구현")
+Task(document-writer, haiku, "API 문서 작성")
+// → 백엔드 + 프론트엔드 + 문서 동시 완성
+
+// Phase 3: 검증 [병렬, 10분]
+Task(code-reviewer, opus, "보안/성능 검토")
+Task(deployment-validator, sonnet, "빌드/타입 검증")
+// → 품질 확인
+
+// Phase 4: 배포 [순차, 2분]
+Task(git-operator, haiku, "변경사항 커밋")
+// → 완료
+```
+
+**총 소요 시간:** 약 32분 (순차면 60+분)
+
+---
+
+## References
+
+### 추가 학습
+
+- @parallel-execution.md - 병렬화 상세 규칙
+- @read-parallelization.md - Read 도구 최적화
+- @model-routing.md - 모델 선택 가이드
+- @agent-coordination.md - 에이전트 역할 정의
+
+### 관련 지침
+
+- @instructions/workflow-patterns/
+- @instructions/context-engineering/
+- @instructions/validation/
+
+---
+
+## 요약
+
+**3가지 핵심 원칙:**
+
+1. **병렬화**: 독립 작업은 단일 메시지에서 동시 호출
+2. **모델 선택**: 복잡도별 최적 모델 (haiku→sonnet→opus)
+3. **협업 구조**: Tier 기반 역할 분류 (계획→실행→검증)
+
+**결과:**
+- 성능: 67-90% 시간 단축
+- 비용: 40-60% 절감
+- 품질: 각 전문 에이전트 활용

package/templates/.claude/instructions/agent-patterns/model-routing.md

@@ -0,0 +1,167 @@
+# Model Routing Guide
+
+**목적**: 작업 복잡도에 따라 최적의 모델 선택
+
+## 모델 선택 기준
+
+| 모델 | 복잡도 | 비용 | 속도 | 사용 시점 |
+|------|--------|------|------|----------|
+| **haiku** | LOW | 💰 | 🚀🚀🚀 | 간단한 작업 |
+| **sonnet** | MEDIUM | 💰💰 | 🚀🚀 | 일반 작업 (기본값) |
+| **opus** | HIGH | 💰💰💰 | 🚀 | 복잡한 작업 |
+
+## Haiku 사용 케이스
+
+**특징**: 빠르고 저렴, 단순 작업에 최적
+
+| 작업 유형 | 예시 |
+|----------|------|
+| 파일 탐색 | 코드베이스 구조 분석, 파일 찾기 |
+| 간단한 문서 작성 | README, 상태 문서, 로그 |
+| 번역 | 한글↔영어 문서 번역 |
+| Git 작업 | 커밋, 푸시 (로직 없음) |
+| 단순 검색 | Glob, Grep 작업 |
+
+**복잡도 기준:**
+- 1-3개 파일만 다룸
+- 로직 변경 없음
+- 단순 CRUD
+
+**코드 예시:**
+```typescript
+Task(subagent_type="explore", model="haiku",
+     prompt="프로젝트 구조 분석")
+
+Task(subagent_type="document-writer", model="haiku",
+     prompt="TASKS.md 업데이트")
+
+Task(subagent_type="git-operator", model="haiku",
+     prompt="변경사항 커밋")
+```
+
+## Sonnet 사용 케이스
+
+**특징**: 균형 잡힌 성능, 대부분의 작업에 적합
+
+| 작업 유형 | 예시 |
+|----------|------|
+| 기능 구현 | 새 API 엔드포인트, 컴포넌트 |
+| 버그 수정 | 로직 오류, 타입 에러 |
+| 리팩토링 | 코드 구조 개선 |
+| 코드 분석 | 성능 분석, 패턴 식별 |
+| 테스트 작성 | 단위/통합 테스트 |
+
+**복잡도 기준:**
+- 4-10개 파일 수정
+- 중간 복잡도 로직
+- 일반적인 개발 작업
+
+**코드 예시:**
+```typescript
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="User CRUD API 구현")
+
+Task(subagent_type="designer", model="sonnet",
+     prompt="로그인 폼 UI 구현")
+
+Task(subagent_type="lint-fixer", model="sonnet",
+     prompt="타입 에러 수정")
+```
+
+## Opus 사용 케이스
+
+**특징**: 최고 성능, 복잡하고 중요한 작업
+
+| 작업 유형 | 예시 |
+|----------|------|
+| 아키텍처 설계 | 시스템 구조 설계, 기술 선택 |
+| 보안 검토 | 취약점 분석, 인증/인가 로직 |
+| 복잡한 디버깅 | 다층 스택 이슈, 성능 문제 |
+| 계획 검증 | 구현 계획 승인 (Planner) |
+| 종합 코드 리뷰 | 품질, 보안, 성능 전체 검토 |
+
+**복잡도 기준:**
+- 10개 이상 파일 영향
+- 아키텍처 수준 변경
+- 보안/성능 중요
+
+**코드 예시:**
+```typescript
+Task(subagent_type="planner", model="opus",
+     prompt="인증 시스템 아키텍처 설계")
+
+Task(subagent_type="code-reviewer", model="opus",
+     prompt="보안 취약점 전체 검토")
+
+Task(subagent_type="architect", model="opus",
+     prompt="DB 스키마 설계 분석")
+```
+
+## 복잡도 판단 플로우차트
+
+```
+작업 시작
+    ↓
+파일 수 확인
+    ↓
+1-3개? → haiku
+4-10개? → sonnet
+10개+? → opus
+    ↓
+로직 복잡도 확인
+    ↓
+단순 CRUD? → haiku
+일반 로직? → sonnet
+아키텍처? → opus
+    ↓
+중요도 확인
+    ↓
+보안/성능 중요? → opus
+일반 기능? → sonnet
+문서/탐색? → haiku
+```
+
+## 모델 전환 기준
+
+| 상황 | 조치 |
+|------|------|
+| haiku로 시작했는데 복잡함 발견 | sonnet으로 재시도 |
+| sonnet으로도 해결 안 됨 | opus로 에스컬레이션 |
+| opus 필요했는데 haiku 사용 | 처음부터 다시 (opus) |
+
+## 비용 최적화 전략
+
+1. **탐색은 항상 haiku** (explore 에이전트)
+2. **구현은 기본 sonnet** (implementation-executor)
+3. **검증만 opus** (planner, code-reviewer)
+4. **문서는 haiku** (document-writer)
+
+**예상 비용 절감:** 40-60%
+
+## Agent별 권장 모델
+
+| Agent | 기본 모델 | 복잡할 때 |
+|-------|----------|----------|
+| explore | haiku | haiku (항상) |
+| implementation-executor | sonnet | opus |
+| planner | opus | opus (항상) |
+| code-reviewer | opus | opus (항상) |
+| designer | sonnet | opus |
+| document-writer | haiku | sonnet |
+| git-operator | haiku | haiku (항상) |
+| lint-fixer | sonnet | sonnet |
+| deployment-validator | sonnet | sonnet |
+| architect | sonnet | opus |
+| analyst | sonnet | opus |
+| refactor-advisor | sonnet | opus |
+
+## 체크리스트
+
+에이전트 호출 전 확인:
+
+- [ ] 파일 몇 개 다루는가?
+- [ ] 로직 복잡도는?
+- [ ] 보안/성능이 중요한가?
+- [ ] 비용 대비 효과는?
+
+**적절한 모델 선택 → 비용 절감 + 품질 향상**

package/templates/.claude/instructions/agent-patterns/parallel-execution.md

@@ -0,0 +1,91 @@
+# Parallel Execution Pattern
+
+**목적**: 독립적인 작업을 동시에 수행하여 실행 시간 단축
+
+## 기본 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| **PARALLEL** | 독립 작업은 단일 메시지에서 동시 Tool 호출 |
+| **SEQUENTIAL** | 의존성 있는 작업은 순차 실행 |
+| **DELEGATE** | 전문 에이전트에게 즉시 위임 |
+
+## 병렬화 가능 조건
+
+다음 조건을 **모두** 만족하면 병렬 실행:
+
+- [ ] 작업이 서로 독립적 (A의 결과가 B의 입력이 아님)
+- [ ] 같은 파일을 동시 수정하지 않음
+- [ ] 각 작업의 컨텍스트가 분리 가능
+- [ ] 순서에 관계없이 결과가 동일
+
+## 병렬화 금지 조건
+
+다음 중 **하나라도** 해당하면 순차 실행:
+
+- [ ] A의 결과가 B의 입력으로 필요
+- [ ] 같은 파일을 수정
+- [ ] Git 작업 (commit, push는 항상 순차)
+- [ ] 상태 의존성 (이전 작업의 부작용에 의존)
+
+## 코드 예시
+
+### ❌ 순차 실행 (느림)
+
+```typescript
+Read({ file_path: "file1.ts" })
+// 대기...
+Read({ file_path: "file2.ts" })
+// 대기...
+Read({ file_path: "file3.ts" })
+```
+
+### ✅ 병렬 실행 (빠름)
+
+```typescript
+// 단일 메시지에서 모든 Read 동시 호출
+Read({ file_path: "file1.ts" })
+Read({ file_path: "file2.ts" })
+Read({ file_path: "file3.ts" })
+```
+
+## Agent 병렬 실행
+
+### ❌ 순차 호출
+
+```typescript
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="기능 A 구현")
+// 대기...
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="기능 B 구현")
+```
+
+### ✅ 병렬 호출
+
+```typescript
+// 단일 메시지에서 두 Task 호출
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="기능 A 구현")
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="기능 B 구현")
+```
+
+## 성능 개선
+
+| 시나리오 | 순차 | 병렬 | 개선 |
+|---------|------|------|------|
+| 3개 파일 읽기 | 3N초 | N초 | 67% 단축 |
+| 5개 파일 읽기 | 5N초 | N초 | 80% 단축 |
+| 여러 에이전트 | 합계 | 최대값 | 50-80% 단축 |
+
+## 체크리스트
+
+작업 시작 전 확인:
+
+- [ ] 이 작업은 독립적인가?
+- [ ] 병렬 실행해도 안전한가?
+- [ ] 순서가 중요한가?
+- [ ] 같은 리소스를 공유하는가?
+
+**모든 항목 확인 후 병렬/순차 결정**

package/templates/.claude/instructions/agent-patterns/read-parallelization.md

@@ -0,0 +1,106 @@
+# Read Tool Parallelization
+
+**목적**: 여러 파일을 동시에 읽어 분석 시간 단축
+
+## 핵심 원칙
+
+**독립적인 파일 읽기는 항상 병렬로 실행**
+
+## 언제 병렬화하는가
+
+| 상황 | 병렬화 |
+|------|--------|
+| 3개 이상 파일 읽기 | ✅ 필수 |
+| 서로 다른 디렉토리 파일 | ✅ 권장 |
+| 같은 패턴의 파일들 | ✅ 권장 |
+| 순차 의존성 없음 | ✅ 가능 |
+
+## 코드 패턴
+
+### ❌ 잘못된 패턴 (순차)
+
+```typescript
+Read({ file_path: "src/routes/index.tsx" })
+// 결과 대기...
+Read({ file_path: "src/components/Header.tsx" })
+// 결과 대기...
+Read({ file_path: "src/lib/utils.ts" })
+```
+
+**문제점:**
+- 총 시간 = T1 + T2 + T3
+- 불필요한 대기 시간
+- 컨텍스트 전환 비용
+
+### ✅ 올바른 패턴 (병렬)
+
+```typescript
+// 단일 메시지에서 모든 Read 동시 호출
+Read({ file_path: "src/routes/index.tsx" })
+Read({ file_path: "src/components/Header.tsx" })
+Read({ file_path: "src/lib/utils.ts" })
+```
+
+**장점:**
+- 총 시간 = max(T1, T2, T3)
+- 67-80% 시간 단축
+- 효율적인 리소스 활용
+
+## 실전 시나리오
+
+### 시나리오 1: 프로젝트 구조 분석
+
+```typescript
+// ✅ 여러 설정 파일 동시 읽기
+Read({ file_path: "package.json" })
+Read({ file_path: "tsconfig.json" })
+Read({ file_path: "vite.config.ts" })
+Read({ file_path: ".claude/CLAUDE.md" })
+```
+
+### 시나리오 2: 관련 파일 분석
+
+```typescript
+// ✅ API 구현 + 타입 + 테스트 동시 읽기
+Read({ file_path: "src/functions/user.ts" })
+Read({ file_path: "src/types/user.ts" })
+Read({ file_path: "src/functions/user.test.ts" })
+```
+
+### 시나리오 3: 컴포넌트 패밀리 분석
+
+```typescript
+// ✅ 부모 + 자식 컴포넌트들 동시 읽기
+Read({ file_path: "src/routes/users/index.tsx" })
+Read({ file_path: "src/routes/users/-components/UserList.tsx" })
+Read({ file_path: "src/routes/users/-components/UserCard.tsx" })
+Read({ file_path: "src/routes/users/-hooks/useUsers.ts" })
+```
+
+## 성능 비교
+
+| 파일 수 | 순차 (초) | 병렬 (초) | 개선율 |
+|---------|----------|----------|--------|
+| 3개 | 6 | 2 | 67% |
+| 5개 | 10 | 2 | 80% |
+| 10개 | 20 | 2 | 90% |
+
+**가정**: 각 파일 읽기 2초
+
+## 체크리스트
+
+Read 사용 전 확인:
+
+- [ ] 읽을 파일이 2개 이상인가?
+- [ ] 각 파일이 독립적인가?
+- [ ] 순차적으로 읽어야 할 의존성이 있는가?
+
+**2개 이상 독립 파일 → 무조건 병렬 실행**
+
+## 주의사항
+
+다음 경우는 순차 실행:
+
+- 이전 파일의 내용에 따라 다음 파일 경로가 결정되는 경우
+- 파일 A의 분석 결과가 파일 B 읽기 여부를 결정하는 경우
+- 같은 파일을 여러 번 읽는 경우 (불필요)