@kood/claude-code 0.5.1 → 0.5.4

package/templates/.claude/{PARALLEL_AGENTS.md → instructions/multi-agent/coordination-guide.md}

@@ -6,19 +6,29 @@
 
 <overview>
 
-## 핵심 원칙
+## 목적 및 개요
 
 **Goal:** 독립적인 작업을 동시에 처리하여 대기 시간 최소화, 처리량 극대화, 비용 절감.
 
 **Performance:** 순차 실행 → 병렬 실행으로 5-15배 성능 향상.
 
+### 사용 시점
+
+| 상황 | 설명 | 예상 효과 |
+|------|------|----------|
+| **독립적인 작업** | 서로 의존하지 않는 여러 작업 | 대기 시간 → 동시 실행 시간 |
+| **여러 파일 수정** | 다른 파일 동시 작업 | 순차 작업 → 병렬 처리 |
+| **탐색 + 구현** | 코드베이스 분석 + 기능 구현 | 별도 컨텍스트 활용 |
+| **다중 도메인** | API + UI + 문서 동시 작업 | 전문 에이전트 활용 |
+| **배치 처리** | 여러 아이템 동일 작업 | 토큰 70-90% 절감 |
+
 </overview>
 
 ---
 
 <core_principles>
 
-## 3대 원칙
+## 3대 핵심 원칙
 
 | 원칙 | 실행 방법 | 기대 효과 |
 |------|----------|----------|
@@ -26,7 +36,8 @@
 | **BACKGROUND** | 10개 이상 작업 시 `run_in_background=true` | 대기 시간 제거 |
 | **DELEGATE** | 전문 에이전트에게 즉시 위임 | 컨텍스트 격리, 품질 향상 |
 
