Claude Code Agent Teams: 1M 컨텍스트로 병렬 리팩터링 돌리기

결론부터. Claude Code Agent Teams는 여러 Claude Code 세션이 팀처럼 움직이는 실험 기능이고, 리팩터링·코드 리뷰·복잡한 원인 분석처럼 병렬 탐색이 필요한 일에 맞아요. 2026-05-10 기준 공식 문서에는 Claude Code v2.1.32 이상, 리더 모델 Opus 4.6 이상, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, 팀원별 독립 컨텍스트, 직접 메시지 교환, 높은 토큰 사용량이 핵심으로 잡혀 있어요.

3~5명 팀, Git Worktree 격리, Plan Mode 선행. 이 셋을 빼면 속도보다 충돌과 비용이 먼저 와요.

Agent Teams를 처음 켰을 때 제일 먼저 드는 생각은 이거예요. “이거 그냥 Subagent 여러 개 띄운 거 아닌가?” 근데 써보면 다르더라고요. Claude Code Agent Teams는 리더 세션이 있고, 팀원 세션이 따로 있고, 팀원끼리 메시지를 주고받아요. 컨텍스트도 각자 따로 가져가죠. 그래서 큰 PR(Pull Request, 코드 변경 요청)을 보안·성능·테스트·로직 관점으로 나눠 보는 일에는 꽤 잘 맞아요.

문제도 빨리 와요. 토큰이 팀원 수만큼 늘고, 같은 파일을 두 명이 건드리면 충돌이 나고, 긴 세션에서는 컨텍스트 압축 뒤 팀 상태가 꼬일 수 있어요. 이 글은 “켜는 법”보다 “언제 켜고, 어떻게 안 터뜨릴지”에 초점을 둬요. 먼저 Agent Teams와 Subagent(한 세션 안에서 호출되는 보조 작업자)를 나누고, 그다음 Worktree 격리와 비용 계산까지 한 번에 잡을게요. 컨텍스트 설계 자체가 처음이면 AI 컨텍스트 엔지니어링: Notion·Claude·Cursor 분담법을 먼저 보면 흐름이 더 빨라요.

Claude Code Agent Teams가 Subagent랑 뭐가 다른지부터

Claude Code Agent Teams와 Subagent의 차이는 “팀원끼리 직접 말할 수 있느냐”예요. Subagent는 메인 세션이 일을 던지고 결과를 받는 구조고, Agent Teams는 공유 태스크 목록과 메시지함으로 팀원들이 서로 조율해요.

굳이 팀까지 띄울 이유가 있을까요? 루틴 작업이면 없어요. 공식 문서도 순차 작업, 같은 파일 편집, 의존성이 많은 작업에는 단일 세션이나 Subagent가 더 낫다고 봐요.

구분	Subagent	Agent Teams
구조	메인 세션 안의 보조 작업자	독립 Claude Code 세션 여러 개
소통	메인 세션에 결과 보고	팀원끼리 직접 메시지
컨텍스트	결과가 요약돼 돌아옴	팀원마다 자기 컨텍스트
비용	상대적으로 낮음	팀원 수만큼 커짐
맞는 일	짧은 조사, 테스트 보강, 파일 단위 수정	복잡한 리뷰, 경쟁 가설 디버깅, 모듈별 리팩터링

처음엔 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지 쪽 패턴으로 충분한지 먼저 봐야 해요. “팀원끼리 토론해야 한다”가 아니면 Agent Teams는 과해요.

참고로 공식 문서 기준으로 팀원은 자기 컨텍스트를 따로 갖고, 리더 대화 기록을 그대로 물려받지 않아요. 그래서 spawn prompt, 즉 팀원을 만들 때 주는 첫 지시문에 파일 범위·성공 기준·금지 작업을 다 넣어야 해요. 안 그러면 활동량은 많은데 결과가 애매해져요.

쓸 수 있는 환경과 첫 세팅

