@kood/claude-code 0.5.1 → 0.5.3

package/templates/.claude/instructions/{parallel-agent-execution.md → multi-agent/execution-patterns.md}

@@ -1,22 +1,18 @@
-# Parallel Agent Execution
+# Multi-Agent Execution Patterns
 
-병렬 에이전트 실행을 통한 성능 최적화 및 작업 효율 극대화.
+병렬 에이전트 실행 및 조정 패턴을 통한 성능 최적화.
 
 ---
 
-<purpose>
+<overview>
 
-**Goal:** 독립적인 작업을 동시에 처리하여 대기 시간 최소화, 처리량 극대화, 비용 절감.
-
-**Core Principle:** 순차 실행 → 병렬 실행으로 5-15배 성능 향상.
-
-</purpose>
+## 목적 및 사용 시점
 
----
+**Goal:** 독립적인 작업을 동시에 처리하여 대기 시간 최소화, 처리량 극대화, 비용 절감.
 
-<when_to_use>
+**Performance:** 순차 실행 → 병렬 실행으로 5-15배 성능 향상.
 
-## 사용 시점
+### 사용 시점
 
 | 상황 | 설명 | 예상 효과 |
 |------|------|----------|
@@ -26,21 +22,7 @@
 | **다중 도메인** | API + UI + 문서 동시 작업 | 전문 에이전트 활용 |
 | **배치 처리** | 여러 아이템 동일 작업 | 토큰 70-90% 절감 |
 
-</when_to_use>
-
----
-
-<core_principles>
-
-## 3대 원칙
-
-| 원칙 | 실행 방법 | 기대 효과 |
-|------|----------|----------|
-| **PARALLEL** | 단일 메시지에서 여러 Tool 동시 호출 | 5-15배 속도 향상 |
-| **BACKGROUND** | 10개 이상 작업 시 `run_in_background=true` | 대기 시간 제거 |
-| **DELEGATE** | 전문 에이전트에게 즉시 위임 | 컨텍스트 격리, 품질 향상 |
-
-</core_principles>
+</overview>
 
 ---
 
@@ -189,52 +171,11 @@ TaskOutput(task_id="...")
 
 ---
 
-<model_routing>
-
-## 스마트 모델 라우팅
-
-**원칙:** 작업 복잡도에 따라 모델 선택, 비용 최적화.
-
-| 복잡도 | 모델 | 작업 예시 | 비용 | 속도 |
-|--------|------|----------|------|------|
-| **LOW** | haiku | 파일 읽기, 정의 조회, 간단한 탐색 | 💰 | ⚡⚡⚡ |
-| **MEDIUM** | sonnet | 기능 구현, 버그 수정, 리팩토링 | 💰💰 | ⚡⚡ |
-| **HIGH** | opus | 아키텍처 설계, 복잡한 디버깅, 보안 | 💰💰💰 | ⚡ |
-
-**에이전트별 권장 모델:**
-
-| 에이전트 | 권장 모델 | 용도 |
-|---------|----------|------|
-| planner | opus | 아키텍처 설계, 계획 검증 |
-| implementation-executor | sonnet | 일반 구현, 버그 수정 |
-| explore | haiku | 코드베이스 탐색 |
-| designer | sonnet/opus | UI/UX 구현 |
-| document-writer | haiku/sonnet | 문서 작성 |
-| deployment-validator | sonnet | typecheck/lint/build |
-| code-reviewer | opus | 코드 리뷰 |
-| lint-fixer | sonnet | tsc/eslint 수정 |
-
-**예시:**
-
-```typescript
-// ✅ 모델 명시
-Task(subagent_type="explore", model="haiku",
-     prompt="프로젝트 구조 분석")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="API 엔드포인트 구현")
-Task(subagent_type="planner", model="opus",
-     prompt="아키텍처 검증")
-```
-
-</model_routing>
-
----
-
-<agent_coordination>
+<coordination_patterns>
 
-## 에이전트 조정 패턴
+## 조정 패턴
 