-**핵심 룰:**
+### 핵심 룰
+
 ```typescript
 // ❌ 순차 실행 (느림)
 Task(...) // 60초 대기
@@ -49,238 +60,48 @@ Task(...) // 동시 호출
 
 **원칙:** 작업 복잡도에 따라 모델 선택, 비용 최적화.
 
+### 복잡도별 모델 선택
+
 | 복잡도 | 모델 | 작업 예시 | 비용 | 속도 |
 |--------|------|----------|------|------|
 | **LOW** | haiku | 파일 읽기, 정의 조회, 간단한 탐색 | 💰 | ⚡⚡⚡ |
 | **MEDIUM** | sonnet | 기능 구현, 버그 수정, 리팩토링 | 💰💰 | ⚡⚡ |
 | **HIGH** | opus | 아키텍처 설계, 복잡한 디버깅, 보안 | 💰💰💰 | ⚡ |
 
-**모델 명시 예시:**
-```typescript
-Task(subagent_type="explore", model="haiku", ...)      // 빠르고 저렴
-Task(subagent_type="implementation-executor", model="sonnet", ...)
-Task(subagent_type="planner", model="opus", ...)       // 복잡하지만 정확
-```
+### 에이전트별 권장 모델
 
-</model_routing>
-
----
-
-<agent_roster>
-
-## 에이전트 목록
-
-### 계획 및 분석
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
+| 에이전트 | 권장 모델 | 용도 | 병렬 가능 |
+|---------|----------|------|----------|
 | **planner** | opus | 작업 계획 수립, 인터뷰, .claude/plans/ 생성 | ❌ (조정자) |
 | **analyst** | sonnet | 데이터 분석, 패턴 발견 | ✅ |
 | **architect** | opus | 아키텍처 설계, 시스템 디자인 | ❌ (의사결정) |
-
-### 탐색 및 조사
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **explore** | haiku | 코드베이스 빠른 탐색, 파일/패턴 검색 | ✅ |
-
-### 구현
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **implementation-executor** | sonnet | 즉시 구현, 옵션 제시 없이 최적 방법 실행 | ✅ |
 | **designer** | sonnet/opus | UI/UX 구현, 컴포넌트 작성 | ✅ |
-
-### 검증 및 수정
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **deployment-validator** | sonnet | typecheck/lint/build 검증 | ❌ (순차) |
 | **lint-fixer** | sonnet | tsc/eslint 에러 자동 수정 | ✅ |
 | **code-reviewer** | opus | 코드 리뷰, 보안/성능 검토 | ✅ |
-
-### 문서 및 유틸
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **document-writer** | haiku/sonnet | 문서 작성, 주석, README | ✅ |
 | **ko-to-en-translator** | sonnet | 한글 → 영어 번역 (커밋 메시지) | ✅ |
-
-### Git 및 배포
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **git-operator** | sonnet | Git 작업 (commit, branch, merge) | ❌ (순차) |
 | **dependency-manager** | sonnet | package.json 의존성 관리 | ❌ (의존성) |
-
-### 고급
-
-| 에이전트 | 모델 | 용도 | 병렬 가능 |
-|---------|------|------|----------|
 | **refactor-advisor** | opus | 리팩토링 전략 제안 | ❌ (의사결정) |
 
-</agent_roster>
-
----
-
-<coordination_patterns>
-
-## 조정 패턴
-
-### 패턴 1: 서브에이전트 패턴 (Subagents)
-
-**특징:** 메인 에이전트가 컨텍스트 유지, 서브에이전트는 stateless.
-
-```typescript
-// 메인 에이전트: 전체 흐름 조정
-// 서브에이전트 1: API 구현
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="User API 엔드포인트 구현")
-
-// 서브에이전트 2: UI 구현 (동시 실행)
-Task(subagent_type="designer", model="sonnet",
-     prompt="User Profile UI 구현")
-
-// 서브에이전트 3: 테스트 작성 (동시 실행)
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="API 통합 테스트 작성")
-```
-
-**장점:**
-- 컨텍스트 격리 (재귀 위임 방지)
-- 병렬 실행 (독립적인 작업)
-- 재사용 가능 (전문화된 에이전트)
-
----
-
-### 패턴 2: 순차 파이프라인 (Sequential Pipeline)
-
-**용도:** 단계별 의존성 있는 작업.
-
-```typescript
-// Step 1: 분석 (haiku)
-Task(subagent_type="explore", model="haiku",
-     prompt="기존 인증 로직 분석")
-
-// Step 2: 구현 (sonnet) - Step 1 결과 필요
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="분석 결과 바탕으로 새 인증 로직 구현")
-
-// Step 3: 검증 (sonnet) - Step 2 완료 필요
-Task(subagent_type="deployment-validator", model="sonnet",
-     prompt="typecheck/lint/build 검증")
-```
-
-**주의:** 순차 실행은 의존성이 명확할 때만 사용.
-
----
-
-### 패턴 3: 라우터 패턴 (Router)
-
-**정의:** 중앙 에이전트가 작업 분석 후 전문 에이전트에게 라우팅.
-
-```typescript
-// 작업 분석
-const taskType = analyzeTask(userRequest)
-
-// 조건부 라우팅
-if (taskType === "frontend") {
-  Task(subagent_type="designer", model="sonnet", ...)
-} else if (taskType === "backend") {
-  Task(subagent_type="implementation-executor", model="sonnet", ...)
-} else if (taskType === "documentation") {
-  Task(subagent_type="document-writer", model="haiku", ...)
-}
-```
-
-**활용:** 복잡한 요청을 도메인별로 자동 분배.
-
----
-
-### 패턴 4: Fan-Out Fan-In
-
-**정의:** 하나의 작업을 여러 하위 작업으로 분산(Fan-Out) → 결과 수집 및 통합(Fan-In).
-
-```typescript
-// Fan-Out: 여러 컴포넌트 동시 구현
-Task(subagent_type="designer", model="sonnet",
-     prompt="Header 컴포넌트 구현")
-Task(subagent_type="designer", model="sonnet",
-     prompt="Footer 컴포넌트 구현")
-Task(subagent_type="designer", model="sonnet",
-     prompt="Sidebar 컴포넌트 구현")
-
-// Fan-In: 결과 수집 후 통합
-Read("components/Header.tsx")
-Read("components/Footer.tsx")
-Read("components/Sidebar.tsx")
-// → Layout.tsx에 통합
-```
-
-**활용 사례:**
-- 여러 API 엔드포인트 동시 호출
-- 다중 컴포넌트 병렬 구현
-- 배치 데이터 처리
-
----
-
-### 패턴 5: 계층적 위임 (Hierarchical Delegation)
-
-**구조:** 메인 에이전트 → 계획 + 조정, 서브 에이전트 → 실행.
-
-```typescript
-// 메인 에이전트: 계획 수립
-Task(subagent_type="planner", model="opus",
-     prompt="전체 아키텍처 설계 및 작업 분해")
-
-// 서브 에이전트: 병렬 실행
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="Auth 모듈 구현")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="User 모듈 구현")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="Post 모듈 구현")
-```
-
-**장점:**
-- 컨텍스트 격리 (각 에이전트 독립 컨텍스트)
-- 전문화 (도메인별 최적화)
-- 재시도 용이 (실패 시 해당 에이전트만 재실행)
-
----
-
-### 패턴 6: 배치 처리 (Batching)
-
-**원리:** 유사 작업을 묶어서 컨텍스트 공유, 토큰 70-90% 절감.
+**모델 명시 예시:**
 
 ```typescript
