콘텐츠로 이동

Agent 설계 실전 가이드

Sub-agent와 Agent Team을 설계할 때 참고하는 실전 체크리스트. 우리가 실수했던 것, 발견한 것, 검증된 패턴을 모아둔 문서.

1. Sub-agent vs Agent Team — 선택 기준

[핵심 질문] "에이전트끼리 대화해야 더 나은 결과가 나오는가?"

YES → Agent Team
  - 토론/반박이 필요한 경우
  - 서로의 발견을 참조해야 하는 경우
  - 교차 검증(팩트체크)이 필요한 경우

NO → Sub-agent
  - 각자 독립 조사 후 결과만 모으면 되는 경우
  - 속도가 중요한 경우
  - 비용을 아껴야 하는 경우

비교표

Sub-agent (Task 도구) Agent Team
에이전트 간 대화 불가능 — 결과만 부모에게 보고 가능 — 메일박스로 직접 메시지
공유 작업 목록 없음 있음 — 자기가 알아서 작업 선택
구조 부모 → 자식 (일방향) 리드 ↔ 팀원 ↔ 팀원 (양방향)
토큰 비용 낮음 높음 (팀원 수 × 각자 컨텍스트)
속도 빠름 (~5분) 느림 (~16분+)
적합한 작업 독립 조사, 수집 토론, 교차 검토, 협업

실전 판단 (youtube-workflow 경험)

주간 리포트 (빠른 수집) → Sub-agent (Method A, ~5분)
심층 분석 (팩트체크+토론) → Agent Team (Method B, ~16분)
페르소나 토론 (다관점 창의성) → Agent Team (Method C, ~20분)

2. 반드시 알아야 할 함정들

함정 1: Deferred Tool 로딩 (가장 중요!)

문제: Sub-agent(Task 도구)에서 WebFetch, WebSearch가 안 됨 원인: 이 도구들은 "deferred tool"이라서 ToolSearch로 먼저 로드해야 사용 가능 증상: 에이전트가 검색을 시도하지만 도구 자체를 찾지 못함

[해결법] 프롬프트 맨 앞에 이 블록 추가:

[사전 준비 — 반드시 먼저 실행]
1. ToolSearch("select:WebFetch") 호출하여 WebFetch 도구 로드
2. ToolSearch("select:WebSearch") 호출하여 WebSearch 도구 로드
두 도구가 로드된 뒤에 아래 작업을 시작해.

적용 대상: Sub-agent만. Agent Team 팀원은 독립 Claude Code 세션이라 자동 로드됨.

참고: mode: "bypassPermissions"로도 해결 안 됨. 권한 문제가 아니라 도구 등록 문제.

함정 2: WebFetch 권한 거부

문제: Sub-agent가 WebFetch를 시도하면 사용자에게 권한 요청이 뜸 원인: Sub-agent도 메인 세션의 권한 설정을 따름

[해결법 — 선택지]
1. mode: "bypassPermissions" → 모든 권한 우회 (편하지만 주의)
2. mode: "dontAsk" → 거부당하면 조용히 넘어감
3. 사전에 권한 허용 설정 → settings.json에서 WebFetch 자동 허용

[권장] 검색 전용 에이전트는 "bypassPermissions" 사용
       파일 수정하는 에이전트는 "default" 유지

함정 3: Agent Team에서 ToolSearch가 필요 없는 이유

Agent Team 팀원 = 독립 Claude Code 세션이므로: - CLAUDE.md 자동 로드 - MCP 서버 자동 연결 - Deferred tool도 세션 시작 시 자동 로드

Sub-agent(Task 도구) = 메인 세션의 자식 프로세스이므로: - CLAUDE.md는 접근 가능 - MCP 서버는 상속됨 - Deferred tool은 자동 로드 안 됨 → ToolSearch 필수

함정 4: Sub-agent끼리 결과 공유 불가

[안 되는 것]
Task A → "여기 결과야" → Task B   (불가능)