-### 서브에이전트 패턴 (Subagents Pattern)
+### 패턴 1: 서브에이전트 패턴 (Subagents)
 
 **특징:** 메인 에이전트가 컨텍스트 유지, 서브에이전트는 stateless.
 
@@ -244,11 +185,11 @@ Task(subagent_type="planner", model="opus",
 Task(subagent_type="implementation-executor", model="sonnet",
      prompt="User API 엔드포인트 구현")
 
-// 서브에이전트 2: UI 구현
+// 서브에이전트 2: UI 구현 (동시 실행)
 Task(subagent_type="designer", model="sonnet",
      prompt="User Profile UI 구현")
 
-// 서브에이전트 3: 테스트 작성
+// 서브에이전트 3: 테스트 작성 (동시 실행)
 Task(subagent_type="implementation-executor", model="sonnet",
      prompt="API 통합 테스트 작성")
 ```
@@ -260,29 +201,29 @@ Task(subagent_type="implementation-executor", model="sonnet",
 
 ---
 
-### 순차 파이프라인 (Sequential Pipeline)
+### 패턴 2: 순차 파이프라인 (Sequential Pipeline)
 
 **용도:** 단계별 의존성 있는 작업.
 
 ```typescript
-// Step 1: 분석
+// Step 1: 분석 (haiku)
 Task(subagent_type="explore", model="haiku",
      prompt="기존 인증 로직 분석")
 
-// 분석 결과 기반 Step 2: 구현
+// Step 2: 구현 (sonnet) - Step 1 결과 필요
 Task(subagent_type="implementation-executor", model="sonnet",
      prompt="분석 결과 바탕으로 새 인증 로직 구현")
 
-// Step 3: 검증
+// Step 3: 검증 (sonnet) - Step 2 완료 필요
 Task(subagent_type="deployment-validator", model="sonnet",
-     prompt="구현 완료 후 typecheck/lint/build 검증")
+     prompt="typecheck/lint/build 검증")
 ```
 
-**주의:** 순차 실행 시 각 단계는 이전 단계 완료 필수.
+**주의:** 순차 실행은 의존성이 명확할 때만 사용.
 
 ---
 
-### 라우터/디스패처 패턴 (Router Pattern)
+### 패턴 3: 라우터 패턴 (Router)
 
 **정의:** 중앙 에이전트가 작업 분석 후 전문 에이전트에게 라우팅.
 
@@ -302,344 +243,11 @@ if (taskType === "frontend") {
 
 **활용:** 복잡한 요청을 도메인별로 자동 분배.
 
-</agent_coordination>
-
----
-
-<context_preservation>
-
-## 컨텍스트 보존 전략
-
-### 문제: 병렬 실행 시 컨텍스트 손실
-
-**원인:**
-- 서브에이전트는 독립 컨텍스트
-- 메인 에이전트 컨텍스트와 분리
-- 결과만 전달됨
-
-### 해결책
-
-#### 1. 공유 상태 관리
-
-```typescript
-// ❌ 컨텍스트 손실
-Task(subagent_type="implementation-executor",
-     prompt="모듈 A 구현")
-Task(subagent_type="implementation-executor",
-     prompt="모듈 B 구현")
-// → 서로 모듈 존재 모름
-
-// ✅ 공유 상태 명시
-Task(subagent_type="implementation-executor",
-     prompt=`모듈 A 구현
-
-     공유 상태:
-     - 프로젝트 구조: [설명]
-     - 공통 인터페이스: [설명]
-     - 의존성: [리스트]`)
-
-Task(subagent_type="implementation-executor",
-     prompt=`모듈 B 구현 (모듈 A와 통합)
-
-     공유 상태:
-     - 프로젝트 구조: [설명]
-     - 공통 인터페이스: [설명]
-     - 모듈 A 위치: [경로]`)
-```
-
-#### 2. 문서 기반 컨텍스트
-
-**활용:** 상태 문서 파일로 컨텍스트 공유.
-
-```typescript
-// Step 1: 상태 문서 생성
-Write(".claude/context/project-state.md", `
-# Project State
-
-## Architecture
-- Auth: JWT 기반
-- Database: Prisma + PostgreSQL
-- API: TanStack Start Server Functions
-
-## Modules
-- User: 완료
-- Auth: 진행 중
-- Post: 대기
-`)
-
-// Step 2: 병렬 실행 시 문서 참조
-Task(subagent_type="implementation-executor",
-     prompt="@.claude/context/project-state.md 참조하여 Post 모듈 구현")
-```
-
-#### 3. 컨텍스트 컴팩션 (Context Compaction)
-
-**문제:** 토큰 한계 도달 시 이전 작업 손실.
-
-**해결책:**
-
-```typescript
-// 주기적 요약 및 저장
-Task(subagent_type="document-writer", model="haiku",
-     prompt=`현재까지 작업 요약하여 .claude/context/summary.md에 저장
-
-     포함 내용:
-     - 완료된 작업
-     - 중요 의사결정
-     - 다음 단계`)
-```
-
-**컨텍스트 복구:**
-
-```text
-1. pwd → 작업 디렉토리 확인
-2. Read(".claude/context/summary.md") → 진행 상태 파악
-3. git log --oneline -10 → 최근 작업 확인
-4. 중단 지점부터 재개
-```
-
-#### 4. 핸드오프 (Handoffs)
-
-**정의:** 에이전트 간 명시적 정보 전달.
-
-```typescript
-// Agent A → Agent B 핸드오프
-const resultA = Task(subagent_type="explore", model="haiku",
-     prompt="인증 로직 위치 찾기")
-
-// 결과 명시적 전달
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`인증 로직 수정
-
-     이전 에이전트 결과:
-     ${resultA}
-
-     수정 내용: [...]`)
-```
-
-</context_preservation>
-
----
-
-<error_handling>
-
-## 에러 처리 및 복구
-
-### 원칙
-
-| 전략 | 설명 | 구현 |
-|------|------|------|
-| **Failure Isolation** | 실패 도메인 격리 | 에이전트별 독립 실행 |
-| **Redundancy** | 중요 작업 중복 실행 | 동일 작업 여러 에이전트 |
-| **Circuit Breaker** | 반복 실패 시 중단 | 3회 실패 시 에스컬레이션 |
-| **Monitoring** | 상태 추적 | TaskList, 로그 파일 |
-| **Graceful Degradation** | 부분 실패 허용 | 핵심 작업 우선 완료 |
-
-### 패턴 1: 실패 격리
-
-```typescript
-// ✅ 에이전트별 격리
-try {
-  Task(subagent_type="implementation-executor",
-       prompt="기능 A 구현")
-} catch (error) {
-  // 기능 A 실패해도 B는 계속
-}
-
-Task(subagent_type="implementation-executor",
-     prompt="기능 B 구현")
-```
-
-### 패턴 2: 재시도 전략
-
-```typescript
-// ❌ 무한 재시도
-while (true) {
-  Task(...) // 위험
-}
-
-// ✅ 제한적 재시도
-const maxRetries = 3
-let attempt = 0
-
-while (attempt < maxRetries) {
-  try {
-    Task(subagent_type="implementation-executor", ...)
-    break // 성공 시 탈출
-  } catch (error) {
-    attempt++
-    if (attempt >= maxRetries) {
-      // 에스컬레이션: 더 강력한 모델 사용
-      Task(subagent_type="planner", model="opus",
-           prompt="문제 분석 및 대안 제시")
-    }
-  }
-}
-```
-
-### 패턴 3: 서킷 브레이커
-
-```typescript
-// 에이전트 상태 추적
-const agentFailures = new Map()
-
-function executeWithCircuitBreaker(agentType, prompt) {
-  const failures = agentFailures.get(agentType) || 0
-
-  // 3회 이상 실패 시 차단
-  if (failures >= 3) {
-    console.log(`Circuit breaker: ${agentType} 차단됨`)
-    // 대안 에이전트 사용
-    return Task(subagent_type="alternative-agent", ...)
-  }
-
-  try {
-    const result = Task(subagent_type=agentType, prompt=prompt)
-    agentFailures.set(agentType, 0) // 성공 시 리셋
-    return result
-  } catch (error) {
-    agentFailures.set(agentType, failures + 1)
-    throw error
-  }
-}
-```
-
-### 패턴 4: 모니터링 및 알림
-
-```typescript
-// 작업 상태 추적
-TaskList() // pending/in_progress 작업 확인
-
-// 실패 기록
-Write(".claude/logs/failures.md", `
-## Failure Log
-
-- Time: ${timestamp}
-- Agent: ${agentType}
-- Task: ${taskDescription}
-- Error: ${errorMessage}
-- Retry: ${retryCount}
-`)
-```
-
-### 패턴 5: 분산 복구
-
-```typescript
-// 여러 에이전트로 중복 실행
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="인증 로직 구현 (방법 1)")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="인증 로직 구현 (방법 2)")
-
-// 먼저 완료되거나 더 나은 결과 선택
-```
-
-</error_handling>
-
----
-
-<performance_optimization>
-
-## 성능 최적화
-
-### 최적화 체크리스트
-
-- [ ] 독립 작업 → 병렬 실행
-- [ ] 10개 이상 유사 작업 → 배치 처리
-- [ ] 10분 이상 작업 → 백그라운드 실행
-- [ ] 복잡도별 모델 선택 (haiku/sonnet/opus)
-- [ ] 컨텍스트 크기 모니터링 → 컴팩션
-- [ ] 실패 시 재시도 제한 (3회)
-- [ ] 상태 문서화 (컨텍스트 복구)
-
-### 성능 지표
-
-| 지표 | 목표 | 측정 방법 |
-|------|------|----------|
-| **대기 시간** | 순차 대비 80% 감소 | 시작~완료 시간 |
-| **토큰 사용** | 70-90% 절감 (배치) | API 로그 |
-| **병렬도** | 3-10개 동시 실행 | 활성 에이전트 수 |
-| **성공률** | 95% 이상 | 완료/시도 비율 |
-
-### 안티패턴
-
-| 안티패턴 | 문제 | 올바른 방법 |
-|---------|------|------------|
-| **순차 실행** | 불필요한 대기 | 병렬 실행 |
-| **과도한 병렬** | 컨텍스트 혼란 | 3-10개 제한 |
-| **모델 미스매치** | 비용 낭비 | 복잡도별 선택 |
-| **컨텍스트 미보존** | 작업 손실 | 상태 문서화 |
-| **무한 재시도** | 리소스 낭비 | 3회 제한 |
-
-</performance_optimization>
-
----
-
-<best_practices>
-
-## 모범 사례
-
-### 실행 전 체크
-
-```text
-1. 작업 분석
-   - 독립적인가? → 병렬
-   - 의존적인가? → 순차
-   - 유사한가? → 배치
-
-2. 모델 선택
-   - 간단 → haiku
-   - 일반 → sonnet
-   - 복잡 → opus
-
-3. 컨텍스트 계획
-   - 공유 상태 필요? → 문서화
-   - 컨텍스트 한계? → 컴팩션
-
-4. 에러 처리
-   - 재시도 전략
-   - 대안 계획
-   - 모니터링
-```
-
-### 작업 분해 원칙
-
-| 원칙 | 설명 | 예시 |
-|------|------|------|
-| **Single Responsibility** | 에이전트당 하나의 책임 | explore, implement, review 분리 |
-| **Loose Coupling** | 에이전트 간 최소 의존성 | 공유 상태만 문서로 전달 |
-| **High Cohesion** | 관련 작업 그룹화 | UI 관련 작업 → designer |
-
-### 효율적인 프롬프트
-
-```typescript
-// ❌ 모호한 지시
-Task(subagent_type="implementation-executor",
-     prompt="뭔가 구현해줘")
-
-// ✅ 명확한 지시
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`User API 엔드포인트 구현
-
-     요구사항:
-     - GET /users: 사용자 목록
-     - POST /users: 사용자 생성
-     - 인증: JWT 미들웨어
-     - 검증: Zod 스키마
-
-     기존 패턴:
-     @functions/auth.ts 참조
-
-     예상 결과:
-     - functions/users.ts
-     - 테스트 포함`)
-```
-
-</best_practices>
+</coordination_patterns>
 
 ---
 
-<examples>
+<practical_examples>
 
 ## 실전 예제
 
@@ -808,45 +416,91 @@ while (attempt < maxRetries) {
 }
 ```
 
