Claude Agent Teams를 활용한 병렬처리 사례
TL;DR
Anthropic의 Claude Code에 새로 추가된 Agent Teams 모드는 여러 Claude 인스턴스가 독립적인 컨텍스트 윈도우에서 병렬로 작업하며 서로 직접 소통하는 구조입니다. 기존 Subagent의 "지시-보고" 방식과 달리, 팀원들이 자율적으로 태스크를 분배하고, 토론하며, 공유 태스크 리스트에서 작업을 claim합니다. Anthropic은 이 방식으로 16개 Opus 4.6 인스턴스를 투입해 2주간 $20,000 비용으로 10만 줄의 Rust 기반 C 컴파일러를 구축했으며, Linux 커널, SQLite, PostgreSQL 등을 컴파일하고 GCC 테스트 스위트 99%를 통과하는 성과를 냈습니다.
Key Takeaways
- 병렬 작업의 실질적 가치: Agent Teams는 단순 속도 향상이 아닌 관점의 다양화를 제공합니다. 보안, 성능, 테스트 커버리지 등 전문 영역별로 에이전트를 배치하면 단일 에이전트보다 포괄적인 검토가 가능합니다.
- 자율적 태스크 관리: 공유 태스크 리스트에서 에이전트가 스스로 작업을 claim하고 완료하는 구조로, 중앙 조율 오버헤드 없이 병렬 처리 효율을 극대화할 수 있습니다.
- 격리된 작업 환경과 동기화: Docker를 통한 작업 공간 격리, Git 기반 동기화, Task Lock을 통한 중복 방지 등 체계적인 인프라로 merge conflict까지 에이전트가 자동 해결합니다.
- 실전 검증된 확장성: 10만 줄 규모의 컴파일러 프로젝트를 2,000회 세션에 걸쳐 완수한 사례는 장기 실행 자율 개발의 실현 가능성을 보여줍니다.
- 활성화는 간단하지만 제약 인지 필요: settings.json에 한 줄 추가로 활성화 가능하나, 세션당 하나의 팀만 운영 가능하고 파일 동시 수정 시 충돌이 발생하는 등 현재 실험적 기능의 한계를 이해해야 합니다.
상세 내용
Agent Teams란 무엇인가
Agent Teams는 Claude Code의 새로운 실험적 모드로, 여러 개의 Claude Code 인스턴스가 팀으로 협업하는 구조입니다. 하나의 인스턴스가 리드(lead) 역할을 맡아 작업을 조율하고, 나머지 팀원(teammates)들은 각자 독립적인 컨텍스트 윈도우에서 작업하면서 서로 직접 메시지를 주고받습니다.
기존의 Subagent 방식은 "작업을 시켜놓고 결과만 받는" 일방향 구조였습니다. 반면 Agent Teams는 팀원끼리 토론하고, 서로 반박하며, 태스크를 나눠 가지는 양방향 협업이 가능합니다. 공유 태스크 리스트를 통해 에이전트들이 자율적으로 작업을 claim하고 완료하는 방식으로 운영됩니다.
시작하기: 설정과 활성화
Agent Teams는 Claude Code v2.1.32 이상에서 사용할 수 있는 실험적 기능입니다. 활성화 방법은 매우 간단합니다. settings.json 파일에 다음 설정을 추가하면 됩니다:
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": true
또는 환경 변수로 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 설정할 수도 있습니다.
활성화 후에는 Claude에게 팀 구성을 요청하는 프롬프트를 제공하면 됩니다. 예를 들어, "코드 리뷰를 위해 3명의 전문가 팀을 구성해줘. 한 명은 보안, 한 명은 성능, 한 명은 테스트 커버리지를 담당하도록" 같은 지시가 가능합니다.
실전 활용 사례
병렬 코드 리뷰
가장 직관적인 활용 사례는 관점별 병렬 코드 리뷰입니다. 보안, 성능, 테스트 커버리지를 각각 전담하는 팀원을 배치하면, 단일 에이전트가 순차적으로 검토할 때보다 훨씬 포괄적이고 빠른 리뷰가 가능합니다. 각 팀원은 자신의 전문 영역에 집중하면서도, 필요시 서로 토론하고 반박하며 품질을 높일 수 있습니다.
C 컴파일러 구축: 대규모 프로젝트 사례
Anthropic은 Agent Teams의 가능성을 검증하기 위해 야심찬 실험을 진행했습니다. Claude Opus 4.6 인스턴스 16개를 투입해, 사람의 개입 없이 완전히 자율적으로 Rust 기반 C 컴파일러를 구축하는 프로젝트였습니다.
프로젝트 스펙:
- 기간: 약 2주
- 세션 수: 약 2,000회
- 비용: $20,000
- 결과물: 10만 줄 규모의 Rust 코드
성과:
- Linux 커널(6.9) 컴파일 성공 (x86, ARM, RISC-V 지원)
- QEMU, FFmpeg, SQLite, PostgreSQL, Redis 컴파일 가능
- GCC 테스트 스위트 99% 통과
- Doom 게임 실행 가능
이 프로젝트에서 핵심은 단순히 많은 에이전트를 투입한 것이 아니라, 장기 실행 자율 개발을 가능하게 하는 하네스(harness) 설계였습니다.
아키텍처와 조율 메커니즘
자율 실행 루프
기존 Claude Code는 작업이 완료되면 사용자 입력을 기다리며 멈춥니다. 장기 실행 프로젝트를 위해서는 지속적으로 작업을 이어갈 수 있는 구조가 필요했습니다. Anthropic은 간단한 bash 루프로 이를 구현했습니다:
#!/bin/bash
while true; do
COMMIT=$(git rev-parse --short=6 HEAD)
LOGFILE=agent_logs/agent_${COMMIT}.log
claude --dangerously-skip-permissions \
-p $(cat AGENT_PROMPT.md) \
--model claude-opus-X-Y &> $LOGFILE
done
이 루프는 Claude가 하나의 태스크를 완료하면 즉시 다음 태스크를 픽업하도록 만듭니다. 프롬프트에는 "문제를 작은 조각으로 나누고, 진행 상황을 추적하고, 다음 작업을 스스로 결정하고, 완벽해질 때까지 계속하라"는 지시가 포함되었습니다.
병렬 작업의 조율
여러 에이전트가 동시에 작업할 때 발생하는 문제들을 해결하기 위해 다음과 같은 메커니즘이 사용되었습니다:
Docker 기반 격리: 각 에이전트는 독립된 Docker 컨테이너에서 실행되어 작업 환경이 격리됩니다. 이는 의도치 않은 간섭을 방지하고, 각 에이전트가 안전하게 실험할 수 있는 환경을 제공합니다.
Git 기반 동기화: 모든 에이전트의 작업은 Git을 통해 동기화됩니다. 각 에이전트는 자신의 변경 사항을 커밋하고, 다른 에이전트의 변경 사항을 pull하여 최신 상태를 유지합니다.
Task Lock 시스템: 동일한 작업을 여러 에이전트가 중복으로 수행하는 것을 방지하기 위해 Task Lock 메커니즘이 구현되었습니다. 에이전트가 태스크를 claim하면 다른 에이전트는 해당 작업을 선택할 수 없습니다.
자동 Merge Conflict 해결: 놀랍게도, 발생하는 merge conflict조차 에이전트들이 스스로 해결했습니다. 이는 Agent Teams의 협업 능력이 단순한 병렬 실행을 넘어서는 것을 보여줍니다.
Agent Teams의 이점
1. 진정한 병렬성
단일 Claude Code 세션은 한 번에 하나의 작업만 수행할 수 있습니다. 프로젝트 규모가 커질수록, 여러 이슈를 병렬로 디버깅하는 것이 훨씬 효율적입니다. Agent Teams는 이를 가능하게 합니다.
2. 전문화와 관점의 다양성
여러 에이전트를 활용하면 각 에이전트가 특정 영역에 전문화될 수 있습니다. 보안 전문가, 성능 최적화 전문가, 테스트 전문가 등으로 역할을 분담하면, 각 관점에서 깊이 있는 검토가 가능합니다.
3. 상호 검증과 품질 향상
팀원들 간의 토론과 반박 과정에서 단일 에이전트가 놓칠 수 있는 문제들이 발견됩니다. 서로 다른 접근 방식을 경쟁적으로 시도하는 "competing hypotheses" 방식도 가능합니다.
현재 제약사항과 고려사항
Agent Teams는 실험적 기능이므로 몇 가지 알려진 제약사항이 있습니다:
세션 제한: 세션당 하나의 팀만 운영 가능합니다. 복수의 팀을 동시에 관리하려면 별도의 세션이 필요합니다.
파일 충돌: 같은 파일을 두 팀원이 동시에 수정하면 충돌이 발생할 수 있습니다. 작업 분배 시 파일 단위로 명확하게 영역을 구분하는 것이 좋습니다.
세션 재개 문제: 현재 버전에서는 세션 재개(resumption) 관련 알려진 이슈들이 있습니다.
종료 타이밍: 리드 에이전트가 팀원들의 작업이 완료되기 전에 종료되는 경우가 발생할 수 있습니다. 명시적인 종료 조건 설정이 필요합니다.
고아 tmux 세션: 에이전트가 비정상 종료되면 tmux 세션이 남아있을 수 있습니다. 정기적인 모니터링과 정리가 필요합니다.
베스트 프랙티스
충분한 컨텍스트 제공
각 팀원이 독립적으로 작업할 수 있도록 충분한 컨텍스트를 제공하세요. 프로젝트 목표, 코딩 스타일 가이드, 기술 스택 정보 등을 명확히 공유해야 합니다.
적절한 팀 크기
무조건 많은 에이전트가 좋은 것은 아닙니다. 태스크의 병렬화 가능성, 조율 오버헤드, 비용을 고려하여 적절한 팀 크기를 선택하세요. C 컴파일러 프로젝트에서는 16개가 사용되었지만, 대부분의 경우 3~5개면 충분합니다.
태스크의 적절한 크기 조정
너무 큰 태스크는 병렬화의 이점을 살리기 어렵고, 너무 작은 태스크는 조율 오버헤드가 커집니다. 각 에이전트가 독립적으로 완료할 수 있는 단위로 태스크를 나누세요.
팀원 작업 완료 대기
다음 단계로 진행하기 전에 모든 팀원의 작업이 완료되었는지 확인하세요. 리드 에이전트가 너무 빨리 진행하면 팀원들의 작업이 손실될 수 있습니다.
리서치와 리뷰로 시작
복잡한 구현 작업 전에, 먼저 리서치와 코드 리뷰 같은 안전한 작업으로 Agent Teams를 활용해보세요. 이는 팀의 작동 방식을 이해하고 조율하는 데 도움이 됩니다.
파일 충돌 회피
작업 분배 시 각 팀원이 다른 파일을 담당하도록 명확히 영역을 구분하세요. 동일 파일에 대한 동시 수정은 피하는 것이 좋습니다.
모니터링과 스티어링
Agent Teams는 자율적이지만, 정기적인 모니터링이 필요합니다. 진행 상황을 확인하고, 필요시 방향을 조정하세요. 로그를 활용해 각 에이전트의 활동을 추적할 수 있습니다.
미래 전망
Agent Teams는 AI 기반 소프트웨어 개발의 새로운 패러다임을 보여줍니다. 단일 에이전트의 능력 향상도 중요하지만, 여러 에이전트의 효과적인 협업을 통해 더 복잡하고 큰 규모의 문제를 해결할 수 있습니다.
C 컴파일러 프로젝트는 완전 자율적인 장기 실행 개발이 실현 가능함을 증명했습니다. 물론 $20,000의 비용이 들었지만, 이는 여러 명의 엔지니어가 몇 주간 투입되는 것과 비교하면 경쟁력 있는 수준입니다. 더 중요한 것은, 이 기술이 계속 발전하면서 비용은 낮아지고 능력은 향상될 것이라는 점입니다.
현재는 실험적 기능이지만, Agent Teams의 핵심 아이디어—독립적 컨텍스트, 직접 통신, 자율적 태스크 관리—는 향후 AI 협업 시스템의 표준이 될 가능성이 높습니다.
