Claude Code의 실험 기능인 Agent Teams를 Next.js 프로젝트에서 직접 돌려본 후기입니다. 팀 리드가 태스크를 분배하고, 3명의 팀메이트가 병렬로 코드를 작성하는 과정을 확인했습니다.
1. 왜 해봤나?
Claude Code는 원래 "하나의 AI가 하나의 세션에서 일하는" 구조입니다. 하지만 실제 개발은 그렇지 않습니다. 프론트 따로, 백엔드 따로, 테스트 따로 — 사람이 팀으로 일하듯이 AI도 팀으로 일하면 어떨까요?
Anthropic이 Opus 4.6 출시와 함께 Agent Teams라는 실험 기능을 내놓았습니다. 여러 Claude Code 세션이 팀처럼 협업하는 기능입니다. 한 세션이 리드가 되고, 나머지가 팀메이트로 각자 독립된 컨텍스트에서 작업하면서 서로 메시지를 주고받습니다.
기존 subagent와의 차이점은 구조에 있습니다. subagent는 메인 에이전트에게만 결과를 보고하는 수직 구조입니다. 반면 Agent Teams는 팀메이트끼리 직접 소통합니다. 실제 개발팀이 슬랙으로 대화하면서 일하는 것과 비슷한 방식입니다.
이 기능이 얼마나 실용적인지 궁금해서 직접 Next.js 프로젝트를 하나 만들어서 돌려보았습니다.
2. 데모 프로젝트: AI 북마크 대시보드
테스트용으로 만든 프로젝트는 "AI 북마크 대시보드"입니다.
- URL을 입력하면 도메인 기반으로 자동 태깅 (github.com → "dev", youtube.com → "video")
- 북마크 목록 표시
- 대시보드에서 태그별 통계 차트
이 프로젝트를 선택한 이유는 레이어가 명확히 분리되기 때문입니다.
- UI 레이어 — 랜딩 페이지 + 대시보드
- API 레이어 — CRUD + 자동 태깅 로직
- 테스트 레이어 — 유닛 + 통합 테스트
서로 다른 파일을 건드리기 때문에 팀메이트들이 충돌 없이 병렬로 작업할 수 있습니다.
3. 환경 세팅
3-1. 프로젝트 생성
pnpm create next-app@latest bookmark-dashboard \
--typescript --tailwind --eslint --app --src-dirReact Compiler도 활성화했습니다. Next.js 16, React 19, TypeScript 5.9 — 최신 스택입니다.
3-2. Agent Teams 활성화
실험 기능이라 기본 비활성화 상태입니다. 프로젝트 단위로 켜는 것이 깔끔합니다.
mkdir -p .claude
echo '{"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1"}}' > .claude/settings.json.zshrc에 넣으면 모든 프로젝트에 적용되고, ~/.claude/settings.json에 넣으면 Claude Code 전역 설정이 됩니다. 이번에는 데모 프로젝트에서만 사용할 것이기 때문에 프로젝트 로컬 설정으로 진행했습니다.
3-3. CLAUDE.md 작성
이 부분이 중요합니다. 팀메이트들이 이 파일을 읽고 프로젝트 컨텍스트를 파악합니다. 기술 스택, 디렉토리 구조, 컨벤션을 여기에 적어두면 팀메이트마다 일일이 설명할 필요가 없습니다.
# Bookmark Dashboard
## Tech Stack
- Next.js 16 (App Router)
- React 19 + React Compiler
- TypeScript 5.9 (strict mode)
- Tailwind CSS
- Zustand (client state)
- TanStack Query (server state)
## Conventions
- 컴포넌트는 named export
- API response: { data, error }
- 타입은 @/lib/types에서 import
- 테스트는 __tests__/ 하위에 배치3-4. 공유 타입 먼저 만들기
Agent Teams 실행 전에 반드시 해야 할 것이 있습니다. 팀메이트들이 공유할 타입을 미리 정의해두는 것입니다. 이 작업을 생략하면 각 팀메이트가 제각각 타입을 만들어서 나중에 충돌이 발생합니다.
// src/lib/types.ts
export interface Bookmark {
id: string;
url: string;
title: string;
description: string;
tags: string[];
favicon: string;
createdAt: string;
}
export interface Tag {
id: string;
name: string;
count: number;
}
export interface ApiResponse<T> {
data: T | null;
error: string | null;
}4. tmux 설치 (split-pane 모드 필수)
Agent Teams의 split-pane 모드를 사용하려면 tmux가 필요합니다. 팀메이트별로 별도 터미널 패널이 생기는데, 이를 tmux가 관리합니다.
brew install tmux참고로 iTerm2에서도 Agent Teams 자체는 동작합니다. 하지만 split-pane 없이 in-process 모드로 실행되면 리드 화면 하나에서만 로그가 출력됩니다. 팀메이트들이 동시에 작업하는 과정을 시각적으로 확인하려면 tmux가 필수입니다.
VS Code 통합 터미널, Windows Terminal, Ghostty에서는 split-pane이 지원되지 않습니다.
5. Agent Teams 실행
5-1. tmux 세션 안에서 Claude Code 실행
tmux
cd bookmark-dashboard
claude5-2. 프롬프트 입력
Claude Code 채팅창에 다음을 입력합니다.
Create an agent team in split-pane mode for this bookmark-dashboard project.
Spawn three teammates:
1. "ui-dev": Build the landing page (src/app/page.tsx) with a
bookmark input form (URL 입력 → 자동 태깅) and bookmark list display.
Also build the dashboard page (src/app/dashboard/page.tsx) with
tag statistics using simple bar chart (CSS-only, no chart library).
Use Tailwind CSS. Import types from @/lib/types.
2. "api-dev": Build all API routes:
- src/app/api/bookmarks/route.ts (GET, POST)
- src/app/api/bookmarks/[id]/route.ts (PATCH, DELETE)
- src/app/api/tags/route.ts (GET)
Use in-memory array storage. Implement auto-tagging by domain
(github.com→"dev", youtube.com→"video", etc) and title keywords.
Import types from @/lib/types.
3. "test-dev": Write Vitest unit tests for API route handlers
in src/__tests__/. Start with test scaffolding immediately,
then write integration tests after ui-dev and api-dev report
their completed file paths.
ui-dev and api-dev work in parallel first.
Coordinate through the shared task list.CLAUDE.md는 프로젝트 컨텍스트(이 프로젝트는 이런 구조다)이고, 이 프롬프트는 작업 지시(팀을 구성하고 이렇게 일해라)입니다. 역할이 다릅니다.
6. 실행 과정 관찰
리드가 먼저 움직인다
프롬프트를 입력하면 리드가 먼저 프로젝트 상태를 확인합니다. 기존 파일을 읽고, Zustand store를 만들고, 디렉토리 구조를 세팅한 다음 팀메이트를 spawn합니다.
split-pane으로 팀메이트 등장
리드가 3명의 팀메이트를 spawn하면 tmux 패널이 자동으로 분할됩니다. 왼쪽에 리드, 오른쪽에 팀메이트들이 각각의 패널에서 동시에 작업을 시작합니다.
이 부분이 가장 인상적이었습니다. 리드 패널에는 다음과 같은 테이블이 표시됩니다.
Team: bookmark-team — 3 agents spawned in parallel
| Agent | Task | Status |
|----------|-----------------------------------------------|---------|
| api-dev | Task #1: API routes (bookmarks CRUD, tags) | Running |
| ui-dev | Task #2: Dashboard page (tag stats, CSS chart)| Running |
| test-dev | Task #3: Vitest tests (blocked by Task #1) | Running |팀메이트 간 조율
- api-dev와 ui-dev는 즉시 병렬로 작업을 시작합니다.
- test-dev는 scaffolding을 먼저 만들면서 api-dev 완료를 대기합니다.
- 팀메이트가 파일 시스템 접근 같은 권한이 필요하면 리드에게 승인 요청을 보냅니다. ("Waiting for team lead approval")
권한 승인
팀메이트가 파일을 생성하거나 bash 명령을 실행할 때 리드에게 permission request가 전달됩니다. 리드 패널에서 1 (Yes)을 눌러서 승인하면 됩니다.
주의: tmux에서는 마우스 클릭이 아니라 키보드로 조작합니다. 패널 간 이동은 Ctrl+b → 방향키, 승인은 1 + Enter입니다.
7. 결과물
약 7분 정도 지나면 팀메이트들이 각자의 작업을 완료합니다.
생성된 파일 구조
src/
app/
page.tsx ← ui-dev가 만든 랜딩 페이지
dashboard/
page.tsx ← ui-dev가 만든 대시보드
api/
bookmarks/
route.ts ← api-dev가 만든 CRUD
[id]/
route.ts ← api-dev가 만든 개별 북마크 API
tags/
route.ts ← api-dev가 만든 태그 API
lib/
types.ts ← 미리 만들어둔 공유 타입
store.ts ← 리드가 만든 Zustand store
__tests__/
bookmarks.test.ts ← test-dev가 만든 유닛 테스트실행 확인
pnpm dev
8. 핵심 메커니즘 정리
실제로 사용하면서 파악한 Agent Teams의 내부 동작입니다.
공유 태스크 리스트
리드가 태스크를 만들면 ~/.claude/teams/{팀명}/ 하위에 태스크 파일이 생성됩니다. 팀메이트는 자기가 수행할 수 있는 태스크를 자동으로 claim(자기 할당) 합니다. 파일 락킹으로 race condition을 방지합니다.
메일박스 시스템
각 에이전트별로 메일박스가 있어서 서로 메시지를 주고받습니다. test-dev가 api-dev에게 "어떤 파일을 만들었는지 알려달라"고 요청하고, api-dev가 완료 후 파일 경로를 보내주는 방식입니다.
라이프사이클 관리
작업이 끝나면 리드에서 shutdown + cleanup을 해야 합니다. cleanup은 반드시 리드에서 실행해야 합니다. 팀메이트에서 cleanup을 돌리면 리소스가 꼬일 수 있습니다.
Shut down all teammates and clean up the team.9. 느낀 점
좋았던 것
병렬 작업이 실제로 동작합니다. api-dev가 route를 만드는 동안 ui-dev가 페이지를 만듭니다. 순차적으로 했으면 2배 이상 걸렸을 작업이 동시에 진행됩니다.
CLAUDE.md의 위력을 체감했습니다. 팀메이트별로 일일이 컨텍스트를 설명할 필요가 없습니다. CLAUDE.md에 컨벤션과 구조를 잘 적어두면 모든 팀메이트가 같은 규칙을 따릅니다.
태스크 의존성 관리가 자연스럽습니다. test-dev가 api-dev 완료를 기다렸다가 통합 테스트를 작성하는 흐름이 자동으로 동작합니다.
아쉬운 점
토큰 소비가 큽니다. 팀메이트 하나당 독립 컨텍스트를 사용하기 때문에 3명이면 최소 3배입니다. Claude Max 요금제도 빠르게 한도에 도달할 수 있습니다.
권한 승인이 번거롭습니다. 팀메이트마다 파일 생성할 때 리드에서 승인해줘야 합니다. tmux 패널을 왔다 갔다 하면서 1 + Enter를 반복하게 됩니다.
아직 실험 기능입니다. 세션 재개, 종료 동작에 알려진 제한이 있습니다. 프로덕션 워크플로우로 사용하기에는 이른 단계입니다.
10. 언제 쓰면 좋을까?
| 상황 | 추천 |
|---|---|
| 서로 다른 레이어 동시 개발 (프론트/백/테스트) | ✅ Agent Teams |
| PR 리뷰 (보안/성능/테스트 관점 병렬 검토) | ✅ Agent Teams |
| 디버깅 — 여러 가설 병렬 검증 | ✅ Agent Teams |
| MSA 크로스 서비스 리팩토링 | ✅ Agent Teams |
| 같은 파일 수정 | ❌ 단일 세션 |
| 순차적 작업 (A 끝나야 B 시작) | ❌ 단일 세션 |
| 간단한 버그 수정 | ❌ 단일 세션 |
판단 기준은 간단합니다. *"이 작업을 사람 3명에게 각각 맡기면 서로 안 부딪히고 병렬로 할 수 있는가?"* Yes라면 Agent Teams, No라면 단일 세션입니다.
마무리
Claude Code Agent Teams는 "AI가 팀으로 일한다"는 개념을 실제로 체험할 수 있는 기능입니다. 아직 실험 단계라 거친 부분이 있지만, 병렬 작업이 가능한 프로젝트에서는 확실히 효율적입니다.
특히 MSA 같은 멀티 서비스 프로젝트에서 크로스 서비스 리팩토링이나 새 모듈 추가 같은 작업에 적합할 것으로 보입니다. 토큰 비용과 안정성이 개선되면 실무 워크플로우에도 충분히 도입할 수 있을 것이라 생각합니다.
사용해보고 싶다면 간단한 프로젝트부터 시작하는 것을 추천합니다. PR 리뷰에 3명의 리뷰어를 붙여보는 것도 좋은 시작점입니다.