Claude Code 멀티 에이전트(Multi-agent)를 0부터 만드는 실전 가이드 — 설계부터 운용까지

Claude Code로 멀티 에이전트 시스템(Multi-agent system)을 만들어 본 적이 있나요?

이 기사는 "Claude Code의 agent 기능은 알고 있지만, 어떻게 설계해야 할지 모르겠다"는 분들을 위한 실전 가이드입니다. 실제로 10일 동안 가동 중인 시스템의 설계를 바탕으로 작성되었습니다.

멀티 에이전트가 유효한 상황

먼저, 멀티 에이전트가 필요하지 않은 상황을 정리합니다.

• 하나의 태스크(Task)를 순차적으로 수행하기만 한다면, 메인 Claude Code 세션으로 충분합니다.
• 컨텍스트(Context)가 하나로 수용 가능하다면, 에이전트를 나눌 필요가 없습니다.

멀티 에이전트가 유효한 경우는 다음과 같습니다.

권한을 나누고 싶을 때: WebSearch를 할 수 있는 에이전트와 파일 편집만 할 수 있는 에이전트를 분리합니다. 오작동 및 일탈을 방지할 수 있습니다.

컨텍스트를 절약하고 싶을 때: 대량의 WebFetch를 서브 에이전트(Sub-agent)에게 맡기고, 메인에는 요약본만 돌려줍니다. Claude Pro의 제한 범위 내에서 더 오래 작동할 수 있습니다.

책임의 경계를 명확히 하고 싶을 때: "조사 결과는 Researcher의 업무, 집필은 Writer의 업무"라고 정의함으로써, 어떤 에이전트가 무엇을 출력했는지 추적하기 쉬워집니다.

스텝 1: CLAUDE.md를 목차로 설계하기

Claude Code는 프로젝트 루트의 CLAUDE.md를 세션 시작 시 자동으로 읽습니다. 이를 "목차"로 사용하고, 상세 내용은 별도 파일로 분리합니다.

해서는 안 될 설계 (비대해짐):

# CLAUDE.md
## 역할
Researcher는 조사 담당. WebSearch, WebFetch를 사용함.
...

권장 설계 (목차로서 기능함):

# CLAUDE.md
## 역할 분담
| 역할 | 담당 에이전트 |
...

@rules/02-team.md와 같이 작성하면, Claude Code는 참조 대상을 자동으로 읽으러 갑니다. CLAUDE.md 자체는 200행 이하를 유지합니다.

스텝 2: 에이전트를 역할별로 정의하기

.claude/agents/ 아래에 정의 파일을 둡니다.

.claude/agents/
├── researcher.md ← 조사 담당
├── writer.md ← 집필 담당
...

정의 파일의 예:

---
name: researcher
description: >
...

포인트: description:에는 "언제 이 에이전트를 사용하는가"를 명확하게 적습니다. 이는 Claude Code가 에이전트를 선택할 때의 판단 근거가 됩니다.

스텝 3: tools로 권한을 제한하기

에이전트에게 부여하는 툴(Tools)은 필요 최소한으로 합니다.

에이전트	tools	이유
Researcher	WebSearch, WebFetch, Read, Write, Grep, Glob	조사와 저장이 필요함
...	git 조작만 허용
Knowledge Manager	Read, Write, Grep, Glob	정리만 수행, Web 불필요

tools:에 적혀 있지 않은 툴은 해당 에이전트가 호출되어도 사용할 수 없습니다. 이것이 일탈 방지 메커니즘입니다.

스텝 4: 큐(Queue) 시스템으로 상태 관리하기

세션을 넘나들며 상태를 관리하기 위해, 마크다운(Markdown) 파일을 큐(Queue)로 사용합니다.

tasks/
├── inbox/ ← 착수 전 태스크
├── doing/ ← 처리 중 (에이전트가 작업 중)
...

태스크 카드 형식:

---
title: Deep Research 서비스 요금 조사
status: inbox
...

에이전트는 착수 시 카드를 doing/으로 이동시키고, 완료 시 done/으로 이동합니다.

# CLAUDE.md에 작성할 착수 시 지시 사항
# "태스크 착수 전에 카드를 inbox/ → doing/로 이동할 것"
git mv tasks/inbox/CARD.md tasks/doing/

스텝 5: 안전 정지 조건을 명시하기

에이전트가 스스로 멈추는 조건을 CLAUDE.md에 작성합니다.

안전 정지 조건 (다음 사항에 해당하면 blocked/ 로 이동하여 다음 작업 수행)

• 공개·게시·판매·가격·법무 판단이 필요한 경우
• 실제 주문·증권 계좌 조작이 필요한 경우
  ...

이것이 "인간의 판단이 필요한 범위"의 정의입니다. 이 경계가 명확할수록 에이전트는 자율적으로 움직일 수 있습니다. AI에게 맡기는 범위는, 멈추는 조건을 명시함으로써 넓힐 수 있습니다.

자주 발생하는 실패와 대책

실패 1: 모든 에이전트에게 동일한 권한을 부여함

"어차피 괜찮겠지"라는 생각으로 모든 에이전트에게 tools: * (모든 도구)를 부여하면, Writer가 WebSearch를 시작하거나 Researcher가 src/를 마음대로 수정하게 됩니다.

대책: 최소 권한부터 시작하여, 필요할 때 추가합니다.

실패 2: CLAUDE.md에 모든 것을 작성함

CLAUDE.md가 200행을 넘어가면, Claude Code가 중요한 부분을 건너뛰기 시작합니다 (컨텍스트(Context)의 후반부는 우선순위가 낮아집니다).

대책: CLAUDE.md는 200행 이하의 목차로 제한하고, 상세 내용은 rules/ 파일로 분리합니다.

실패 3: 에이전트를 너무 많이 늘려 동시에 실행함

10개의 에이전트를 동시에 가동하면 출력 품질과 책임 소재가 무너집니다.

대책: 부문별로 1건씩, 최대 4~5개 에이전트의 동시 가동으로 제한합니다.

실패 4: 세션 종료 기록을 남기지 않음

다음 세션 시작 시 "어디까지 진행되었는지" 알 수 없게 됩니다.

대책: 세션 종료 전에 반드시 logs/daily/YYYY-MM-DD.md에 작업 로그를 추가하는 규칙 (/session-close 스킬)을 만듭니다.

참고: 최소 구성 파일 목록

이것만 있으면 작동합니다.

project/
├── CLAUDE.md # 목차 (200행 이하)
├── rules/
...

요약

Claude Code 멀티 에이전트 설계의 핵심 포인트 5가지를 정리했습니다.

• CLAUDE.md는 목차 (200행 이하, 상세 내용은 rules/에 위임)
• 에이전트는 1잡(Job) 1정의 (역할을 하나로 좁히고, tools로 권한을 제한)
• 큐(Queue) 시스템으로 상태 관리 (Markdown 파일을 세션을 관통하는 상태로 사용)
• 안전 정지 조건을 명시 (멈추는 조건이 명확할수록 AI는 자율적으로 움직일 수 있음)
• 세션 종료 기록을 반드시 작성 (다음 세션의 재개 비용을 낮춤)

실제로 이 설계로 10일간 가동하고 있습니다. 완성된 시스템이 아니라, 지속적으로 개선 중인 시스템입니다. 진행 상황은 이 시리즈를 통해 계속해서 작성하겠습니다.

이 기사는 Claude(claude-sonnet-4-6)가 초안을 작성하고, 인간(CEO)이 확인 및 편집하였습니다.

Discussion