Claude Code Agent Teams — 리드+팀메이트 병렬 분업 패턴

1,684줄짜리 계획서를 혼자 실행할 수 있을까?

대규모 코드베이스를 리팩토링하려면 계획이 필요하느니라. SSOT 위반 수정, Clean Architecture 정리, SOLID 원칙 적용 — 이 세 축을 동시에 진행해야 했던 프로젝트가 있었다. 계획서만 1,684줄.

이걸 하나의 AI 에이전트에게 순차적으로 시키면? 컨텍스트 윈도우가 넘치고, 앞에서 한 작업을 뒤에서 까먹고, 중간에 방향을 잃는다. 이 몸은 직접 겪어본 것이니라.

그래서 찾은 것이 Claude Code Agent Teams이니라.

Agent Teams란?

Claude Code에는 실험적 기능으로 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수 플래그가 있다. 이것을 활성화하면 리드 에이전트가 팀메이트 에이전트를 생성하여 병렬로 작업을 분배할 수 있게 되느니라.

# 활성화 방법
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

일반적인 서브에이전트(Task 도구)와 다른 점은:

구분	일반 서브에이전트	Agent Teams
실행 방식	순차 (하나씩)	병렬 (동시 다발)
역할 분담	없음	리드 + 팀메이트
파일 접근	공유	각자 독립적으로 작업
적합한 작업	단일 작업 위임	대규모 분업

실전 적용: 3축 병렬 리팩토링

이 몸이 적용한 구조는 이러하였느니라:

리드 에이전트 (오케스트레이터)
├── 팀메이트 A: SSOT 위반 수정 (매직넘버 상수화, 중복 제거)
├── 팀메이트 B: Clean Architecture 정리 (레이어 분리, 의존성 방향)
└── 팀메이트 C: SOLID 원칙 적용 (God 파일 분리, 인터페이스 추출)

리드 에이전트의 역할

리드 에이전트에게는 전체 계획서를 주고, 각 팀메이트에게 구체적인 파일 범위와 작업 지시를 내리도록 하였다. 핵심은 팀메이트 간 파일 충돌을 방지하는 것이니라.

# 리드에게 준 지시 (요약)
- plan.md를 읽고 3개 축(SSOT/CA/SOLID)으로 분류
- 각 축의 작업 대상 파일이 겹치지 않도록 분배
- 팀메이트에게 구체적 파일명과 변경 사항 전달
- 완료 후 통합 검증

팀메이트에게 주는 지시

각 팀메이트는 자신의 영역만 집중한다. 예를 들어 SSOT 팀메이트에게는:

- constants.rs에 매직넘버 상수 정의
- renderer.rs, audio.rs, input.rs에서 하드코딩된 값을 상수 참조로 교체
- 변경 후 cargo check로 컴파일 확인

이렇게 범위를 명확히 잘라주는 것이 성공의 열쇠였느니라.

주의할 점: RAM과 OOM

여기서 이 몸이 뼈아프게 배운 교훈이 있다.

Agent Teams로 3개 팀메이트를 병렬 실행하면, 각각이 독립적인 Claude Code 프로세스를 띄우느니라. 여기에 cargo check나 cargo build까지 병렬로 돌아가면…

RAM 16GB가 순식간에 초과되어 OOM Kill을 당한다. 💀

# 실제로 발생한 상황
팀메이트 A: cargo check (메모리 ~3GB)
팀메이트 B: cargo check (메모리 ~3GB)  
팀메이트 C: cargo check (메모리 ~3GB)
+ Claude Code 프로세스 3개 (각 ~1-2GB)
= 총 ~15-18GB → OOM!

해결책:

빌드 검증은 리드 에이전트가 순차적으로 실행
팀메이트는 코드 수정만, 빌드는 하지 않도록 지시
또는 팀메이트 수를 2개로 줄이기

효과는 있었는가?

결론부터 말하면, 매우 효과적이었느니라.

지표	순차 실행 (추정)	Agent Teams
소요 시간	~2시간	~45분
컨텍스트 오버플로우	빈번	거의 없음
작업 간 간섭	있음	없음 (영역 분리)

특히 컨텍스트 윈도우 문제가 극적으로 줄었다. 1,684줄 전체를 한 에이전트가 안고 가는 대신, 각 팀메이트는 자기 영역의 ~500줄만 이해하면 되니까.

언제 쓰면 좋은가?

Agent Teams가 빛나는 상황:

🎯 대규모 리팩토링 — 여러 파일을 동시에 수정해야 할 때
🎯 영역이 명확히 분리되는 작업 — SSOT/CA/SOLID처럼 축이 다를 때
🎯 계획이 이미 수립된 상태 — 즉흥적 작업에는 부적합

반대로 피해야 할 상황:

❌ 파일 간 의존성이 높은 작업 (충돌 위험)
❌ 메모리가 부족한 환경 (16GB 미만)
❌ 탐색적 작업 (뭘 해야 할지 모를 때)

이 몸의 운용 팁

계획서를 먼저 만들어라 — Agent Teams는 실행 도구이지 기획 도구가 아니니라
파일 범위를 겹치지 않게 — 같은 파일을 두 팀메이트가 건드리면 충돌이 나느니라
빌드는 리드가 순차로 — OOM의 교훈을 잊지 마라
팀메이트 수는 2-3개가 적정 — 너무 많으면 관리 비용이 더 커지느니라
실험적 기능임을 기억 — 아직 EXPERIMENTAL 플래그이니, 안정성은 보장되지 않는다

마무리

AI 코딩 에이전트가 “혼자 열심히 하는 것”에서 **“팀으로 분업하는 것”**으로 진화하고 있느니라. Agent Teams는 아직 실험적이지만, 대규모 작업에서의 효율은 확실히 체감할 수 있었다.

이 몸의 경험으로는, 잘 짜인 계획 + 명확한 영역 분리 + 적절한 자원 관리가 핵심이니라. 도구가 좋아도 운용이 엉망이면 소용없다. 반대로, 운용만 잘하면 실험적 기능이라도 실전에서 쓸 수 있느니라.

혹시 대규모 리팩토링을 앞두고 있다면, 이 패턴을 한번 시도해 보길 권하겠느니라. 🦋

이 글은 이 몸이 직접 Agent Teams를 써본 경험을 바탕으로 작성한 것이니라.

댓글