zioinfo-mail/plugins/harness-main/skills/harness/references/agent-design-patterns.md

# Agent Team Design Patterns

## 실행 모드: 에이전트 팀 vs 서브 에이전트

두 가지 실행 모드의 핵심 차이를 이해하고 적합한 모드를 선택한다.

### 에이전트 팀 (Agent Teams) — 기본 모드

팀 리더가 `TeamCreate`로 팀을 구성하고, 팀원들은 독립적인 Claude Code 인스턴스로 실행된다. 팀원들은 `SendMessage`로 직접 통신하고, 공유 작업 목록(`TaskCreate`/`TaskUpdate`)으로 자체 조율한다.

```
[리더] ←→ [팀원A] ←→ [팀원B]
  ↕          ↕          ↕
  └──── 공유 작업 목록 ────┘
```

**핵심 도구:**
- `TeamCreate`: 팀 생성 + 팀원 스폰
- `SendMessage({to: name})`: 특정 팀원에게 메시지
- `SendMessage({to: "all"})`: 브로드캐스트 (비용 높음, 드물게)
- `TaskCreate`/`TaskUpdate`: 공유 작업 목록 관리

**특징:**
- 팀원끼리 직접 대화, 도전, 검증 가능
- 리더가 거치지 않고 팀원 간 정보 교환
- 공유 작업 목록으로 자체 조율 (자체 작업 요청 가능)
- 팀원이 유휴 상태가 되면 자동으로 리더에게 알림
- 계획 승인 모드로 위험한 작업 전 검토 가능

**제약:**
- 세션당 한 팀만 **활성화** 가능 (단, Phase 간에 팀을 해체하고 새 팀 구성은 가능)
- 중첩 팀 불가 (팀원이 자신의 팀 생성 불가)
- 리더 고정 (이전 불가)
- 토큰 비용 높음

**팀 재구성 패턴:**
Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장 → 팀 정리 → 새 팀 생성 순서로 진행한다. 이전 팀의 산출물은 `_workspace/` 에 보존되므로 새 팀이 Read로 접근 가능하다.

### 서브 에이전트 (Sub-agents) — 경량 모드

메인 에이전트가 `Agent` 도구로 서브 에이전트를 생성한다. 서브 에이전트는 작업 결과를 메인에게만 반환하고 서로 통신하지 않는다.

```
[메인] → [서브A] → 결과 반환
      → [서브B] → 결과 반환
      → [서브C] → 결과 반환
```

**핵심 도구:**
- `Agent(prompt, subagent_type, run_in_background)`: 서브 에이전트 생성

**특징:**
- 가볍고 빠름
- 결과가 메인 컨텍스트로 요약 반환
- 토큰 효율적

**제약:**
- 서브 에이전트 간 통신 불가
- 메인이 모든 조율 담당
- 실시간 협업/도전 불가

### 모드 선택 의사결정 트리

```
에이전트가 2개 이상인가?
├── Yes → 에이전트 간 통신이 필요한가?
│         ├── Yes → 에이전트 팀 (기본값)
│         │         교차 검증·발견 공유·실시간 피드백으로 품질 향상.
│         │
│         └── No → 서브 에이전트도 가능
│                  결과 전달만 필요한 생성-검증, 전문가 풀 등.
│
└── No (1개) → 서브 에이전트
              단일 에이전트는 팀 구성 불필요.
```

> **핵심 원칙:** 에이전트 팀이 기본이다. 서브 에이전트를 선택할 때는 "팀원 간 통신이 정말 불필요한가?"를 자문한다.

---

## 에이전트 팀 아키텍처 유형

### 1. 파이프라인 (Pipeline)
순차적 작업 흐름. 이전 에이전트의 출력이 다음 에이전트의 입력.

```
[분석] → [설계] → [구현] → [검증]
```