Agent Teams는 Claude Code 기능이라 CLI(터미널) 기준으로 세팅하는 게 제일 명확해요. 다만 Claude Code 자체는 터미널, VS Code, JetBrains, Desktop App, Web, Slack 진입점을 갖고 있어서 “어디서 시작하고 어디서 관리할지”를 먼저 골라야 해요.

진입점마다 강점이 좀 갈려요. Desktop App은 macOS와 Windows 쪽 GUI가 강하고, Linux는 CLI 쪽으로 가야 해요. VS Code는 diff 리뷰와 Plan Mode(편집 전에 계획을 먼저 승인받는 모드) 피드백이 편하고, 터미널은 자동화와 플래그 제어가 좋아요.

사용 환경	2026-05-10 기준 체크	Agent Teams 메모
Terminal CLI	claude 명령으로 실행	세팅과 디버깅 기준점
VS Code	Claude Code 확장, diff 보기, Plan Mode	Web 원격 세션 일부 이어받기 가능
JetBrains	전용 확장	IDE 안에서 흐름 유지
Desktop App	macOS/Windows, 자동 Worktree 세션	Linux는 CLI 사용
Web	Claude Code on the Web	원격 작업 시작점으로 보기
Slack	작업 킥오프 진입점	세부 조율은 별도 확인 필요

첫 세팅은 짧아요. 근데 버전부터 봐야 해요. Agent Teams는 Research Preview·Experimental 단계라 공식 문서가 Claude Code v2.1.32 이상을 요구하고, 리더 모델은 Opus 4.6 이상이어야 동작해요. Sonnet으로 리더를 잡으면 팀이 안 떠요.

# 버전 체크
claude --version

# 출력 예: Claude Code v2.1.32 이상이면 Agent Teams 문서 기준 충족

.claude/settings.json 같은 프로젝트나 사용자 세팅에 환경변수를 넣어요.

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

그다음 Claude Code를 재시작하고, 자연어로 팀을 만들라고 시키면 돼요.

Create an agent team with 3 teammates.
One reviews API changes, one reviews database changes, one reviews tests.
Require plan approval before edits.

더 깊게 돌릴 생각이면 Claude Code thinking 모드: low/medium/high/xhigh 언제 쓰는지도 같이 봐두세요. Claude Code Agent Teams는 생각 깊이와 토큰 소비가 바로 비용으로 이어지거든요.

Claude Code 병렬 리팩터링은 언제 켜야 할까

Claude Code 병렬 리팩터링은 “같은 코드베이스 안에 독립 작업이 여러 개 있을 때”만 켜는 게 좋아요. 팀원 3명이 각자 다른 파일 범위를 맡을 수 있으면 이득이고, 한 파일을 같이 고치면 바로 충돌 쪽으로 가요.

이걸 매번 켜야 할까요? 아니요. 솔직히 대부분은 Subagent나 단일 Claude Code 세션이 더 싸고 조용해요.

상황	추천	이유
PR 하나를 보안·성능·테스트로 나눠 리뷰	Agent Teams	관점 분리가 쉬움
모듈 A, B, C가 서로 독립	Agent Teams + Worktree	파일 충돌을 줄일 수 있음
같은 핵심 파일 하나를 계속 수정	단일 세션	충돌 위험이 큼
짧은 문서 조사 3개	Subagent	결과만 받으면 충분
실패 원인이 여러 후보로 갈림	Agent Teams	경쟁 가설 디버깅에 맞음
배포 로그를 계속 봐야 함	단일 세션 + 모니터링	팀보다 관찰 도구가 먼저

시작 기준은 이렇게 잡으면 판단이 빨라져요.

• 팀원별 파일 소유권이 분리돼요.
• 팀원마다 5~15분 안에 끝낼 태스크가 있어요.
• 팀 전체 작업이 2시간을 넘기지 않아요.
• 리더가 직접 코딩하지 않고 조율만 하게 만들 수 있어요.
• 실패했을 때 버릴 수 있는 브랜치가 있어요.
• 토큰 비용이 커져도 이번 작업에서 회수돼요.

