지난 글에서 Agent에게 Tool 권한을 설계하는 원칙을 정리했다.
기본은 금지, 읽기와 쓰기 분리, 비용이 드는 Tool은 Orchestrator 승인 필수.
이 원칙을 적용하고 나니 자연스럽게 다음 질문이 떠올랐다.
Agent가 여러 명이면 어떻게 되는가?
마침 Anthropic이 Claude Code Agent Teams라는 실험적 기능을 공개했다.
여러 Claude Code 인스턴스가 팀으로 협업하는 기능이다.
공식 문서(https://code.claude.com/docs/ko/agent-teams)를 읽고 직접 써보면서 정리한 내용을 공유한다.
1. Agent Teams? : Subagent와 뭐가 다른가
Claude Code에는 이미 Subagent라는 기능이 있다.
메인 에이전트가 하위 에이전트를 생성하고 결과를 받아서 종합하는 구조다.
Agent Teams는 서브 에이전트와는 다르게 동작하는데,
핵심 차이는 통신 구조다.
# Subagent: 보고만 한다
Main Agent ← 결과 ← Subagent A
Main Agent ← 결과 ← Subagent B
Main Agent ← 결과 ← Subagent C
(Subagent들은 서로 모른다)
# Agent Teams: 서로 대화한다
Team Lead ←→ Teammate A ←→ Teammate B
↕ ↕
Teammate C ←→ Teammate D
(공유 작업 목록 + 직접 메시징)
Subagent는 결과만 중요한 집중 작업에 적합하다.
그만큼 빠르고 토큰 비용도 낮다.
결과가 메인 컨텍스트로 요약되어 돌아오기 때문이다.
Agent Teams는 팀원들이 서로 발견 사항을 공유하고, 서로의 결론에 도전하며,
스스로 조율해야 하는 복잡한 작업에 적합하다.
대신 각 팀원이 별도의 Claude 인스턴스이므로 토큰 비용이 훨씬 높다.
이 구분이 중요한 이유는 비용이다.
일상적인 작업에 Agent Teams를 쓰면 토큰만 낭비된다.
“병렬 탐색이 실질적 가치를 더하는 작업”에만 쓰라는 게 공식 가이드의 핵심 메시지다.
2. 아키텍처: 팀 리더, 팀원, 작업 목록, 메일박스
Agent Teams의 구성 요소는 네 가지다.
팀 리더(Team Lead): 팀을 만들고 팀원을 생성하며 작업을 조율하는 메인 Claude Code 세션이다.
팀을 만드는 세션의 수명 동안 리더로 고정된다. 리더를 바꾸거나 팀원을 리더로 승격시킬 수 없다.
팀원(Teammate): 각각 독립된 Claude Code 인스턴스다. 자신만의 컨텍스트 윈도우를 가진다.
생성될 때 프로젝트의 CLAUDE.md, MCP 서버, 스킬 같은 프로젝트 컨텍스트를 로드하지만 리더의 대화 기록은 상속하지 않는다. 그러므로 팀원에게 작업을 줄 때 충분한 컨텍스트를 생성 프롬프트에 포함해야 한다.
공유 작업 목록(Task List): 팀 전체의 작업을 조율한다. 작업은 대기 중, 진행 중, 완료 세 가지 상태를 가진다.
작업 간 종속성도 관리된다. 하나의 작업이 완료되면 그에 의존하는 차단된 작업이 자동으로 해제된다.
작업 청구(claim)는 파일 잠금을 사용해서 여러 팀원이 동시에 같은 작업을 가져가는 경합 조건을 방지한다.
메일박스(Mailbox): 에이전트 간 통신 시스템이다. 팀원이 메시지를 보내면 수신자에게 자동 전달된다.
리더가 폴링할 필요가 없다.
팀과 작업은 로컬에 저장된다.
~/.claude/teams/{team-name}/config.json # 팀 구성 (멤버 목록)
~/.claude/tasks/{team-name}/ # 공유 작업 목록
3. 활성화부터 팀 생성까지
Agent Teams는 실험적 기능이라 기본적으로 비활성화되어 있다. settings.json에 환경 변수를 추가해서 켠다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
활성화한 뒤에는 자연어로 팀을 만들면 된다. 코드를 쓸 필요가 없다.
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles:
one teammate on UX, one on technical architecture, one playing devil's advocate.
이렇게 요청하면 Claude가 팀을 만들고 팀원을 생성하고 작업을 분배한다.
세 역할이 독립적이라 서로를 기다리지 않고 탐색할 수 있기 때문에 이 예시가 잘 작동한다.
표시 모드는 두 가지가 있다. In-process는 모든 팀원이 메인 터미널 안에서 돌아간다.
Shift+Up/Down으로 팀원을 선택하고 직접 메시지를 보낼 수 있다. 추가 설정이 필요 없다.
분할 창(Split Panes)은 각 팀원이 별도 창을 가진다. tmux나 iTerm2가 필요하다.
macOS에서는 iTerm2에서 tmux -CC를 쓰는 걸 공식적으로 권장한다.
4. AI 엔지니어가 주목할 기능 세 가지
문서를 읽으면서 특히 실무에 유용하겠다고 느낀 기능이 세 가지 있다.
첫째, 계획 승인(Plan Approval) 모드다.
복잡하거나 위험한 작업에서 팀원이 먼저 계획을 세우고 리더가 승인한 뒤에만 구현을 시작하게 할 수 있다.
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
팀원은 읽기 전용 모드에서 계획을 작성하고 리더에게 제출한다.
리더가 승인하면 구현을 시작하고 피드백과 함께 거부하면 계획을 수정해서 다시 제출한다.
이전 글에서 내가 세운 “비용이 드는 Tool은 Orchestrator 승인 필수” 원칙과 같은 맥락이다.
Agent가 코드를 건드리기 전에 사람이(혹은 리더 에이전트가) 검토하는 구조인 셈.
둘째, 위임 모드(Delegation Mode)다.
리더가 직접 작업을 하지 않고 조율에만 집중하게 제한하는 모드다(Shift+Tab으로 전환).
리더가 팀원을 기다리지 않고 직접 코드를 쓰기 시작하는 문제가 실제로 자주 발생한다고 한다.
위임 모드는 리더를 “팀원 생성, 메시징, 종료, 작업 관리” 도구만 쓸 수 있게 제한한다.
셋째, Hooks를 통한 품질 게이트다.
TeammateIdle 훅은 팀원이 유휴 상태로 전환될 때 실행된다.
exit code 2를 반환하면 피드백을 보내고 팀원을 계속 작업시킬 수 있다.
TaskCompleted 훅은 작업이 완료로 표시될 때 실행된다.
exit code 2를 반환하면 완료를 막고 피드백을 보낸다.
자동화된 품질 관리 파이프라인을 만들 수 있는 구조다.
5. 가장 잘 맞는 사용 사례: 병렬 코드 리뷰와 가설 경쟁 디버깅
문서에서 제시하는 사용 사례 중 두 가지가 특히 인상적이었다.
병렬 코드 리뷰.
한 명이 리뷰하면 한 번에 한 가지 유형의 이슈에 치우친다.
보안을 보면 성능을 놓치고, 성능을 보면 테스트 커버리지를 놓친다.
Agent Teams로 리뷰 기준을 독립적 도메인으로 나누면 전부 동시에 철저하게 검토할 수 있다.
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
각 리뷰어가 같은 PR을 다른 필터로 본다. 리더가 전부 끝난 뒤 발견 사항을 종합한다.
경쟁 가설 디버깅.
이게 더 흥미롭다. 근본 원인이 불명확할 때 단일 에이전트는 그럴듯한 설명 하나를 찾고 멈추는 경향이 있다.
Agent Teams는 이걸 구조적으로 해결한다.
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk
to each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.
핵심은 팀원들을 “적대적”으로 만드는 것이다.
각 팀원의 임무가 자기 이론을 조사하는 것뿐 아니라 다른 팀원의 이론을 반박하는 것이기도 하다.
순차적 조사는 하나의 이론이 탐색되면 이후 조사가 그쪽으로 편향된다.
여러 독립 조사자가 동시에 서로를 반박하려 할 때 살아남는 이론이 실제 근본 원인일 가능성이 훨씬 높다.
6. 현재의 제한 사항: 프로덕션에 쓸 수 있는가
솔직하게 말하면 아직 프로덕션에 쓰기엔 이르다는 생각이다.
공식 문서에서도 명시하는 제한 사항이 상당하다.
세션을 재개하면 in-process 팀원이 복원되지 않는다.
리더가 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 시도할 수 있다.
작업 상태가 지연되어 팀원이 작업을 완료로 표시하지 못하면 종속 작업이 차단된다.
세션당 팀은 하나뿐이고 중첩 팀(팀원이 자기 팀을 만드는 것)은 불가능하다.
분할 창 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않는다.(이것때문에 꽤나 고생했다 ㅠ)
그리고 제일 문제는 역시 토큰 비용.
각 팀원이 별도의 Claude 인스턴스이므로 활성 팀원 수에 비례해서 비용이 늘어난다.
팀원 5명이면 단일 세션 대비 5배 이상의 토큰을 쓴다고 봐야 한다.
그럼에도 불구하고 가치가 있는 시나리오가 있다.
코드 리뷰, 라이브러리 리서치, 버그 조사처럼 병렬 탐색의 가치가 명확하고 코드 작성이 필수가 아닌 작업이다.
공식 문서도 이런 작업으로 시작하라고 권장한다.
7. 실전 팁: 문서에서 건진 Agent Teams사용 팁
문서의 모범 사례 섹션에서 실전에 바로 쓸 수 있는 팁들을 정리했다.
팀원에게 충분한 컨텍스트를 주자.
팀원은 리더의 대화 기록을 상속하지 않는다.
생성 프롬프트에 파일 경로, 사용 기술, 집중할 포인트를 구체적으로 적어야 한다.
Spawn a security reviewer teammate with the prompt: "Review the authentication
module at src/auth/ for security vulnerabilities. Focus on token handling,
session management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."
작업 크기를 적절히 조정하자.
너무 작으면 조율 오버헤드가 이점을 초과한다.
너무 크면 팀원이 체크인 없이 너무 오래 작동해서 낭비 위험이 커진다.
팀원당 5~6개 작업을 유지하는 게 좋다고 한다.
파일 충돌을 피하자.
두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생한다.
각 팀원이 다른 파일 집합을 소유하도록 작업을 나눠야 한다.
이건 마이크로서비스에서 서비스 경계를 나누는 것과 비슷한 사고방식이다.
리더가 직접 일하기 시작하면 멈추자.
리더가 팀원을 기다리지 않고 직접 구현을 시작하는 일이 자주 있다.
“Wait for your teammates to complete their tasks before proceeding”이라고 말하면 된다.
또는 위임 모드(Shift+Tab)를 켜면 구조적으로 방지할 수 있다.
마무리하며
Agent Teams를 조사하면서 가장 인상적이었던 것은 “프레임워크”가 아니라 “조율 패턴”이라는 점이다.
팀 리더가 작업을 분해하고, 팀원이 독립적으로 실행하며, 공유 작업 목록으로 상태를 추적하고, 메일박스로 소통한다.
이건 소프트웨어 팀이 Jira 보드와 Slack으로 일하는 방식과 비슷하다.
AI 엔지니어로서 재미있는 것은 사람 팀의 조율 문제가 AI 팀에서도 그대로 반복된다는 점이다.
리더가 위임하지 않고 직접 일하는 문제, 팀원 간 파일 충돌, 작업 상태 동기화 지연.
이미 우리가 잘 아는 문제들이다.
아직 실험적 단계이고 제한 사항도 많지만 방향은 명확하다.
AI 도구가 단일 어시스턴트에서 협업하는 팀으로 진화하고 있다.
이 흐름은 Agent Teams뿐만 아니라 CrewAI, LangGraph, AutoGen, OpenAI Agents SDK 등 업계 전반에서 동시에 일어나고 있다.
다음 글에서는 이런 멀티 에이전트 패턴을 실제로 적용하면서 겪은 경험을 공유하겠다.
기존 단일 파이프라인을 병렬 에이전트 구조로 리팩토링하면서 배운 것들을 정리할 예정이다.
참고 링크
- Claude Code Agent Teams 공식 문서: https://code.claude.com/docs/ko/agent-teams
- Claude Code Subagents 문서: https://code.claude.com/docs/ko/sub-agents
- Anthropic MCP(Model Context Protocol): https://modelcontextprotocol.io/