[되는 것]
Task A → 결과 → 메인
Task B → 결과 → 메인
메인이 A+B 결과를 종합하여 Task C에 전달

Agent Team에서는: 팀원A → (메시지) → 팀원B 직접 가능

함정 5: 1개 에이전트가 여러 역할을 하면 편향됨

[문제] 1개 에이전트에게 "4명 역할을 순서대로 해" 시키면:
  - 같은 "뇌"라서 비슷한 결론이 나옴
  - 첫 번째 역할의 판단이 나머지에 영향 (앵커링 효과)
  - 진짜 반박이 아니라 형식적 반박

[해결] 독립 관점이 필요하면 → 별개 에이전트로 분리
  - Sub-agent 4개 병렬 (서로 모르는 상태)
  - 또는 Agent Team (서로 대화 가능)

3. 검증된 설계 패턴

패턴 A: 수집형 (Sub-agent)

메인 (편집장)
  ├─ Sub-agent 1: 소스 그룹 A 검색
  ├─ Sub-agent 2: 소스 그룹 B 검색
  ├─ Sub-agent 3: 소스 그룹 C 검색
  └─ Sub-agent 4: 소스 그룹 D 검색
→ 메인이 결과 종합 → 리포트

장점: 빠름, 저렴
단점: 교차 검증 없음

패턴 B: 토론형 (Agent Team)

리드 (편집장)
  ├─ 팀원 1: 소스 검색 → 결과 공유
  ├─ 팀원 2: 소스 검색 → 결과 공유
  ├─ 팀원 3: 소스 검색 → 결과 공유
  └─ 팀원 4: 소스 검색 → 결과 공유
→ 리드가 교차 토론 지시 → 팀원끼리 DM → 리드가 수렴

장점: 팩트체크, 교차 분석
단점: 느림, 토큰 많이 소비

패턴 C: 페르소나 토론형 (Agent Team + 성격)

리드 (편집장)
  ├─ 🎨 creative: 발산형 검색+해석
  ├─ 🔍 factchecker: 정밀형 검색+검증
  ├─ 👥 audience: 시청자 관점 검색+분석
  └─ 📊 strategist: 전략형 검색+포지셔닝
→ 리드가 결과 종합 → 팀원들에게 교차 피드백 지시
→ 팀원끼리 DM으로 밀기/반대 → 리드가 최종 수렴

장점: 다양한 관점, 진짜 토론, 창의적 결과
단점: 가장 느림, 가장 비쌈

4. 비용 최적화

모델 선택

[Agent Team]
  리드 (편집장): opus — 판단력, 종합력 필요
  팀원 (검색+해석): sonnet — 조사+요약에 충분, 비용 ~1/5

[Sub-agent]
  검색 전용: sonnet 또는 haiku
  분석/글쓰기: sonnet
  중요 판단: opus

팀 규모

추천: 3~5명 (대부분 4명이면 충분)
팀원당 작업: 5~6개가 적당
그 이상: 조율 비용 > 병렬 이득

라운드 제한

교차 토론: 2라운드면 충분 (3라운드부터 가성비 급감)
피드백 루프: "밀기 1개 + 반대 1개"로 제한 → 발산 방지

5. Agent Team 실전 체크리스트

팀 생성 전

  • [ ] 팀원끼리 대화가 필요한 작업인지 확인 (아니면 Sub-agent)
  • [ ] 팀원 수 결정 (3~5명 권장)
  • [ ] 각 팀원의 역할과 담당 범위 명확히
  • [ ] 모델 지정 (기본: 팀원은 sonnet)
  • [ ] 라운드 수 결정 (조사 + 토론 1~2회)

팀 운영 중

  • [ ] 리드가 직접 작업하지 않게 주의 ("팀원이 끝날 때까지 기다려")
  • [ ] 교차 토론 시 구체적 쌍 지정 ("🎨는 🔍의 제안에 대해 피드백해")
  • [ ] 중간 결과를 사용자에게 공유 (라운드별 파일 저장 + 화면 요약)
  • [ ] 팀원이 멈춰 있으면 직접 메시지 (Shift+Down)