Plan Mode부터 쓰세요. 팀을 만들기 전에 “누가 어떤 파일을 만질지”를 문서로 고정해야 해요. 대형 리팩터링을 클라우드에서 길게 돌리는 쪽은 Claude Code Ultraplan으로 클라우드에서 대규모 리팩터링 돌리기와 비교해보는 게 낫고요.

3명 팀과 4명 팀의 체감 차이는 의외로 커요. 3명까지는 리더가 머릿속에 팀원 상태를 다 들고 있는데, 4명을 넘기면 메시지 큐가 늘어나면서 리더가 조율 대신 따라가기에 바빠지더라고요. 처음엔 3명으로 시작해서 같은 파이프라인을 두세 번 돌려보고 익숙해지면 4명을 시도해 보세요.

Agent Teams Git Worktree로 팀원 격리하기

Claude Code Agent Teams Git Worktree 패턴은 팀원마다 별도 작업 폴더와 브랜치를 주는 방식이에요. 같은 저장소 기록을 공유하지만 파일 변경은 서로 다른 디렉터리에서 일어나서, 동시에 편집해도 메인 작업 폴더가 덜 지저분해져요.

같은 파일을 네 명이 동시에 고치면 어떻게 될까요? 거의 늘 사람이 뒤에서 머지를 수습해요. 그래서 팀을 띄우기 전에 브랜치와 파일 범위를 나눠야 해요.

공식 Claude Code 문서에는 claude --worktree 방식이 있어요. 직접 Git 명령으로 잡아도 돼요. 아래는 독자가 자기 프로젝트에 맞게 바꿀 수 있는 예시예요.

# 팀원별 브랜치와 작업 폴더 만들기
git worktree add ../project-api -b refactor/api-layer
git worktree add ../project-db -b refactor/db-layer
git worktree add ../project-tests -b refactor/test-layer
git worktree add ../project-ui -b refactor/ui-layer

# 현재 Worktree 목록 보기
git worktree list
# 출력 예: ../project-api, ../project-db, ../project-tests, ../project-ui

각 Worktree에서 따로 Claude Code를 열고, 팀 리더에게 이렇게 말해요.

Create an agent team for a staged refactor.

Use these ownership rules:
- api teammate: only edit routes/ and services/
- db teammate: only edit migrations/ and repositories/
- test teammate: only edit tests/
- ui teammate: only edit components/

Require plan approval before any teammate edits files.
If a teammate needs another folder, ask the lead first.

환경 파일도 놓치기 쉬워요. Worktree는 새 체크아웃이라 .env 같은 gitignored 파일이 없을 수 있거든요. 필요한 값은 .worktreeinclude 같은 방식으로 복사 규칙을 잡거나, 각 Worktree에서 따로 세팅하세요.

.env.local
config/local.example.json

tmux를 쓸 수 있으면 분할 패널로 팀원마다 세션을 띄워두는 게 편해요. 어떤 팀원이 멈췄는지 한눈에 보이고, 토큰을 쓸데없이 태우는 팀원을 바로 죽일 수 있거든요. tmux 없이도 동작하지만, 출력이 한 스레드에 섞이면 디버깅이 어려워져요.

단일 세션을 보면서 로그를 추적하는 쪽은 Claude Code Monitor 도구로 배포 로그 실시간 추적하기가 더 맞아요. Agent Teams는 모니터링 도구가 아니라 병렬 작업 조율 도구예요.

4명 팀으로 모놀리식 모듈 리팩터링 돌리기

4명 팀은 “리더 1명 + 독립 팀원 4명”이 아니라, 보통 리더가 조율하고 팀원 3~4명이 움직이는 그림이 좋아요. 공식 문서도 대부분 작업에 3~5명부터 시작하라고 해요.

네 명을 띄웠는데 왜 더 느릴까요? 태스크가 작지 않거나, 팀원이 서로 같은 맥락을 다시 읽거나, 리더가 조율 대신 직접 코딩에 뛰어들면 그렇게 돼요.

