2026년 3월 14일

Claude Code 200% 활용하기 (3) — 서브에이전트, 에이전트 팀

서론

Part 1에서 메모리·스킬·훅을, Part 2에서 플러그인·MCP·IDE 연동을 다뤘다.

시리즈 마지막 Part 3에서는 Claude Code의 최강 기능을 다룬다:

서브에이전트: 특정 작업을 전담하는 전문 AI 보조를 만들어 위임
에이전트 팀: 여러 Claude Code 인스턴스가 팀을 이뤄 병렬 협업

1. 서브에이전트 — 전문가에게 위임하기

서브에이전트는 특정 작업을 전담하는 독립 AI 보조다. 각 서브에이전트는 자신만의 컨텍스트 윈도우, 시스템 프롬프트, 도구 접근 권한을 가진다. Claude가 적합한 작업을 만나면 자동으로 해당 서브에이전트에게 위임한다.

1.1 왜 서브에이전트인가

컨텍스트 보존: 탐색·조사 결과가 메인 대화를 오염시키지 않는다
제약 강제: 특정 도구만 사용하도록 제한할 수 있다
비용 절감: 빠르고 저렴한 모델(Haiku)로 라우팅 가능
전문화: 도메인별 시스템 프롬프트로 정확도 향상

1.2 내장 서브에이전트

Claude Code에는 기본 내장된 서브에이전트가 있다:

에이전트	모델	도구	용도
Explore	Haiku (빠름)	읽기 전용	코드베이스 탐색, 파일 검색
Plan	상속	읽기 전용	계획 모드에서 컨텍스트 수집
General-purpose	상속	전체	복잡한 멀티스텝 작업
Claude Code Guide	Haiku	읽기 전용	Claude Code 기능 질문

Explore 에이전트는 코드베이스를 탐색할 때 자동으로 사용된다. 탐색 결과가 메인 대화 컨텍스트를 낭비하지 않으면서도 필요한 정보를 가져온다.

1.3 커스텀 서브에이전트 만들기

/agents 명령어

# Claude Code 안에서
/agents
# → Create new agent → User-level 또는 Project-level 선택
# → Generate with Claude 또는 직접 작성

직접 파일로 작성

서브에이전트는 YAML 프론트매터가 있는 마크다운 파일이다.

저장 위치:

위치	범위	우선순위
`.claude/agents/`	이 프로젝트	높음
`~/.claude/agents/`	모든 프로젝트	중간
플러그인 `agents/`	플러그인 활성화 시	낮음

예시: 코드 리뷰어

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드 품질과 보안을 점검하는 전문 리뷰어. 코드 변경 후 자동으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---

시니어 코드 리뷰어로서 코드 품질과 보안을 검사한다.

실행 시:
1. git diff로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드 가독성과 구조
- 에러 핸들링
- 보안 취약점 (API 키 노출 등)
- 테스트 커버리지

피드백은 우선순위별로 정리:
- Critical (반드시 수정)
- Warning (수정 권장)
- Suggestion (개선 제안)

사용:

코드 리뷰어 서브에이전트로 최근 변경사항 리뷰해줘

예시: 디버거

---
name: debugger
description: 에러, 테스트 실패, 예상치 못한 동작을 디버깅하는 전문가
tools: Read, Edit, Bash, Grep, Glob
---

디버깅 프로세스:
1. 에러 메시지와 스택 트레이스 확인
2. 재현 단계 파악
3. 가설 수립 및 검증
4. 최소한의 수정 적용
5. 수정 결과 검증

1.4 서브에이전트 설정 옵션

모델 선택

model: haiku    # 빠르고 저렴
model: sonnet   # 균형
model: opus     # 최고 성능
model: inherit  # 메인 대화와 동일 (기본값)

도구 제한

# 허용 도구만 지정
tools: Read, Grep, Glob, Bash

# 특정 도구 금지
disallowedTools: Write, Edit

MCP 서버 연결

서브에이전트에만 MCP 서버를 연결할 수 있다. 메인 대화에는 노출되지 않으므로 컨텍스트를 절약한다:

---
name: browser-tester
description: Playwright로 브라우저 테스트
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github  # 이미 설정된 서버 참조
---

영구 메모리

서브에이전트에게 대화를 넘어 지속되는 메모리를 부여할 수 있다:

---
name: code-reviewer
description: 코드 리뷰 전문가
memory: user  # user | project | local
---

범위	위치	용도
`user`	`~/.claude/agent-memory/`	모든 프로젝트에서 학습 유지
`project`	`.claude/agent-memory/`	프로젝트별 지식 (Git 공유 가능)
`local`	`.claude/agent-memory-local/`	프로젝트별, 나만 사용

Git 워크트리 격리

isolation: worktree

서브에이전트가 별도의 Git 워크트리에서 작업한다. 메인 코드에 영향을 주지 않으면서 독립적으로 변경할 수 있다. 변경이 없으면 워크트리는 자동 정리된다.

1.5 포그라운드 vs 백그라운드