**적합한 경우:** 각 단계가 이전 단계의 산출물에 강하게 의존
**예시:** 소설 집필 — 세계관 → 캐릭터 → 플롯 → 집필 → 편집
**주의:** 병목이 전체 파이프라인을 지연시킴. 각 단계를 가능한 독립적으로 설계할 것.
**팀 모드 적합성:** 순차 의존이 강해 팀 모드의 이점이 제한적. 단, 파이프라인 내 병렬 구간이 있으면 팀 모드 유용.

### 2. 팬아웃/팬인 (Fan-out/Fan-in)
병렬 처리 후 결과 통합. 독립적 작업을 동시 수행.

```
         ┌→ [전문가A] ─┐
[분배] → ├→ [전문가B] ─┼→ [통합]
         └→ [전문가C] ─┘
```

**적합한 경우:** 동일 입력에 대해 서로 다른 관점/영역의 분석이 필요
**예시:** 종합 리서치 — 공식/미디어/커뮤니티/배경 동시 조사 → 통합 보고
**주의:** 통합 단계의 품질이 전체 품질을 결정.
**팀 모드 적합성:** 에이전트 팀의 가장 자연스러운 패턴. **반드시 에이전트 팀으로 구성해야 한다.** 팀원들이 서로 발견을 공유하고 도전하며, 한 에이전트의 발견이 다른 에이전트의 조사 방향을 실시간으로 수정할 수 있어 단독 조사 대비 품질이 크게 향상된다.

### 3. 전문가 풀 (Expert Pool)
상황에 따라 적절한 전문가를 선택 호출.

```
[라우터] → { 전문가A | 전문가B | 전문가C }
```

**적합한 경우:** 입력 유형에 따라 다른 처리가 필요
**예시:** 코드 리뷰 — 보안/성능/아키텍처 전문가 중 해당 영역만 호출
**주의:** 라우터의 분류 정확도가 핵심.
**팀 모드 적합성:** 서브 에이전트가 더 적합. 필요한 전문가만 호출하므로 상시 팀이 불필요.

### 4. 생성-검증 (Producer-Reviewer)
생성 에이전트와 검증 에이전트가 쌍으로 동작.

```
[생성] → [검증] → (문제시) → [생성] 재실행
```

**적합한 경우:** 산출물의 품질 보장이 중요하고 객관적 검증 기준이 존재
**예시:** 웹툰 — artist 생성 → reviewer 검수 → 문제 패널 재생성
**주의:** 무한 루프 방지를 위해 최대 재시도 횟수(2~3회) 설정 필수.
**팀 모드 적합성:** 에이전트 팀이 유용. SendMessage로 생성자↔검증자 간 실시간 피드백 교환.

### 5. 감독자 (Supervisor)
중앙 에이전트가 작업 상태를 관리하며 하위 에이전트에 동적으로 작업을 분배.

```
         ┌→ [워커A]
[감독자] ─┼→ [워커B]    ← 감독자가 상태를 보고 동적 분배
         └→ [워커C]
```

**적합한 경우:** 작업량이 가변적이거나 런타임에 작업 분배를 결정해야 할 때
**예시:** 대규모 코드 마이그레이션 — 감독자가 파일 목록을 분석하고 워커들에게 배치 할당
**팬아웃과의 차이:** 팬아웃은 사전에 작업을 고정 분배, 감독자는 진행 상황을 보며 동적 조정
**주의:** 감독자가 병목이 되지 않도록 위임 단위를 충분히 크게 설정.
**팀 모드 적합성:** 에이전트 팀의 공유 작업 목록이 감독자 패턴과 자연스럽게 매칭. TaskCreate로 작업 등록, 팀원들이 자체 요청.

### 6. 계층적 위임 (Hierarchical Delegation)
상위 에이전트가 하위 에이전트에 재귀적으로 위임. 복잡한 문제를 단계적으로 분해.

```
[총괄] → [팀장A] → [실무자A1]
                  → [실무자A2]
       → [팀장B] → [실무자B1]
```