-// ❌ 개별 처리 (비효율)
-Edit("file1.ts", ...) // 컨텍스트 전송
-Edit("file2.ts", ...) // 컨텍스트 재전송
-Edit("file3.ts", ...) // 컨텍스트 재전송
-
-// ✅ 배치 처리 (효율)
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`다음 파일들에 동일한 수정 적용:
-     - file1.ts
-     - file2.ts
-     - file3.ts
-
-     수정 내용: [공통 규칙]`)
+Task(subagent_type="explore", model="haiku", ...)      // 빠르고 저렴
+Task(subagent_type="implementation-executor", model="sonnet", ...)
+Task(subagent_type="planner", model="opus", ...)       // 복잡하지만 정확
 ```
 
-**적용 기준:**
-- 10개 이상 유사 작업
-- 공통 컨텍스트 공유 가능
-- 순서 무관
-
-</coordination_patterns>
+</model_routing>
 
 ---
 
 <context_preservation>
 
-## 컨텍스트 보존
+## 컨텍스트 보존 전략
 
 ### 문제: 병렬 실행 시 컨텍스트 손실
 
@@ -406,6 +227,7 @@ Task(subagent_type="document-writer", model="haiku",
 | **Circuit Breaker** | 반복 실패 시 중단 | 3회 실패 시 대안 에이전트 |
 | **Redundancy** | 중요 작업 중복 실행 | 동일 작업 여러 에이전트 |
 | **Graceful Degradation** | 부분 실패 허용 | 핵심 작업 우선 완료 |
+| **Monitoring** | 상태 추적 | TaskList, 로그 파일 |
 
 ### 패턴 1: 실패 격리
 
@@ -498,120 +320,6 @@ Write(".claude/logs/failures.md", `
 
 ---
 