포그라운드: 서브에이전트가 끝날 때까지 메인 대화가 대기한다. 허가 요청이 사용자에게 전달된다.
백그라운드: 메인 대화와 병렬 실행. Ctrl+B로 진행 중인 작업을 백그라운드로 전환할 수 있다.

서브에이전트를 백그라운드로 테스트 실행하고, 실패한 테스트만 보고해줘

1.6 활용 패턴

대용량 출력 격리

테스트 실행, 로그 분석 같은 대량 출력 작업을 서브에이전트에 위임하면, 메인 대화 컨텍스트를 낭비하지 않고 요약만 받을 수 있다:

서브에이전트로 전체 테스트 스위트 실행하고, 실패한 테스트와 에러 메시지만 보고해줘

병렬 조사

독립적인 조사는 여러 서브에이전트를 동시에 띄워 병렬로 진행한다:

인증, 데이터베이스, API 모듈을 각각 별도 서브에이전트로 조사해줘

체이닝

순차적 워크플로우에서는 서브에이전트를 연쇄적으로 사용한다:

코드 리뷰어 서브에이전트로 성능 이슈를 찾고, 그 다음 옵티마이저 서브에이전트로 수정해줘

2. 에이전트 팀 — 여러 Claude가 함께 일하기

⚠️ 에이전트 팀은 실험 기능이다. 기본적으로 비활성화되어 있다.

에이전트 팀은 여러 Claude Code 인스턴스가 팀을 이뤄 협업하는 기능이다. 한 세션이 팀 리드 역할을 하고, 팀원들은 각자의 컨텍스트 윈도우에서 독립적으로 작업하면서 서로 직접 소통한다.

2.1 서브에이전트 vs 에이전트 팀

	서브에이전트	에이전트 팀
컨텍스트	독립 윈도우, 결과를 메인에 반환	완전히 독립
소통	메인 에이전트에만 보고	팀원끼리 직접 메시지
조정	메인 에이전트가 관리	공유 태스크 리스트로 자율 조정
적합한 경우	결과만 필요한 집중 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음	높음 (각 팀원이 별도 인스턴스)

서브에이전트는 “결과만 가져와” 방식. 에이전트 팀은 “같이 논의하면서 해결” 방식.

2.2 활성화

settings.json에 추가:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2.3 팀 시작하기

자연어로 팀 구성을 설명하면 된다:

CLI 도구를 설계하려고 해. 에이전트 팀을 만들어서 세 가지 관점에서 탐색해줘:
- 하나는 UX
- 하나는 기술 아키텍처
- 하나는 데빌스 어드보킷(반론)

Claude가 팀을 생성하고, 팀원을 배정하고, 작업을 조율한다.

2.4 디스플레이 모드

모드	설명	환경
in-process	모든 팀원이 하나의 터미널에서 실행	모든 터미널
split panes	각 팀원이 별도 창	tmux 또는 iTerm2 필요

{
  "teammateMode": "in-process"
}

Shift+Down으로 팀원 간 전환. 각 팀원에게 직접 메시지를 보낼 수 있다.

2.5 팀원과 소통

리드 → 팀원: 태스크 할당, 지시
팀원 → 팀원: 직접 메시지로 발견 사항 공유, 상대방 이론에 반론
사용자 → 팀원: Shift+Down으로 팀원 선택 후 직접 지시

보안 리뷰어 팀원에게 인증 모듈 집중 검토하라고 해

2.6 태스크 관리

공유 태스크 리스트로 작업을 조율한다:

리드가 태스크를 생성하고 할당
팀원이 작업을 완료하면 다음 미할당 태스크를 자동으로 가져감
태스크 간 의존성도 관리 (선행 태스크 완료 전까지 후속 태스크 블록)

2.7 계획 승인 모드

복잡하거나 위험한 작업에는 팀원이 먼저 계획을 세우도록 요구할 수 있다:

architect 팀원이 인증 모듈을 리팩토링하되, 변경 전에 계획 승인을 받도록 해줘

팀원이 계획을 제출하면 리드가 검토 후 승인/반려한다. 반려 시 피드백을 반영해 수정.

2.8 실전 활용 사례

병렬 코드 리뷰

PR #142를 에이전트 팀으로 리뷰해줘. 세 명의 리뷰어:
- 보안 관점
- 성능 관점
- 테스트 커버리지 관점

각 리뷰어가 동일한 PR을 다른 관점에서 동시에 분석한다.

경쟁 가설 디버깅

사용자가 앱이 한 번 메시지 보내고 종료된다고 보고했어.
5명의 에이전트 팀원을 만들어 서로 다른 가설을 조사하게 해.
서로 상대방의 이론을 반증하려고 과학적 토론을 하도록 해.

혼자 디버깅하면 첫 번째 가설에 고착되기 쉽다. 팀원들이 서로의 이론에 반론을 제기하면서 실제 원인에 더 빨리 도달한다.

2.9 모범 사례