-</examples>
+</practical_examples>
 
 ---
 
-<references>
+<best_practices>
 
-## 참고 자료
+## 모범 사례
 
-### Anthropic
+### 실행 전 체크리스트
 
-1. [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - 컨텍스트 엔지니어링 원칙
-2. [Multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) - 멀티 에이전트 시스템 사례
-3. [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) - 배치 처리 API
+```text
+1. 작업 분석
+   - 독립적인가? → 병렬
+   - 의존적인가? → 순차
+   - 유사한가? → 배치
 
-### 아키텍처 패턴
+2. 모델 선택
+   - 간단 → haiku
+   - 일반 → sonnet
+   - 복잡 → opus
 
-4. [Multi-Agent Design Patterns (Azure)](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns) - 에이전트 오케스트레이션 패턴
-5. [Multi-Agent Systems (Google ADK)](https://google.github.io/adk-docs/agents/multi-agents/) - 병렬 에이전트 구현
-6. [Multi-Agent Patterns (LangChain)](https://docs.langchain.com/oss/python/langchain/multi-agent) - 서브에이전트, 라우터 패턴
-7. [Agentic AI Patterns (AWS)](https://docs.aws.amazon.com/prescriptive-guidance/latest/agentic-ai-patterns/introduction.html) - 워크플로우 패턴
+3. 컨텍스트 계획
+   - 공유 상태 필요? → 문서화
+   - 컨텍스트 한계? → 컴팩션
 
-### 성능 최적화
+4. 에러 처리
+   - 재시도 전략
+   - 대안 계획
+   - 모니터링
+```
 
-8. [Batch Query Processing (arXiv)](https://arxiv.org/html/2509.02121v1) - 배치 최적화 연구
-9. [Parallel Processing with Claude](https://codesignal.com/learn/courses/exploring-workflows-with-claude-in-typescript/lessons/parallel-processing-with-claude) - 병렬 처리 실습
-10. [AI Agent Performance Optimization](https://www.talktoagent.com/blog/ways-to-optimize-ai-agent-performance) - 9가지 최적화 전략
+### 작업 분해 원칙
 
-### 에러 처리
+| 원칙 | 설명 | 예시 |
+|------|------|------|
+| **Single Responsibility** | 에이전트당 하나의 책임 | explore, implement, review 분리 |
+| **Loose Coupling** | 에이전트 간 최소 의존성 | 공유 상태만 문서로 전달 |
+| **High Cohesion** | 관련 작업 그룹화 | UI 관련 작업 → designer |
 
-11. [Multi-Agent AI Failure Recovery](https://galileo.ai/blog/multi-agent-ai-system-failure-recovery) - 실패 복구 전략
-12. [Exception Handling for AI Agents](https://datagrid.com/blog/exception-handling-frameworks-ai-agents) - 예외 처리 프레임워크
-13. [Multi-Agent Systems Fault Tolerance](https://milvus.io/ai-quick-reference/how-do-multiagent-systems-ensure-fault-tolerance) - 결함 허용
+### 효율적인 프롬프트
 
-### 고급 패턴
+```typescript
+// ❌ 모호한 지시
+Task(subagent_type="implementation-executor",
+     prompt="뭔가 구현해줘")
 
-14. [Fan-Out Fan-In Pattern](https://systemdesignschool.io/fundamentals/fan-out-fan-in) - 분산 처리 패턴
-15. [Context Preservation in Multi-Agent](https://developers.googleblog.com/architecting-efficient-context-aware-multi-agent-framework-for-production/) - 컨텍스트 보존 기법
+// ✅ 명확한 지시
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt=`User API 엔드포인트 구현
 
-</references>
+     요구사항:
+     - GET /users: 사용자 목록
+     - POST /users: 사용자 생성
+     - 인증: JWT 미들웨어
+     - 검증: Zod 스키마
+
+     기존 패턴:
+     @functions/auth.ts 참조
+
+     예상 결과:
+     - functions/users.ts
+     - 테스트 포함`)
+```
+
+### 성능 최적화 체크리스트
+
+- [ ] 독립 작업 → 병렬 실행
+- [ ] 10개 이상 유사 작업 → 배치 처리
+- [ ] 10분 이상 작업 → 백그라운드 실행
+- [ ] 복잡도별 모델 선택 (haiku/sonnet/opus)
+- [ ] 컨텍스트 크기 모니터링 → 컴팩션
+- [ ] 실패 시 재시도 제한 (3회)
+- [ ] 상태 문서화 (컨텍스트 복구)
+
+### 안티패턴
+
+| 안티패턴 | 문제 | 올바른 방법 |
+|---------|------|------------|
+| **순차 실행** | 불필요한 대기 | 병렬 실행 |
+| **과도한 병렬** | 컨텍스트 혼란 | 3-10개 제한 |
+| **모델 미스매치** | 비용 낭비 | 복잡도별 선택 |
+| **컨텍스트 미보존** | 작업 손실 | 상태 문서화 |
+| **무한 재시도** | 리소스 낭비 | 3회 제한 |
+
+</best_practices>
 
 ---
 
@@ -872,3 +526,38 @@ while (attempt < maxRetries) {
 5. 모니터링 → TaskList, 로그
 
 </summary>
+
+---
+
+<references>
+
+## 참고 자료
+
+**관련 문서:**
+- `.claude/instructions/parallel-agent-execution.md` - 병렬 실행 전체 가이드
+- `.claude/PARALLEL_AGENTS.md` - 멀티 에이전트 조정 가이드
+- `.claude/agents/*.md` - 개별 에이전트 스펙
+
+**외부 자료:**
+
+### Anthropic
+1. [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - 컨텍스트 엔지니어링 원칙
+2. [Multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) - 멀티 에이전트 시스템 사례
+3. [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) - 배치 처리 API
+
+### 아키텍처 패턴
+4. [Multi-Agent Design Patterns (Azure)](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns) - 에이전트 오케스트레이션 패턴
+5. [Multi-Agent Systems (Google ADK)](https://google.github.io/adk-docs/agents/multi-agents/) - 병렬 에이전트 구현
+6. [Multi-Agent Patterns (LangChain)](https://docs.langchain.com/oss/python/langchain/multi-agent) - 서브에이전트, 라우터 패턴
+7. [Agentic AI Patterns (AWS)](https://docs.aws.amazon.com/prescriptive-guidance/latest/agentic-ai-patterns/introduction.html) - 워크플로우 패턴
+
+### 성능 최적화
+8. [Batch Query Processing (arXiv)](https://arxiv.org/html/2509.02121v1) - 배치 최적화 연구
+9. [Parallel Processing with Claude](https://codesignal.com/learn/courses/exploring-workflows-with-claude-in-typescript/lessons/parallel-processing-with-claude) - 병렬 처리 실습
+10. [AI Agent Performance Optimization](https://www.talktoagent.com/blog/ways-to-optimize-ai-agent-performance) - 9가지 최적화 전략
+
+### 고급 패턴
+11. [Fan-Out Fan-In Pattern](https://systemdesignschool.io/fundamentals/fan-out-fan-in) - 분산 처리 패턴
+12. [Context Preservation in Multi-Agent](https://developers.googleblog.com/architecting-efficient-context-aware-multi-agent-framework-for-production/) - 컨텍스트 보존 기법
+
+</references>