2026. 2. 18. 01:59ㆍAI 기술/Claude
2편에서 Claude Code가 "AI 한 명이 직접 코딩하는" 경험을 다뤘습니다. 이번 편에서는 한 단계 더 나아갑니다.
Agent Teams — AI 한 명이 아니라 여러 명이 동시에 일합니다. 한 명은 프론트엔드를 짜고, 한 명은 백엔드를 만들고, 한 명은 그 둘이 만든 코드를 리뷰합니다. 그것도 실시간으로, 서로 대화하면서. 싱글 스레드에서 멀티 스레드로 넘어가는 것과 비슷한 전환입니다.
2편에서 설치와 기본 사용법을 익혔다면, 이 글은 그 다음 레벨입니다.
Claude AI 완전 정복 시리즈 3/9
목차
1. 왜 AI "팀"이 필요한가
2. Agent Teams 아키텍처 — 7가지 도구로 이루어진 시스템
3. 설정 — 딱 한 줄이면 끝
4. 첫 팀 만들기 — 자연어로 지시하기
5. 실전 시나리오 4가지
6. Subagent vs Agent Teams — 언제 뭘 쓰나
7. 화면 모드 — In-process vs Split Pane
8. 비용과 주의사항
9. 실전 팁 — 팀을 잘 쓰는 사람의 습관
10. FAQ
1. 왜 AI "팀"이 필요한가
2편에서 Claude Code 하나로 할 일 앱을 만들어봤습니다. 잘 됐죠. 그런데 프로젝트가 커지면 문제가 생깁니다.
AI 한 명(하나의 세션)이 순차적으로 일하면, API 설계 → 프론트엔드 → 테스트 → 리뷰 → 문서를 한 번에 하나씩 처리합니다. 앞 작업의 컨텍스트가 쌓이면서 뒤쪽 작업의 품질이 떨어집니다. 2편에서 "/compact를 자주 쓰라"고 한 이유가 이겁니다.
Agent Teams는 이 문제를 근본적으로 해결합니다. 각 작업을 별도의 AI에게 맡기고, 각자 깨끗한 컨텍스트에서 일하게 합니다. 프론트엔드 담당 AI는 프론트엔드만 생각하고, 테스트 담당 AI는 테스트만 집중합니다. 사람 팀이 일하는 방식과 똑같습니다.
한 줄 요약: Single Agent는 혼자서 직렬로 일하는 인턴. Agent Teams는 역할을 나눠서 병렬로 일하는 개발팀.
2. Agent Teams 아키텍처 — 7가지 도구로 이루어진 시스템
Agent Teams를 이해하려면 구조를 먼저 알아야 합니다. 복잡하지 않습니다. 핵심 요소 4개와 도구 7개로 이루어져 있습니다.
핵심 요소 4가지
| 요소 | 역할 | 비유 |
|---|---|---|
| Team Lead | 팀 생성, 태스크 배분, 결과 통합. 내가 대화하는 메인 세션. | 팀장 / 테크 리드 |
| Teammate | 독립된 Claude Code 인스턴스. 각자 고유한 컨텍스트 윈도우를 가짐. | 팀원 개발자 |
| Task List | 공유 작업 목록. pending → in_progress → completed. 태스크 간 의존성 설정 가능. | Jira / 칸반 보드 |
| Mailbox | Teammate 간 직접 메시지 교환. JSON 파일 기반. | Slack / 팀 채팅 |
기존의 Subagent와 가장 큰 차이는 통신입니다. Subagent는 결과만 메인에게 보고하는 "파견 일꾼"이었다면, Agent Teams의 Teammate는 서로 메시지를 주고받고, 서로의 작업에 반론을 제기하고, 공유 태스크 보드에서 자율적으로 다음 일을 가져가는 "협업 팀원"입니다.
7가지 도구 (TeammateTool)
| 도구 | 기능 |
|---|---|
TeamCreate |
팀 생성. 팀 이름과 설명을 정의하고 디렉토리 구조를 만듦 |
TaskCreate |
태스크 생성. 제목, 설명, 의존성 설정. Teammate가 읽고 작업할 "업무 지시서" |
TaskUpdate |
태스크 상태 변경. pending → in_progress → completed |
TaskList |
현재 태스크 목록 조회. 진행 상황 확인 |
SendMessage |
Teammate 간 메시지 전송. 메일박스(JSON inbox)를 통해 비동기 전달 |
Shutdown |
Teammate에게 종료 요청. Teammate가 승인하면 종료, 거부하면 이유 설명 |
Cleanup |
팀 리소스 정리. 반드시 Lead가 실행해야 함 |
3. 설정 — 딱 한 줄이면 끝
Agent Teams는 실험적 기능이라 기본적으로 꺼져 있습니다. 켜는 건 간단합니다.
방법 1: settings.json에 추가 (추천)
터미널에서 claude를 실행한 뒤 /config를 열거나, 직접 settings.json 파일을 편집합니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
settings.json에 넣으면 Claude Code가 시작할 때마다 자동으로 적용됩니다. 세션이 바뀌어도 유지되니 이 방법이 가장 편합니다.
방법 2: 환경 변수 (Windows)
PS> $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
// 영구 적용하려면
PS> [System.Environment]::SetEnvironmentVariable(
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "1", "User"
)
방법 2: 환경 변수 (macOS / Linux)
$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
// 영구 적용하려면 .bashrc 또는 .zshrc에 추가
$ echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
권한 설정도 함께 하세요
Teammate는 Lead의 권한을 상속받습니다. 매번 승인을 눌러줄 수 없으니, 자주 쓰는 명령어는 settings.json의 permissions.allow에 미리 허용해두세요. Edit(*), Write(*), Bash(git:*), Bash(npm:*) 정도면 대부분의 작업이 원활합니다. 단, git push --force나 git reset --hard 같은 위험한 명령은 permissions.deny에 반드시 넣어두세요.
4. 첫 팀 만들기 — 자연어로 지시하기
설정을 켰으면 바로 써봅시다. Agent Teams의 가장 놀라운 점은, 팀 구성을 자연어로 지시한다는 겁니다. 수동으로 설정 파일을 만들 필요가 없습니다.
PS> claude
> 결제 모듈을 리팩토링하고 싶어. Agent Team을 만들어줘.
Teammate 3명: API 레이어 담당, DB 마이그레이션 담당,
테스트 커버리지 담당. 공유 태스크 리스트로 조율해줘.
이 한 마디로 Claude가 다음을 자동으로 처리합니다.
먼저 TeamCreate로 팀을 생성하고, TaskCreate로 태스크 목록을 만듭니다. 그 다음 3명의 Teammate를 spawn하는데, 각각에게 역할과 맥락을 부여합니다. Teammate들은 태스크를 자율적으로 가져가서(self-claim) 작업을 시작합니다.
Lead(내가 대화하는 메인 세션)는 진행 상황을 모니터링하고, 필요하면 방향을 수정하고, 최종 결과를 통합합니다.
프롬프트를 잘 쓰는 법
Agent Teams에서 프롬프트 품질은 결정적입니다. Teammate는 Lead의 대화 기록을 상속받지 않기 때문에, spawn할 때 준 지시가 그 Teammate가 아는 전부입니다.
좋은 프롬프트에 들어가야 할 것
1) 구체적인 역할과 목표. 2) 작업할 파일 경로. 3) "완료"의 기준. 4) 다른 Teammate와의 관계 ("Backend가 API 스펙을 줄 때까지 기다려"). 사람 팀원에게 업무를 줄 때 쓰는 것과 같은 수준의 구체적인 브리핑이 필요합니다.
> 인증 시스템을 리뷰할 Agent Team을 만들어줘.
Teammate 3명:
- 보안 리뷰어: src/auth/ 폴더의 보안 취약점 점검.
JWT 토큰 처리, 세션 관리, 입력값 검증에 집중.
심각도 등급을 매겨서 보고해줘.
- 성능 분석가: 응답 시간 프로파일링, 병목 구간 식별.
- 테스트 검증자: 엣지 케이스 확인, 미작성 테스트 발견.
각자 리뷰 후 결과를 공유하고, Lead가 통합 리포트 작성.
5. 실전 시나리오 4가지
Agent Teams가 특히 효과적인 상황이 있습니다. 핵심은 "병렬 탐색이 가치를 만드는 작업"입니다.
시나리오 1: PR 리뷰 (가장 추천하는 입문 시나리오)
사람 한 명이 PR을 리뷰하면 한 가지 관점에 치우치기 쉽습니다. 보안에 집중하면 성능을 놓치고, 성능에 집중하면 테스트 커버리지를 놓칩니다. Teammate 3명에게 각각 보안/성능/테스트라는 "렌즈"를 씌우면, 세 관점이 동시에 철저하게 검토됩니다.
- 보안 리뷰어
- 성능 분석가
- 테스트 커버리지 검증자
각자 리뷰 후 발견사항을 공유해줘.
시나리오 2: 디버깅 토론 (가장 강력한 시나리오)
원인을 모르는 버그가 있을 때, 하나의 에이전트는 한 가지 가설을 찾으면 거기에 "앵커링"되기 쉽습니다. 5명의 Teammate에게 각자 다른 가설을 세우게 하고, 서로 반론하게 하면 — 과학적 토론처럼 가장 강한 가설만 살아남습니다.
Teammate 5명을 spawn해서 서로 다른 가설을 조사해줘.
서로 대화하면서 상대방의 이론을 반증하려고 해봐.
과학적 토론처럼. 합의가 나오면 결과 문서에 정리해줘.
시나리오 3: 풀스택 개발
프론트엔드, 백엔드, 테스트를 각각 담당하는 Teammate를 두면 병렬로 개발할 수 있습니다. 핵심 원칙은 파일 소유권 분리입니다. 두 Teammate가 같은 파일을 편집하면 덮어쓰기가 발생하니까, 각자 담당 폴더/파일을 명확히 나눠야 합니다.
시나리오 4: 설계 탐색
새로운 기능을 설계할 때 UX 전문가, 기술 아키텍트, "악마의 변호인" 세 관점에서 동시에 접근하면, 한 관점에서 놓치는 문제를 다른 관점이 잡아줍니다.
6. Subagent vs Agent Teams — 언제 뭘 쓰나
| Subagent | Agent Teams | |
|---|---|---|
| 통신 | Main에게만 보고 | Teammate 간 직접 대화 |
| 태스크 관리 | 없음 | 공유 리스트 + 의존성 |
| 비용 | 상대적으로 가벼움 | Teammate 수만큼 배로 증가 |
| 적합한 작업 | 빠르고 단순한 병렬 작업 | 조율이 필요한 복잡한 협업 |
| 비유 | 심부름 보낸 파견 직원 | 회의하면서 일하는 팀원 |
판단 기준: "이 Teammate들이 서로 대화할 필요가 있는가?" Yes면 Agent Teams, No면 Subagent가 더 효율적입니다.
7. 화면 모드 — In-process vs Split Pane
Teammate가 일하는 모습을 어떻게 보느냐에 따라 두 가지 모드가 있습니다.
| 모드 | 설명 | 추천 환경 |
|---|---|---|
| In-process | 하나의 터미널에서 Shift+Up/Down으로 Teammate 전환. 기본값. |
VS Code 터미널, Windows Terminal, 일반 환경 |
| Split Pane | tmux 또는 iTerm2에서 Teammate별 패널을 동시에 표시. 실시간 모니터링 가능. | macOS(iTerm2), Linux(tmux) |
| Auto | 환경을 감지해서 자동 선택. tmux 세션 안이면 split pane, 아니면 in-process. | 기본 설정 그대로 사용 |
Windows 사용자 참고
Split pane 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않습니다. Windows에서는 In-process 모드(기본값)를 사용하면 됩니다. Shift+Up/Down으로 Teammate 사이를 전환할 수 있어서 충분히 실용적입니다. WSL 2 환경에서 tmux를 설치하면 split pane도 가능합니다.
8. 비용과 주의사항
Agent Teams는 강력하지만, 공짜 점심은 없습니다.
비용: Teammate 수 = 컨텍스트 윈도우 수
각 Teammate는 독립된 Claude Code 인스턴스입니다. Teammate 3명을 쓰면 토큰 소비가 대략 3배입니다. Pro 플랜($20/월)에서도 쓸 수 있지만, 빈번하게 사용하면 사용량 제한에 금방 도달합니다. 헤비하게 쓸 계획이라면 Max Expanded($100/월)를 고려하세요.
핵심 주의사항 5가지
| # | 주의사항 | 해결법 |
|---|---|---|
| 1 | 같은 파일 동시 편집 = 덮어쓰기 | Teammate별 파일/폴더 소유권 명확히 분리 |
| 2 | Lead가 위임 안 하고 직접 구현 | "Teammate가 완료할 때까지 기다려"라고 명시 |
| 3 | Teammate가 맥락 없이 방황 | spawn 시 구체적 브리핑 필수 |
| 4 | 방치하면 토큰만 소비 | 주기적으로 진행 상황 체크, 방향 수정 |
| 5 | Cleanup을 안 하면 리소스 잔류 | 작업 끝나면 반드시 Lead에서 Shutdown → Cleanup 순서로 |
실험적 기능 참고: Agent Teams는 아직 experimental 상태입니다. 세션 복원이 안 되고, 중첩 팀(Teammate가 또 팀을 만드는 것)도 불가능합니다. Opus 4.6과 함께 출시되었고 빠르게 개선되고 있지만, 프로덕션 핵심 워크플로에 의존하기보다는 "강력한 보조 도구"로 쓰는 게 안전합니다.
9. 실전 팁 — 팀을 잘 쓰는 사람의 습관
1. 첫 팀은 코드 리뷰로 시작하세요
코드를 쓰는 게 아니라 읽는 작업이라 위험이 적습니다. Agent Teams의 조율 패턴을 안전하게 익힌 뒤에 개발 작업으로 넘어가세요.
2. Teammate당 태스크 5~6개가 적당합니다
너무 적으면 금방 끝나서 비효율적이고, 너무 많으면 체크인 없이 오래 돌아가면서 방향이 틀어집니다. 5~6개가 "자율적으로 일하되 관리 가능한" 최적 구간입니다.
3. Plan Mode → Agent Teams 2단계 워크플로
2편에서 배운 Plan Mode를 먼저 쓰세요. Plan Mode에서 전체 계획을 세운 뒤, 그 계획을 Agent Team에 넘기면 품질이 확 올라갑니다. 계획 없이 바로 팀을 돌리면 각자 다른 방향으로 달리기 쉽습니다.
4. Hooks를 활용하세요 (고급)
Claude Code에는 Hook이라는 자동화 기능이 있습니다. TeammateIdle Hook은 Teammate가 할 일이 없어질 때 자동으로 다음 작업을 배정하고, TaskCompleted Hook은 태스크 완료 시 품질 게이트를 걸어줍니다. 테스트 통과 여부를 자동 체크하는 식으로 활용하면 사람이 개입할 일이 크게 줄어듭니다.
5. "전체 앱 만들어줘"는 금물
Agent Teams라고 해서 "대규모 프로젝트를 통째로 던지면 알아서 해줄 것"이라고 기대하면 안 됩니다. 토큰만 태우고 결과물의 품질은 떨어집니다. "명확하게 정의된 5개의 API 엔드포인트를 이 스펙에 맞춰 구현해줘"가 "앱 만들어줘"보다 100배 좋은 결과를 냅니다.
10. FAQ
Q. Pro 플랜($20/월)에서도 Agent Teams를 쓸 수 있나요?
네, 쓸 수 있습니다. 다만 Teammate 수가 늘수록 토큰 소비가 비례하기 때문에, 사용량 제한에 빨리 도달할 수 있습니다. 가벼운 PR 리뷰나 2~3명 규모의 팀으로 시작하는 걸 추천합니다.
Q. Teammate끼리 같은 파일을 수정하면 어떻게 되나요?
마지막에 저장한 쪽이 이깁니다(last-write-wins). 충돌 방지 메커니즘이 있긴 하지만 완벽하지 않습니다. 반드시 파일/폴더 소유권을 명확히 분리하세요. 같은 파일을 건드려야 한다면 태스크 의존성으로 순서를 정해야 합니다.
Q. Teammate는 몇 명까지 만들 수 있나요?
기술적 상한은 명시되어 있지 않지만, Anthropic의 사례 연구에서는 16명까지 사용한 적이 있습니다(C 컴파일러 프로젝트). 실용적으로는 3~5명이 관리하기 적당합니다. 그 이상은 조율 오버헤드가 이점을 상쇄합니다.
Q. VS Code 터미널에서도 되나요?
네. In-process 모드(기본값)로 작동합니다. Split pane 모드는 VS Code 터미널에서 지원되지 않지만, Shift+Up/Down으로 Teammate 사이를 전환할 수 있어서 실사용에 문제 없습니다.
Q. CLAUDE.md는 Teammate에도 적용되나요?
네. Teammate는 프로젝트의 CLAUDE.md, MCP 서버, Skills를 자동으로 로드합니다. 단, Lead의 대화 기록은 상속받지 않습니다. 2편에서 설정한 CLAUDE.md가 그대로 적용되니, "코딩 컨벤션"이나 "절대 건드리면 안 되는 파일" 같은 규칙이 Teammate에게도 전달됩니다.
다음 편 예고 — 4편: MCP 연동 완전 정복
Claude에게 손과 발을 달아주는 기능, MCP(Model Context Protocol). GitHub, Slack, 데이터베이스, 웹 검색 — 외부 도구를 Claude Code에 직접 연결하는 방법을 다룹니다. MCP를 쓰면 Agent Teams의 Teammate가 실시간 데이터에 접근하면서 일할 수 있습니다.
Claude AI 완전 정복 시리즈 전체 글
1편: 내가 반한 AI, Claude — 2026 최신 기능 총정리
2편: Claude Code 입문 — 터미널에서 AI가 코딩한다
3편: Agent Teams 완전 정복 — AI 팀을 병렬로 일시키기 (현재 글)
4편: MCP 연동 — Claude에게 손과 발을 달아주기 (예정)
5편: Claude in Excel — AI가 수식을 진짜로 이해한다 (예정)
6편: Claude in PowerPoint — 내 템플릿으로 슬라이드 만들기 (예정)
7편: Claude.ai 200% 활용법 (예정)
8편: 실전 프로젝트 — 앱 하나 처음부터 끝까지 (예정)
9편: 요금제 비교 + AI 3강 비교 (예정)
Agent Teams는 실험적(experimental) 기능이며, Anthropic의 업데이트에 따라 기능과 인터페이스가 변경될 수 있습니다. 이 글은 2026년 2월 기준이며, 최신 정보는 code.claude.com을 확인하시기 바랍니다.