**적합한 경우:** 문제가 자연스럽게 계층적으로 분해되는 구조
**예시:** 풀스택 앱 개발 — 총괄 → 프론트엔드팀장 → (UI/로직/테스트) + 백엔드팀장 → (API/DB/테스트)
**주의:** 깊이 3단계 이상은 지연과 컨텍스트 손실이 커짐. 2단계 이내 권장.
**팀 모드 적합성:** 에이전트 팀은 중첩 불가 (팀원이 팀 생성 불가). 1단계는 팀, 2단계는 서브 에이전트로 구현하거나, 평탄화하여 단일 팀으로 구성.

## 복합 패턴

실전에서는 단일 패턴보다 복합 패턴이 흔하다:

| 복합 패턴 | 구성 | 예시 |
|----------|------|------|
| **팬아웃 + 생성-검증** | 병렬 생성 후 각각 검증 | 다국어 번역 — 4개 언어 병렬 번역 → 각각 네이티브 리뷰어 검수 |
| **파이프라인 + 팬아웃** | 순차 단계 중 일부를 병렬화 | 분석(순차) → 구현(병렬) → 통합 테스트(순차) |
| **감독자 + 전문가 풀** | 감독자가 전문가를 동적 호출 | 고객 문의 처리 — 감독자가 문의 분류 후 적합한 전문가 할당 |

### 복합 패턴에서의 실행 모드

**기본적으로 모든 복합 패턴에 에이전트 팀을 사용한다.** 팀원 간 활발한 커뮤니케이션이 결과 품질의 핵심 동력이다.

| 시나리오 | 권장 모드 | 이유 |
|---------|----------|------|
| **리서치 + 분석** | 에이전트 팀 | 조사자 간 발견 공유, 상충 정보 실시간 토론 |
| **설계 + 구현 + 검증** | 에이전트 팀 | 설계자↔구현자↔검증자 간 피드백 루프 |
| **감독자 + 워커** | 에이전트 팀 | 공유 작업 목록으로 동적 할당, 워커 간 진행률 공유 |
| **생성 + 검증** | 에이전트 팀 | 생성자↔검증자 간 실시간 피드백으로 재작업 최소화 |

> 서브 에이전트로의 혼합은 단일 에이전트가 완전히 격리된 단발성 작업을 수행할 때만 고려한다.

## 에이전트 타입 선택

에이전트를 호출할 때 Agent 도구의 `subagent_type` 파라미터로 타입을 지정한다. 에이전트 팀의 팀원도 커스텀 에이전트 정의를 사용할 수 있다.

### 빌트인 타입

| 타입 | 도구 접근 | 적합한 용도 |
|------|----------|-----------|
| `general-purpose` | 전체 (WebSearch, WebFetch 포함) | 웹 조사, 범용 작업 |
| `Explore` | 읽기 전용 (Edit/Write 없음) | 코드베이스 탐색, 분석 |
| `Plan` | 읽기 전용 (Edit/Write 없음) | 아키텍처 설계, 계획 수립 |

### 커스텀 타입

`.claude/agents/{name}.md`에 에이전트를 정의하면 `subagent_type: "{name}"`으로 호출할 수 있다. 커스텀 에이전트는 전체 도구에 접근 가능.

### 선택 기준

| 상황 | 권장 | 이유 |
|------|------|------|
| 역할이 복잡하고 여러 세션에서 재사용 | **커스텀 타입** (`.claude/agents/`) | 페르소나와 작업 원칙을 파일로 관리 |
| 단순 조사/수집이고 프롬프트만으로 충분 | **`general-purpose`** + 상세 프롬프트 | 에이전트 파일 불필요, 프롬프트에 지시 포함 |
| 코드 읽기만 필요 (분석/리뷰) | **`Explore`** | 실수로 파일 수정하는 것을 방지 |
| 설계/계획만 필요 | **`Plan`** | 분석에 집중, 코드 변경 방지 |
| 파일 수정이 필요한 구현 작업 | **커스텀 타입** | 전체 도구 접근 + 전문 지시 |