충분한 컨텍스트 제공: 팀원은 리드의 대화 히스토리를 상속받지 않는다. 스폰 프롬프트에 필요한 정보를 모두 포함해야 한다.
3-5명이 적당: 토큰 비용과 조율 오버헤드를 고려하면 이 범위가 최적이다.
팀원당 5-6개 태스크: 각 팀원이 너무 한가하지도 너무 바쁘지도 않게.
파일 충돌 방지: 같은 파일을 여러 팀원이 동시에 수정하면 덮어쓰기가 발생한다. 각 팀원이 다른 파일을 담당하도록 분배.
주기적 확인: 팀원의 진행 상황을 체크하고, 잘못된 방향이면 재조정.

2.10 제한 사항

세션 재개 시 in-process 팀원은 복원되지 않는다
한 세션에 하나의 팀만 운영 가능
팀원은 자기 팀이나 하위 팀을 만들 수 없다
리드 역할은 변경 불가
split pane 모드는 VS Code 통합 터미널에서 미지원

3. Oh My Claude Code — 커뮤니티 멀티에이전트 프레임워크

Oh My Claude Code(OMCC)는 Claude Code 위에 멀티에이전트 오케스트레이션을 올린 커뮤니티 오픈소스 프로젝트다. Oh My Zsh가 zsh를 확장하듯, OMCC는 Claude Code에 에이전트·스킬·자동 모델 라우팅을 추가한다.

3.1 주요 기능

32개 전문 에이전트: 아키텍처, 보안, 테스트, 코드 리뷰, 데이터 사이언스 등 도메인별 에이전트가 기본 포함
40개 이상 스킬: 자주 쓰는 개발 작업용 스킬이 사전 설정됨
스마트 모델 라우팅: 작업 복잡도에 따라 Haiku(단순) ↔ Opus(복잡) 자동 전환. 30-50% 토큰 절감 효과

3.2 오케스트레이션 모드

모드	설명	적합한 경우
Team	`plan → prd → exec → verify → fix` 파이프라인	체계적인 기능 개발
Autopilot	완전 자동 실행, 사용자 개입 없음	단순 기능 구현
Ultrapilot	최대 5개 워커 병렬 실행	멀티 컴포넌트 프로젝트
Ralph	완료될 때까지 반복 검증/수정	중요한 작업
Pipeline	순차 스테이지 처리	멀티스텝 변환

3.3 에이전트 팀 vs OMCC

	에이전트 팀 (내장)	OMCC (커뮤니티)
설치	환경 변수 하나로 활성화	플러그인 마켓플레이스에서 설치
설정	자연어로 팀 구성	키워드(`ralph`, `autopilot` 등)로 모드 선택
에이전트 수	직접 정의 또는 자연어 요청	32개 사전 정의
모델 라우팅	수동 (`model:` 지정)	자동 (복잡도 기반)
워크플로우	자유형 — 팀원이 자율 조정	구조화 — 파이프라인/검증 루프
토큰 비용	높음 (각 팀원 별도 인스턴스)	라우팅으로 30-50% 절감
안정성	실험 기능	커뮤니티 유지보수
적합한 경우	토론·반론이 필요한 협업	체계적이고 반복 가능한 워크플로우

에이전트 팀은 “여러 Claude가 토론하며 해결”하는 방식이고, OMCC는 “미리 짜인 파이프라인으로 체계적으로 처리”하는 방식이다. 둘은 상충하지 않으며, OMCC를 설치한 상태에서 에이전트 팀을 함께 사용할 수도 있다.

OMCC의 대표 기능인 Ralph(완료될 때까지 반복 검증/수정)는 Claude Code 공식 플러그인에도 ralph-wiggum이라는 이름으로 포함되어 있다. OMCC를 설치하지 않아도 공식 플러그인 마켓플레이스에서 바로 사용할 수 있다.

3.4 설치

# Claude Code 플러그인으로 설치
/plugins  # 마켓플레이스에서 oh-my-claudecode 검색 후 설치

자세한 내용은 OMCC 공식 문서를 참고.

시리즈를 마치며

3편에 걸쳐 Claude Code의 고급 기능을 모두 다뤘다:

Part	주제	핵심
Part 1	메모리 + 스킬 + 훅	Claude가 나를 기억하고, 반복 작업을 자동화
Part 2	플러그인 + MCP + IDE	외부 도구를 연결하고, IDE에서 바로 사용
Part 3	서브에이전트 + 에이전트 팀	작업을 분할하고, 병렬로 처리

이 기능들을 조합하면 Claude Code는 단순한 채팅봇이 아니라, 나의 프로젝트에 최적화된 개발 파트너가 된다:

CLAUDE.md로 규칙을 정하고
커스텀 스킬로 반복 작업을 자동화하고
훅으로 파일 보호, 포맷팅, 알림을 설정하고
플러그인으로 팀과 공유하고
MCP로 GitHub, Sentry, DB를 연결하고
서브에이전트로 전문가에게 위임하고
에이전트 팀으로 복잡한 작업을 병렬 처리한다

이 모든 걸 한 번에 다 쓸 필요는 없다. 하나씩 적용해보면서 자신의 워크플로우에 맞는 조합을 찾아가면 된다.