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" 파라미터를 명시한다.

에이전트 정의 구조

---
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 도구, 전용이면 인라인, 대용량이면 레퍼런스 로드.