-<examples>
-
-## 실전 예제
-
-### 예제 1: 풀스택 기능 구현
-
-```typescript
-// 목표: User Profile 기능 구현 (API + UI + 테스트)
-
-// ✅ 병렬 실행
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`User Profile API 구현
-
-     - GET /profile: 프로필 조회
-     - PUT /profile: 프로필 수정
-     - 인증 필수
-     - Prisma User 모델 사용`)
-
-Task(subagent_type="designer", model="sonnet",
-     prompt=`User Profile UI 구현
-
-     - 프로필 조회 화면
-     - 수정 폼
-     - TanStack Query 사용
-     - Tailwind 스타일`)
-
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`User Profile 통합 테스트 작성
-
-     - API 테스트
-     - UI 테스트
-     - E2E 시나리오`)
-```
-
-**예상 시간:**
-- 순차 실행: 180초 (60 + 60 + 60)
-- 병렬 실행: 60초 (가장 긴 작업)
-- 개선: 3배 향상
-
----
-
-### 예제 2: 대규모 리팩토링
-
-```typescript
-// 목표: 10개 파일 동일 패턴으로 리팩토링
-
-// ❌ 순차 실행 (비효율)
-Edit("file1.ts", ...)
-Edit("file2.ts", ...)
-// ... (10번 반복)
-
-// ✅ 배치 처리 (효율)
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt=`다음 파일들 리팩토링:
-
-     파일 목록:
-     - file1.ts ~ file10.ts
-
-     공통 규칙:
-     1. const 함수 → arrow function
-     2. any → unknown
-     3. 명시적 return type 추가
-
-     패턴:
-     ❌ function fn() { ... }
-     ✅ const fn = (): ReturnType => { ... }`)
-```
-
-**예상 효과:**
-- 토큰 사용: 70-90% 절감
-- 실행 시간: 단축
-- 일관성: 향상
-
----
-
-### 예제 3: 멀티 스테이지 파이프라인
-
-```typescript
-// Phase 1: 탐색 (병렬)
-Task(subagent_type="explore", model="haiku",
-     prompt="프로젝트 구조 분석")
-Task(subagent_type="explore", model="haiku",
-     prompt="기존 인증 로직 위치")
-Task(subagent_type="explore", model="haiku",
-     prompt="테스트 구조 파악")
-
-// Phase 2: 구현 (병렬)
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="새 인증 로직 구현")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="미들웨어 구현")
-Task(subagent_type="implementation-executor", model="sonnet",
-     prompt="테스트 작성")
-
-// Phase 3: 검증 (순차)
-Task(subagent_type="deployment-validator", model="sonnet",
-     prompt="typecheck/lint/build 전체 검증")
-
-// Phase 4: 리뷰 (병렬)
-Task(subagent_type="code-reviewer", model="opus",
-     prompt="보안 검토")
-Task(subagent_type="code-reviewer", model="opus",
-     prompt="성능 검토")
-```
-
-**구조:**
-1. Phase 1, 2, 4: 병렬 실행 (독립 작업)
-2. Phase 3: 순차 실행 (의존성)
-3. 모델 최적화 (haiku → sonnet → opus)
-
-</examples>
-
----
-
 <best_practices>
 
 ## 모범 사례
@@ -706,7 +414,7 @@ Task(subagent_type="implementation-executor", model="sonnet",
 | **배치 처리** | 유사 작업 묶음 → 토큰 70-90% 절감 |
 | **모델 라우팅** | haiku (간단), sonnet (일반), opus (복잡) |
 | **에이전트 위임** | 전문 에이전트 즉시 위임 → 품질 향상 |
-| **컨텍스트 보존** | 상태 문서화 + 핸드오프 |
+| **컨텍스트 보존** | 상태 문서화 + 핸드오프 + 컴팩션 |
 | **에러 처리** | 격리 + 재시도 (3회) + 서킷 브레이커 |
 | **성능 목표** | 대기 시간 80% 감소, 병렬도 3-10개 |
 
@@ -718,20 +426,3 @@ Task(subagent_type="implementation-executor", model="sonnet",
 5. 모니터링 → TaskList, 로그
 
 </summary>
-
----
-
-<references>
-
-## 참고 자료
-
-**관련 문서:**
-- `.claude/instructions/parallel-agent-execution.md` - 병렬 실행 상세 가이드
-- `.claude/agents/*.md` - 개별 에이전트 스펙
-
-**외부 자료:**
-- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-- [Multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system)
-- [Multi-Agent Design Patterns (Azure)](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
-
-</references>