멀티에이전트 Co-work

멀티에이전트 Co-work는 여러 Claude 인스턴스가 각자 역할을 맡아 협력하는 방식입니다. 한 에이전트가 모든 것을 처리하는 대신, 전문화된 에이전트들이 병렬로 작업하고 결과를 통합합니다.

Co-work vs 단일 에이전트

구분	단일 에이전트	멀티에이전트 Co-work
처리 방식	순차적	병렬
컨텍스트	하나의 긴 컨텍스트	각자 독립된 컨텍스트
전문성	범용	역할별 특화
속도	느림	빠름
비용	낮음	높음 (병렬만큼 증가)
적합 케이스	단순 작업	복잡한 대규모 작업

기본 Co-work 패턴

역할 분담 아키텍처

[사용자 요청]
      ↓
[코디네이터 에이전트] — 작업 분석 및 역할 배정
      ↓
┌─────────────────────────────────────────────┐
│  [리서처]      [개발자]      [리뷰어]        │
│  (정보 수집)   (코드 작성)   (품질 검토)     │
└─────────────────────────────────────────────┘
      ↓
[코디네이터 에이전트] — 결과 통합 및 최종 응답

Claude Code에서 Co-work 요청

> 우리 결제 시스템에 새 기능을 추가해야 해.
  세 가지 역할로 나눠서 진행해줘:

  1. 리서처: 현재 payment/ 코드를 분석해서
     아키텍처와 패턴을 파악해줘
  2. 개발자: 리서처 결과를 바탕으로
     환불 기능 구현해줘
  3. 리뷰어: 개발자 코드를 검토하고
     보안 이슈와 엣지케이스 찾아줘

Agent SDK로 Co-work 구현

전문가 패널 패턴

여러 전문가 에이전트가 동일한 문제를 각자 분석:

import { query } from "@anthropic-ai/claude-agent-sdk";

interface ExpertOpinion {
  role: string;
  analysis: string;
  recommendation: string;
}