가상의 Express에서 Fastify로 옮기는 작업이라면 이렇게 쪼개요. Express는 Node.js 웹 서버 프레임워크고, Fastify는 더 가벼운 웹 서버 프레임워크예요.

팀원	소유 범위	태스크 예시	성공 기준
API	routes/, controllers/	라우터 호출 방식 교체	기존 API 응답 스냅샷 통과
Plugin	plugins/, middleware/	인증·로깅 미들웨어 이식	인증 테스트 통과
Test	tests/	실패 테스트 갱신	핵심 테스트 초록
Reviewer	읽기 중심	변경 범위와 회귀 위험 체크	위험 목록 제출

실제 프롬프트는 짧고 구체적으로 가요.

Create an agent team for a small refactor spike.

Goal:
Move one module from Express-style handlers to Fastify-style handlers.

Rules:
- No teammate may edit files outside their ownership.
- Each teammate must write a short plan first.
- The reviewer teammate must not edit code.
- Stop after one module. Do not expand scope.

Deliverable:
A summary with changed files, tests run, and unresolved risks.

실행 뒤에는 바로 검증으로 가요.

# 의존성 설치
npm install

# 테스트 돌리기
npm test

# 타입 체크
npm run typecheck

# 출력 예: tests 24 passed, 0 failed / typecheck OK

위 표와 프롬프트는 독자가 자기 모듈 리팩터링에 그대로 옮겨 쓸 수 있게 짠 샘플이에요. 실제 마이그레이션 벤치마크가 아니라, 팀원 소유권을 어떻게 끊어야 충돌이 안 나는지를 보여주려고 골랐어요.

PR 리뷰로 확장할 때는 Claude Opus 4.7 vs Sonnet 4.6: 코드 작업별 선택과 비용 비교를 같이 열어두면 좋아요. 리뷰 팀원 전체에 Opus를 쓰는 순간 비용이 훅 올라가거든요.

Claude Opus 1M 컨텍스트와 비용 장애 패턴

Claude Opus 1M 컨텍스트는 Claude Code Agent Teams 리더가 큰 코드베이스 흐름을 잡을 때 매력적이에요. 컨텍스트는 모델이 한 번에 참고할 수 있는 입력 범위고, Opus 4.7은 공식 모델 페이지 기준 1M 컨텍스트 창을 내세워요. 다만 1M까지 채우면 LLM 응답 정확도가 떨어진다는 보고가 많아서, 리더라도 200~300K 안에서 끊어가는 게 현실적이에요.

구독 플랜과 API 단가 비교

Pro 플랜($20)으로 진짜 버틸까요? 짧은 실험은 가능해도, 팀원 수를 늘린 리팩터링을 계속 돌리는 용도로는 빡빡할걸요. 2026-05-10 공식 가격 기준 Claude Pro는 월 $20, Max 5x는 월 $100, Max 20x는 월 $200이고, API(프로그램에서 모델을 부르는 방식) 단가는 Opus 4.7 입력 $5/MTok·출력 $25/MTok, Sonnet 4.6 입력 $3/MTok·출력 $15/MTok이에요. MTok은 백만 토큰을 뜻해요.

구성	입력 가정	출력 가정	대략 계산	메모
Sonnet 팀원 3명	150K	45K	입력 $0.45 + 출력 $0.675	API 단가 기준 단발 예시
Opus 리더 1명 + Sonnet 팀원 3명	리더 80K, 팀원 150K	리더 20K, 팀원 45K	Opus $0.90 + Sonnet $1.125	장시간이면 누적 큼
Opus 4명	200K	60K	입력 $1.00 + 출력 $1.50	작은 PR 한 번 예시

표는 2026-05-10 공식 API 단가에서 단순 곱셈으로 뽑은 1회성 추정이에요. 구독 플랜은 토큰을 사용량 한도로 환산하니까, 실제 한 달 비용은 이 표보다 “팀을 몇 번 띄우느냐 × 평균 작업 길이”에 더 좌우돼요. GeekNews에는 Claude Code Agent Teams를 Max 5x로 돌리다가 짧은 시간 안에 일일 한도가 바닥난 사례도 올라와 있어요.