팀 종료

  • [ ] 모든 팀원 셧다운 확인
  • [ ] 리드에게 "팀 정리해줘" 지시
  • [ ] 결과 리포트 저장 확인

6. Sub-agent 실전 체크리스트

프롬프트 작성

  • [ ] ToolSearch 사전 준비 블록 추가 (WebFetch/WebSearch 사용 시 필수)
  • [ ] 결과 형식 명시 (마크다운 테이블, 불릿 등)
  • [ ] 정확도 지시 (버전 확인, 날짜 확인 등)
  • [ ] 모델 지정 (model: "sonnet" 등)

권한 설정

[검색만 하는 에이전트]
  mode: "bypassPermissions" — WebFetch 권한 팝업 방지

[파일 수정하는 에이전트]
  mode: "default" — 안전하게

[권한 거부 시 fallback 필요]
  mode: "dontAsk" — 거부당하면 조용히 다음으로

병렬 실행

  • [ ] 독립 작업이면 run_in_background: true로 병렬
  • [ ] 의존성 있으면 순차 실행 (R1 끝나야 R2 가능)
  • [ ] 결과 파일 경로 기록 (output_file)

7. 실수 기록 (사고 일지)

사고 1: ToolSearch 누락 (2026-02-24)

  • 상황: Method C v1에서 4개 Sub-agent가 웹 검색 전혀 못함
  • 원인: WebFetch/WebSearch가 deferred tool → ToolSearch 먼저 호출해야 로드됨
  • 영향: 편집장이 직접 R1 검색을 수행하느라 20분+ 소요
  • 해결: 프롬프트에 [사전 준비] 블록 추가
  • 교훈: Sub-agent 프롬프트 작성 시 deferred tool 체크 필수

사고 2: Google/Gemini SPA 사이트 (2026-02-24)

  • 상황: W09 리포트에서 Gemini 3.1 Pro 출시(2/19) 완전 누락
  • 원인: Google AI Blog이 SPA(Single Page App)라 WebFetch 실패 + 2군 검색에 전용 쿼리 없었음
  • 해결: Gemini new model {월} {연도} 전용 쿼리 + site:9to5google.com 보완 쿼리 추가
  • 교훈: WebFetch 실패하는 사이트는 WebSearch 우회 쿼리를 미리 설계

사고 3: 한국어 유튜브 검색 0건 (2026-02-24)

  • 상황: WebSearch("site:youtube.com AI 도구 2026") → 0건 반환
  • 원인: WebSearch의 site: 연산자 + 한국어 조합이 불안정
  • 해결: yt-dlp "ytsearch10:AI 도구 {연도}" 로 직접 유튜브 검색
  • 교훈: 한국어 유튜브 검색은 yt-dlp가 훨씬 안정적

사고 4: 1개 에이전트 4역할 = 가짜 토론 (2026-02-24)

  • 상황: Method C v1/v2에서 R2/R3를 1개 에이전트가 4명 역할극
  • 원인: Sub-agent끼리 결과 공유 불가 → 어쩔 수 없이 1개로
  • 영향: 같은 뇌라서 반박이 형식적, 관점 다양성 부족
  • 해결: Agent Team으로 전환 → 진짜 독립 에이전트가 진짜 토론
  • 교훈: "진짜 다른 관점"이 필요하면 반드시 별개 에이전트

사고 5: WebFetch 권한 거부 (2026-02-24)

  • 상황: Method C v2 시뮬레이션에서 🎨 에이전트 WebFetch 거부됨
  • 원인: 사용자 권한 모드에서 WebFetch마다 승인 필요
  • 영향: 🎨가 WebSearch로 fallback → 일부 소스 직접 읽기 실패
  • 해결: 검색 전용 에이전트는 mode: "bypassPermissions" 사용
  • 교훈: Sub-agent의 mode 설정을 용도에 맞게 미리 결정

참고 문서