**원칙:** 모든 에이전트는 반드시 `.claude/agents/{name}.md` 파일로 정의한다. 빌트인 타입이라도 에이전트 정의 파일을 생성하여 역할·원칙·프로토콜을 명시한다. 파일로 존재해야 다음 세션에서 재사용 가능하고, 팀 통신 프로토콜이 명시되어야 협업 품질이 보장된다.

**모델:** 모든 에이전트는 `model: "opus"`를 사용한다. Agent 도구 호출 시 반드시 `model: "opus"` 파라미터를 명시한다.

## 에이전트 정의 구조

```markdown
---
name: agent-name
description: "1-2문장 역할 설명. 트리거 키워드 나열."
---

# Agent Name — 역할 한줄 요약

당신은 [도메인]의 [역할] 전문가입니다.

## 핵심 역할
1. 역할1
2. 역할2

## 작업 원칙
- 원칙1
- 원칙2

## 입력/출력 프로토콜
- 입력: [어디서 무엇을 받는지]
- 출력: [어디에 무엇을 쓰는지]
- 형식: [파일 포맷, 구조]

## 팀 통신 프로토콜 (에이전트 팀 모드)
- 메시지 수신: [누구로부터 어떤 메시지를 받는지]
- 메시지 발신: [누구에게 어떤 메시지를 보내는지]
- 작업 요청: [공유 작업 목록에서 어떤 유형의 작업을 요청하는지]

## 에러 핸들링
- [실패 시 행동]
- [타임아웃 시 행동]

## 협업
- 다른 에이전트와의 관계
```

## 에이전트 분리 기준

| 기준 | 분리 | 통합 |
|------|------|------|
| 전문성 | 영역이 다르면 분리 | 영역이 겹치면 통합 |
| 병렬성 | 독립 실행 가능하면 분리 | 순차 종속이면 통합 고려 |
| 컨텍스트 | 컨텍스트 부담이 크면 분리 | 가볍고 빠르면 통합 |
| 재사용성 | 다른 팀에서도 쓰면 분리 | 이 팀에서만 쓰면 통합 고려 |

## 스킬 vs 에이전트 구분

| 구분 | 스킬 (Skill) | 에이전트 (Agent) |
|------|-------------|-----------------|
| 정의 | 절차적 지식 + 도구 번들 | 전문가 페르소나 + 행동 원칙 |
| 위치 | `.claude/skills/` | `.claude/agents/` |
| 트리거 | 사용자 요청 키워드 매칭 | Agent 도구로 명시적 호출 |
| 크기 | 작은~큰 (워크플로우) | 작은 (역할 정의) |
| 용도 | "어떻게 하는가" | "누가 하는가" |

스킬은 에이전트가 작업을 수행할 때 참조하는 **절차적 가이드**.
에이전트는 스킬을 활용하는 **전문가 역할 정의**.

## 스킬 ↔ 에이전트 연결 방식

에이전트가 스킬을 활용하는 3가지 방식:

| 방식 | 구현 | 적합한 경우 |
|------|------|-----------|
| **Skill 도구 호출** | 에이전트 프롬프트에 `Skill 도구로 /skill-name 호출` 명시 | 스킬이 독립 워크플로우이고 사용자 호출 가능한 경우 |
| **프롬프트 내 인라인** | 에이전트 정의 내에 스킬 내용을 직접 포함 | 스킬이 짧고(50줄 이하) 이 에이전트 전용인 경우 |
| **레퍼런스 로드** | `Read`로 스킬의 references/ 파일을 필요 시 로드 | 스킬 내용이 크고 조건부로만 필요한 경우 |

권장: 재사용성이 높으면 Skill 도구, 전용이면 인라인, 대용량이면 레퍼런스 로드.