알려진 장애와 회피책

장애 패턴도 같이 봐야 해요. Claude Code Agent Teams는 Research Preview 단계라 GitHub에 미해결 이슈가 쌓여 있고, 작업 흐름이 길어지면 그대로 부딪혀요.

문제	2026-05-10 상태	회피 방법
GitHub Issue #23620: 리더 컨텍스트 압축 뒤 팀 상태를 잃는 버그 리포트	Open	2시간 넘기지 말고 단계별 종료
GitHub Issue #49786: 팀원 컨텍스트 압축 부재 요청	Open	팀원 태스크를 5~15분 단위로 쪼개기
GitHub Issue #26107: 기존 .claude/agents/ 정의 재사용 요청	Open	spawn 프롬프트에 기존 subagent 정의명을 직접 명시
GitHub Issue #42848: Windows 경로 문제 리포트	Open, stale	Windows는 CLI 경로와 tmux/iTerm2 대체 흐름 재검증

긴 작업은 한 번에 밀지 마세요. “계획 → 팀 생성 → 짧은 실행 → 테스트 → 정리 → 다음 팀”으로 끊는 게 낫더라고요. Anthropic의 C 컴파일러 실험도 16 에이전트, 입력 약 2B 토큰·출력 약 140M 토큰, 약 $20K API 비용이 붙은 연구 사례예요. 개인 프로젝트 운영 패턴으로 그대로 가져오면 안 돼요.

자주 묻는 질문

Q1: Claude Code Agent Teams와 Subagent의 차이는 뭔가요?

A: Subagent는 메인 세션이 부르는 보조 작업자에 가까워요. Claude Code Agent Teams는 별도 Claude Code 세션들이 공유 태스크 목록과 메시지로 서로 조율해요. 팀원끼리 직접 말해야 하는 작업이면 Claude Code Agent Teams, 결과만 받으면 되는 작업이면 Subagent가 더 싸요.

Q2: Pro 플랜($20)으로도 Claude Code Agent Teams를 쓸 수 있나요?

A: Claude Pro는 2026-05-10 공식 가격표 기준 월 $20이고 Claude Code를 포함해요. Claude Code Agent Teams 자체는 막아두지 않지만, 팀원마다 컨텍스트와 토큰을 따로 쓰니까 Pro 사용량 한도를 빠르게 소진해요. 짧은 실험 정도가 현실적이고, 긴 리팩터링은 Max 5x 이상에서 도전하는 편이 무난해요.

Q3: 팀원이 같은 파일을 동시에 고쳐서 충돌이 나면요?

A: 먼저 멈추고 파일 소유권을 다시 나눠요. 그다음 Agent Teams Git Worktree 패턴으로 팀원별 브랜치를 분리하세요. 같은 파일을 여러 팀원에게 맡기는 건 병렬화가 아니라 충돌 예약이에요.

Q4: 컨텍스트 압축 뒤 팀이 사라지는 문제는 해결됐나요?

A: GitHub Issue #23620은 2026-05-10에 Open으로 봤어요. 긴 세션을 한 번에 끌고 가지 말고, 작업을 짧게 나눈 뒤 팀을 정리하고 새 팀으로 이어가는 게 현실적인 회피책이에요.

Q5: 1M 컨텍스트 Opus 4.7을 팀원 전체에 쓰면 좋나요?

A: 보통은 과해요. 리더만 Opus 4.7로 큰 그림을 잡고, 팀원은 Sonnet 4.6부터 섞어보는 편이 나아요. 실제 비용은 입력보다 출력 토큰에서 더 아프게 느껴질 수 있어요.

다음 단계

작은 모듈 하나만 골라서 Worktree 3개로 먼저 돌려보세요. 결과가 괜찮으면 다음엔 PR 리뷰를 보안·성능·테스트 팀원으로 나눠서 붙이면 돼요.