이 글은 터미널 사용, Git, 기본적인 소프트웨어 개발 경험이 있는 분을 대상으로 작성했다. 프로그래밍을 처음 접하는 경우에는 먼저 기초를 다진 뒤 돌아오는 걸 추천한다.

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. 2026년 2월 기준으로 Opus 4.6 출시와 함께 "Agent Teams" 기능이 추가되면서, 여러 AI 에이전트가 동시에 작업하고 서로 소통하는 멀티 에이전트 개발이 가능해졌다.

이 글에서는 Claude Code 설치부터 Opus 4.6 + Sonnet 4.6 조합의 멀티 에이전트 환경 구성까지 다룬다.

Claude Code 설치

Node.js 22 이상 필요.

npm install -g @anthropic-ai/claude-code

설치 후 프로젝트 디렉토리에서 claude 명령어를 실행하면 된다.

cd your-project
claude

최초 실행 시 Anthropic 계정 인증을 진행한다. Pro ($20/월) 또는 Max ($100/월, $200/월) 구독이 필요하다.

구독 선택

Pro ($20/월): Opus 4.6, Sonnet 4.6 사용 가능. 일반적인 개인 개발에 충분하다.
Max 5x ($100/월): Pro 대비 5배 용량. 멀티 에이전트를 자주 쓰면 이쪽이 현실적이다.
Max 20x ($200/월): 헤비 유저용. Agent Teams를 하루 종일 돌릴 경우.

멀티 에이전트는 에이전트 수만큼 토큰을 소비한다. 에이전트 3개를 동시에 돌리면 단일 세션 대비 약 3~5배 비용이 나온다. Pro 플랜으로 시작해보고 한도에 자주 걸리면 Max로 올리는 게 합리적이다.

모델 역할 분담

Opus 4.6과 Sonnet 4.6은 성격이 다르다. 적재적소에 쓰는 게 핵심이다.

Opus 4.6: 1M 토큰 컨텍스트 윈도우. 복잡한 아키텍처 설계, 대규모 리팩토링, 멀티파일 수정, 디버깅에 강하다. 느리지만 정확하다.
Sonnet 4.6: 빠르고 저렴하다. 단일 파일 수정, 테스트 작성, 반복 작업, 콘텐츠 생성에 적합하다.

실전에서는 이렇게 나눈다:
- 메인 세션 (팀 리드): Opus 4.6 — 전체 설계, 태스크 분배, 결과 검토
- 서브 에이전트들: Sonnet 4.6 — 개별 구현, 테스트 작성, 단순 수정

CLAUDE.md 설정

프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code가 매 세션 시작 시 자동으로 읽는다. 여기에 프로젝트 규칙, 코딩 컨벤션, 에이전트 지침을 넣으면 된다.

예시:

CLAUDE.md

프로젝트 구조

Django + React 모노레포
백엔드: /api, 프론트: /web
테스트: pytest (백엔드), vitest (프론트)

규칙

코드 수정 시 반드시 테스트 포함
커밋 전 pytest 통과 확인
타입 힌트 필수 (Python), TypeScript strict 모드 (프론트)

모델 전략

아키텍처/디버깅: Opus 4.6
구현/테스트: Sonnet 4.6

이 파일이 잘 작성되어 있으면 에이전트가 프로젝트 맥락을 정확히 이해한 상태에서 작업을 시작한다. 멀티 에이전트 환경에서는 특히 중요하다. 각 에이전트가 동일한 규칙을 공유하기 때문이다.

Agent Teams 활성화

Agent Teams는 현재 Research Preview 상태이므로 수동으로 활성화해야 한다.

방법 1: settings.json에 추가 (권장, 영구 적용)

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_ TEAMS": "1"
  }
}

방법 2: 환경 변수 (셸 프로필에 추가)

export CLAUDE_CODE_EXPERIMENTAL_AGENT_T EAMS=1

방법 3: 일회성 실행

CLAUDE_CODE_EXPERIMENTAL_AGENT_T EAMS=1 claude

Agent Teams vs Subagents

Claude Code에는 두 가지 멀티 에이전트 방식이 있다. 혼동하기 쉬우니 정리한다.

Subagents:
- 메인 에이전트가 하위 에이전트를 생성
- 하위 에이전트는 결과만 메인에게 반환
- 하위 에이전트끼리 통신 불가
- 토큰 비용 낮음 (결과가 요약되어 반환)
- 용도: "이 파일 조사해서 알려줘" 같은 단방향 작업

Agent Teams:
- 팀 리드가 팀원을 생성하고 태스크를 분배
- 팀원끼리 직접 메시지를 주고받을 수 있음
- 공유 태스크 리스트로 의존성 관리
- 토큰 비용 높음 (각 팀원이 독립 세션)
- 용도: "프론트, 백엔드, 테스트 각각 맡아서 동시에 진행해" 같은 협업 작업

작업 규모가 작으면 Subagent로 충분하다. 여러 영역을 동시에 건드려야 하는 경우에만 Agent Teams를 쓰는 게 효율적이다.

실전 사용 예시

Agent Teams를 활성화한 후, 자연어로 지시하면 된다.

이 프로젝트에 다크 모드를 추가해야 해. 팀을 구성해줘:
1. 프론트엔드 담당 - CSS 변수 시스템 구축, 컴포넌트별 다크 모드 적용
2. 백엔드 담당 - 사용자 테마 설정 저장 API 추가
3. 테스트 담당 - 1번과 2번 작업 완료되면 통합 테스트 작성

Claude가 팀원을 생성하고, 각자 독립적으로 작업을 시작한다. 팀원 간 의존성이 있으면 (예: 테스트 담당은 구현 완료 후 시작) 자동으로 대기한다.

모니터링은 키보드로 한다:
- Shift+Up/Down: 팀원 선택
- Enter: 해당 팀원 세션 보기
- Ctrl+T: 태스크 리스트 토글
- Escape: 팀원 작업 인터럽트

디스플레이 모드

in-process (기본): 하나의 터미널에서 팀원을 전환하며 확인. 별도 설정 불필요.

tmux: 각 팀원이 별도 터미널 패널에서 실행. 동시에 모든 에이전트 출력을 볼 수 있다.

{
  "teammateMode": "tmux"
}

tmux 모드는 VS Code 내장 터미널에서는 작동하지 않는다. iTerm2나 기본 터미널 앱을 사용해야 한다.

비용 관리 팁

탐색/조사 작업은 Subagent의 Explore 모드를 활용한다. Haiku 모델을 사용하므로 저렴하다.
단순 구현은 Sonnet 4.6으로 라우팅한다. CLAUDE.md에 명시해두면 Claude가 알아서 판단한다.
Opus 4.6은 설계, 리뷰, 복잡한 디버깅에만 쓴다.
Agent Teams는 정말 필요할 때만 쓴다. 대부분의 작업은 단일 세션 + Subagent 조합이면 된다.

참고

Claude Code 공식 문서: https://code.claude.com/docs
Subagent 설정: https://code.claude.com/docs/en/sub-agents
Agent Teams는 Research Preview 단계이므로 향후 변경될 수 있다.
Anthropic 구독: https://claude.ai (Pro/Max)

Claude Code 멀티 에이전트 개발 환경 세팅 가이드 (Opus 4.6 + Sonnet 4.6)