async function expertPanel(problem: string): Promise<string> {
  const experts = [
    {
      role: "보안 전문가",
      prompt: `보안 전문가로서 다음 문제를 분석해줘.
        보안 취약점과 위험 요소에 집중해:
        ${problem}`
    },
    {
      role: "성능 전문가",
      prompt: `성능 최적화 전문가로서 다음 문제를 분석해줘.
        병목 지점과 확장성 이슈에 집중해:
        ${problem}`
    },
    {
      role: "UX 전문가",
      prompt: `UX 디자이너로서 다음 문제를 분석해줘.
        사용자 경험과 접근성에 집중해:
        ${problem}`
    }
  ];

  // 모든 전문가가 동시에 분석
  const opinions = await Promise.all(
    experts.map(async (expert) => {
      const response = await query({
        prompt: expert.prompt,
        options: { maxTurns: 8 }
      });
      return {
        role: expert.role,
        analysis: extractText(response)
      } as ExpertOpinion;
    })
  );

  // 코디네이터가 의견 종합
  const synthesis = await query({
    prompt: `다음 세 전문가의 의견을 종합해서
    균형 잡힌 최종 권고안을 작성해줘:

    ${opinions.map(o => `### ${o.role}\n${o.analysis}`).join("\n\n")}

    상충되는 의견은 트레이드오프를 설명하고
    우선순위와 함께 제시해줘.`,
    options: { maxTurns: 5 }
  });

  return extractText(synthesis);
}

파이프라인 Co-work 패턴

각 에이전트가 이전 에이전트의 작업을 이어받아 개선:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function writingPipeline(topic: string): Promise<string> {
  // 1단계: 리서처가 자료 수집
  console.log("📚 리서처: 자료 수집 중...");
  const research = await query({
    prompt: `${topic}에 대해 리서치해줘.
      핵심 개념, 최신 트렌드, 주요 데이터를
      구조화해서 정리해줘.`,
    options: {
      maxTurns: 10,
      allowedTools: ["WebSearch", "Read"]
    }
  });
  const researchResult = extractText(research);

  // 2단계: 작가가 초안 작성
  console.log("✍️ 작가: 초안 작성 중...");
  const draft = await query({
    prompt: `다음 리서치 자료를 바탕으로
    블로그 포스트 초안을 작성해줘.
    독자: 개발자 / 톤: 친근하지만 전문적

    리서치 자료:
    ${researchResult}`,
    options: { maxTurns: 8 }
  });
  const draftResult = extractText(draft);

  // 3단계: 편집자가 다듬기
  console.log("📝 편집자: 교정 및 개선 중...");
  const edited = await query({
    prompt: `다음 블로그 초안을 편집해줘:
    - 명확하지 않은 문장 개선
    - 논리 흐름 점검
    - SEO를 위한 키워드 최적화
    - 독자 참여를 높이는 CTA 추가

    초안:
    ${draftResult}`,
    options: { maxTurns: 6 }
  });

  return extractText(edited);
}

역할 특화 시스템 프롬프트

각 에이전트에 명확한 페르소나 부여:

const agentConfigs = {
  architect: {
    systemPrompt: `당신은 시니어 소프트웨어 아키텍트입니다.
      항상 확장성, 유지보수성, 패턴 일관성을 최우선으로 생각합니다.
      코드 작성보다 설계 결정에 집중하세요.`,
    maxTurns: 5
  },
  developer: {
    systemPrompt: `당신은 풀스택 개발자입니다.
      아키텍처 결정에 따라 실제 구현 코드를 작성합니다.
      테스트 가능하고 읽기 쉬운 코드를 작성하세요.`,
    maxTurns: 20,
    allowedTools: ["Read", "Edit", "Write", "Bash"]
  },
  tester: {
    systemPrompt: `당신은 QA 엔지니어입니다.
      엣지 케이스, 예외 상황, 보안 취약점을 찾는 것이 목표입니다.
      개발자가 놓친 부분을 집중적으로 검토하세요.`,
    maxTurns: 10,
    allowedTools: ["Read", "Glob", "Grep"]
  }
};

async function developFeature(requirement: string) {
  // 1. 아키텍트가 설계
  const designResponse = await query({
    prompt: requirement,
    options: agentConfigs.architect
  });
  const design = extractText(designResponse);

  // 2. 개발자가 구현
  const implementResponse = await query({
    prompt: `다음 아키텍처 설계를 구현해줘:\n${design}`,
    options: agentConfigs.developer
  });
  const implementation = extractText(implementResponse);

  // 3. QA가 검토
  const reviewResponse = await query({
    prompt: `다음 구현 코드를 검토해줘:\n${implementation}`,
    options: agentConfigs.tester
  });

  return {
    design,
    implementation,
    review: extractText(reviewResponse)
  };
}

충돌 해결 패턴

에이전트 간 의견 충돌을 처리하는 방법:

async function resolveConflict(
  agentA: string,
  agentB: string,
  opinions: [string, string]
): Promise<string> {
  const mediator = await query({
    prompt: `두 전문가의 의견이 충돌합니다.
    객관적으로 분석하고 최선의 결론을 도출해줘.

    ${agentA}의 의견:
    ${opinions[0]}

    ${agentB}의 의견:
    ${opinions[1]}

    결론 형식:
    1. 각 의견의 타당한 점
    2. 핵심 충돌 지점
    3. 권장 해결책과 이유`,
    options: { maxTurns: 4 }
  });

  return extractText(mediator);
}

세션 간 메시징 (Cross-Session Messaging)

Claude Code(v2.1.224+)는 동일한 머신에서 실행 중인 다른 Claude Code 세션과 서로 메시지를 주고받을 수 있습니다.

어떤 세션에서 기존 코드를 변경하거나 중요한 발견을 했을 때, 해당 코드를 다루고 있는 다른 세션에게 알려줄 수 있습니다. 사용자가 직접 복사해서 전달할 필요 없이, Claude가 ListAgents와 SendMessage 도구를 사용해 스스로 다른 세션을 찾고 메시지를 전송합니다.

사용 방법

Claude가 스스로 판단: 병렬 작업 중 다른 세션이 알아야 할 내용이 생기면 자율적으로 메시지를 보냅니다.
명시적 지시: 사용자가 프롬프트로 "다른 터미널에서 실행 중인 세션에게 마이그레이션 끝났다고 알려줘"라고 지시할 수 있습니다.
@ 멘션 (v2.1.232+): 프롬프트 창에서 @를 입력하면 현재 실행 중인 다른 세션들의 이름이 자동완성됩니다. 예: @api-worker 에게 스키마 마이그레이션 끝났다고 알려줘.

/list-agents (또는 /peers) 커맨드를 사용하면 현재 메시지를 보낼 수 있는 세션(서브에이전트, 로컬 세션, 백그라운드 세션, Remote Control로 연결된 클라우드/다른 머신 세션) 목록을 확인할 수 있습니다.

인바운드 메시지 제어

다른 세션에서 보낸 메시지를 받을지 여부는 crossSessionInbound 설정이나 /config 메뉴의 Messages from your other sessions에서 제어할 수 있습니다.

accept: 바로 수신하여 Claude에게 전달합니다.
hold: 알림만 띄우고 보류합니다 (대화창에서 Approve/Deny 버튼으로 결정).
refuse: 메시지를 조용히 차단합니다.

보안 모델

다른 세션이 보낸 메시지는 사용자의 명시적 프롬프트와 동일한 권한을 가지지 않습니다. 메시지를 통해 도착한 명령어(예: /compact)는 실행되지 않고 평문으로 처리되며, 해당 세션의 권한 모드 설정(자동 모드 여부 등)과 권한 승인 원칙을 그대로 따릅니다.

한계 및 제약사항

순수 텍스트(Plain Text) 전송: 세션 간 메시지는 텍스트 기반으로만 교환됩니다. 한 세션의 파일 컨텍스트나 전체 대화 기록이 다른 세션으로 복제되지는 않습니다. 완전한 컨텍스트가 필요한 경우 메시징 대신 /resume 커맨드를 사용해 해당 세션을 직접 이어받는 것이 좋습니다.
OS 지원: macOS, Linux, 그리고 Windows의 WSL2 환경에서 완벽히 동작합니다. 단, Windows Native 환경(CMD, PowerShell)은 현재 지원하지 않습니다.

Agent Teams (내장 기능)

위의 Agent SDK 기반 구현 외에, Claude Code에는 내장 Agent Teams 기능이 있습니다. 코드를 작성하지 않고도 자연어로 멀티에이전트 협업을 요청할 수 있습니다.

실험적 기능

Agent Teams는 현재 실험적 기능입니다. 세션 이어가기(resume), 태스크 조율, 종료 동작에 알려진 제한사항이 있습니다.

서브에이전트 vs Agent Teams

구분	서브에이전트	Agent Teams
컨텍스트	결과만 메인에 반환	완전히 독립
커뮤니케이션	메인 에이전트에만 보고	팀원 간 직접 메시지
조율 방식	메인 에이전트가 관리	공유 작업 목록 + 자율 선택
적합한 경우	결과만 중요한 집중 태스크	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음 (결과만 요약)	높음 (각 팀원이 독립 인스턴스)

활성화

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

팀 아키텍처

구성 요소	역할
팀 리더	메인 Claude Code 세션. 팀원 생성, 작업 배정, 결과 조율
팀원	별도의 Claude Code 인스턴스. 배정된 작업을 독립 수행
작업 목록	공유 태스크 리스트. 팀원이 자율적으로 작업을 가져감
메일박스	팀원 간 직접 메시지 시스템 (message + broadcast)

팀과 태스크는 로컬에 저장됩니다:

팀 설정: ~/.claude/teams/{team-name}/config.json
태스크: ~/.claude/tasks/{team-name}/

최적 사용 시나리오

리서치와 리뷰: 여러 팀원이 다른 관점에서 동시에 조사
새 모듈/기능: 각 팀원이 서로 다른 부분을 소유
경쟁 가설 디버깅: 여러 이론을 병렬로 검증하고 수렴
크로스 레이어 작업: 프론트엔드, 백엔드, 테스트를 각각 소유

사용 예시

> CLI 도구를 설계해야 해. 다른 관점에서 탐색할 Agent Team을 만들어줘:
  - UX 담당 1명
  - 기술 아키텍처 담당 1명
  - 반론을 제기할 비평가 1명

Claude가 팀을 생성하고, 팀원을 스폰하며, 공유 태스크 리스트로 작업을 조율합니다.

표시 모드

모드	설명	요구사항
in-process	한 터미널에서 `Shift+Down`으로 전환	없음 (기본)
split-panes	각 팀원이 별도 패널	tmux 또는 iTerm2
auto	tmux 세션이면 split, 아니면 in-process	-

// settings.json
{ "teammateMode": "in-process" }

# 세션별 오버라이드
claude --teammate-mode in-process

Split Pane 제한

Split-pane 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다. tmux 또는 iTerm2가 필요합니다.

팀원과 직접 소통

각 팀원은 완전한 독립 Claude Code 세션입니다:

In-process 모드:

Shift+Down: 팀원 간 전환
Enter: 팀원 세션 진입 → Esc로 중단
Ctrl+T: 태스크 리스트 토글

Split-pane 모드:

패널 클릭으로 직접 상호작용

태스크 관리

태스크는 세 가지 상태로 관리됩니다: pending → in progress → completed. 태스크 간 의존성도 지원됩니다.

리더가 배정: 특정 팀원에게 태스크 지정
자율 선택: 팀원이 완료 후 다음 미배정+미차단 태스크를 자동 선택
파일 락킹: 여러 팀원이 동시에 같은 태스크를 선택하는 것을 방지

Plan 승인

복잡하거나 위험한 작업에는 팀원에게 구현 전 계획 승인을 요구할 수 있습니다:

인증 모듈을 리팩토링할 아키텍트 팀원을 만들어줘.
변경 전에 계획 승인을 받도록 해.

팀원이 계획을 완료하면 리더에게 승인을 요청합니다. 거절 시 피드백과 함께 재계획합니다.

팀 정리

> 팀을 정리해줘

리더를 통해 정리하세요. 팀원이 아직 실행 중이면 먼저 종료해야 합니다. 팀원이 직접 정리하면 리소스가 불일치 상태가 될 수 있습니다.

품질 게이트 Hook

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "npm test -- --related $CHANGED_FILES"
      }]
    }],
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "./scripts/check-remaining-work.sh"
      }]
    }]
  }
}

종료 코드 2를 반환하면 팀원에게 피드백이 전달되고 작업을 계속합니다.

베스트 프랙티스

토큰 비용 폭탄 주의 (실전 사례)

각 팀원은 완전히 독립된 Claude 인스턴스입니다. 팀원 5명이면 5배의 토큰을 소비하며, 서로 메시지를 주고받는 대립 토론이나 병렬 조사 패턴에서는 15분 만에 $80 이상의 API 비용이 발생할 수 있습니다.

비용 최적화 원칙:
1. 단순 결과 요약은 서브에이전트를 사용하고, 팀원 간 토론/자율 분담이 꼭 필요한 경우에만 Agent Teams를 켭니다.
2. 팀원 모델은 Opus 대신 Sonnet 또는 Haiku로 지정하여 비용을 방어하세요.
3. 작업이 끝나면 반드시 > 팀을 정리해줘 명령어로 유휴 팀원을 즉시 종료하세요.

3~5명의 팀원으로 시작 (비용 대비 효과 최적)
팀원당 5~6개 태스크 배정이 적당
팀원 간 파일 소유권을 분리 (같은 파일 동시 수정 방지)
Worktree와 결합하면 파일 충돌 완전 방지
팀원에게 충분한 컨텍스트를 제공 (대화 기록은 상속되지 않음)
팀원 모델로 Sonnet 사용 권장 (능력과 비용의 균형)
주기적으로 진행 상황을 확인하고 방향 수정

제한사항

/resume과 /rewind는 in-process 팀원을 복원하지 않음
태스크 상태가 지연될 수 있어 수동 업데이트가 필요할 때 있음
세션당 하나의 팀만 관리 가능
중첩 팀 불가 (팀원은 자체 팀을 만들 수 없음)
모든 팀원은 리더의 권한 모드로 시작 (스폰 후 개별 변경 가능)

Co-work 설계 원칙

효과적인 Co-work 설계

역할 명확화: 각 에이전트의 책임 범위를 겹치지 않게 정의
인터페이스 통일: 에이전트 간 데이터 교환 형식을 표준화
독립성 보장: 한 에이전트의 실패가 전체를 멈추지 않도록 설계
컨텍스트 요약: 에이전트 간 전달 내용은 핵심만 압축

흔한 실수

서브에이전트 결과가 메인 컨텍스트를 채움: 여러 서브에이전트가 상세한 결과를 반환하면 메인 대화의 컨텍스트를 빠르게 소비합니다. 지속적 병렬 작업이 필요하면 서브에이전트 대신 Agent Teams를 고려하세요
역할 경계가 모호해서 같은 작업을 중복 수행
실패 처리 없이 순차적 의존 → 한 에이전트 실패 시 전체 중단

이 페이지에 오류가 있나요? 오류 제보하기 →

Co-work vs 단일 에이전트​

기본 Co-work 패턴​

역할 분담 아키텍처​

Claude Code에서 Co-work 요청​

Agent SDK로 Co-work 구현​

전문가 패널 패턴​

파이프라인 Co-work 패턴​

역할 특화 시스템 프롬프트​

충돌 해결 패턴​

세션 간 메시징 (Cross-Session Messaging)​

사용 방법​

인바운드 메시지 제어​

Agent Teams (내장 기능)​

서브에이전트 vs Agent Teams​

활성화​

팀 아키텍처​

최적 사용 시나리오​

사용 예시​

표시 모드​

팀원과 직접 소통​

태스크 관리​

Plan 승인​

팀 정리​

품질 게이트 Hook​

베스트 프랙티스​

제한사항​

Co-work 설계 원칙​