🤖 Claude Code Agent Teams : 팀? 서브에이전트? 스킬? (++ 팀 시각화)

안녕하세요!! 트윅히입니다.

에이전트들끼리 대화를 한다고 하는 데 ㅋㅋㅋ

잘 활용하는 법을 끼려왔습니다.!!

 

요즘 매일매일 새로운 용어와 사용법이 나와 다들 따라가기도 벅차시죠..?

이젠... 에이전트 팀의 시대입니다 ㅋㅋㅋㅋ ㅠㅠㅠ 휴...

 

오늘 이 글을 통해 더 똑똑하게 뽕뽑아보자구요!!

 

 

"혼자 일하는 AI가 아니라, 팀으로 일하는 AI" — 이게 Agent Teams의 핵심

 

---

1. Agent Teams가 뭔가요?

Claude Code를 쓰다 보면 어느 순간 한계를 느끼는 순간이 와요. 보안 감사, 성능 리뷰, 테스트 커버리지 분석을 동시에 해야 하는데 세션 하나로는 역부족이랄까요.

Agent Teams는 바로 그 문제를 해결하기 위해 나온 기능이에요.

여러 개의 독립적인 Claude Code 인스턴스가 하나의 프로젝트 안에서 실제로 협업하고,

컨텍스트를 공유하고, 서로 메시지를 주고받는 완전히 새로운 실행 모델이에요.

싱글 스레드 프로그래밍에서 멀티 스레드 프로그래밍으로 넘어가는 느낌이랄까요? 그 점프가 Agent Teams예요 🚀

💡 2026년 2월, Claude Opus 4.6 릴리즈와 함께 정식으로 공개된 실험적 기능이에요. 아직 기본값은 비활성화 상태라 직접 켜줘야 해요.

---

2. 서브 에이전트 vs Agent Teams: 뭐가 다른가요?

가장 핵심적인 차이는 "에이전트끼리 대화할 수 있냐 없냐" 예요.

구분 서브 에이전트 (Subagents) Agent Teams

실행 방식	메인 에이전트 안에서 실행	독립적인 Claude Code 인스턴스
커뮤니케이션	메인 에이전트에게만 결과 보고	팀원끼리 직접 메시지 교환 가능
공유 작업 목록	❌	✅
실시간 조율	❌	✅
개별 팀원에 직접 접근	❌	✅
토큰 비용	상대적으로 저렴	팀원 수에 비례해서 증가

한 마디로 정리하면:

• 서브 에이전트 = 각자 심부름 다녀오는 심부름꾼 🏃
• Agent Teams = 서로 소통하며 협업하는 실제 팀 🤝

공식 문서에서도 이렇게 구분하고 있어요:

"Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own."

---

@claude

 

 

3. 내부적으로 어떻게 동작하나요?

Agent Teams는 내부적으로 다섯 개의 새로운 도구를 사용해요. 이걸 이해하면 왜 이렇게 동작하는지가 훨씬 잘 보여요.

🔧 핵심 내부 도구들

TeamCreate 팀 스캐폴딩을 설정해요. 실행되면 .claude/teams/ 폴더 구조가 생성돼요.

~/.claude/teams/my-team/config.json
~/.claude/tasks/my-team/

TaskCreate 상태 추적, 종속성, 소유권 정보가 담긴 JSON 파일로 작업을 등록해요. 예전 Task 도구와는 다른 버전이에요.

Task (업그레이드 버전) 에이전트를 실행하는데, 이제 name과 team_name 파라미터를 지원해서 팀 모드를 활성화할 수 있어요.

taskUpdate 에이전트들이 작업을 할당받고, 상태를 업데이트하고, 완료 처리할 때 사용해요.

sendMessage 진짜 핵심 기능이에요. 에이전트 대 에이전트의 직접 메시지와 브로드캐스트를 모두 지원해요. 메시지는 .claude/teams/<team_id>/inbox/에 기록되고, 각 에이전트의 대화 기록에 <teammate-message teammate_id="..."> 형태로 삽입돼요.

팀 리더는 shutdown_request를 보내고, 팀원들은 shutdown_response로 확인하면서 세션이 깔끔하게 종료돼요.

---

4. 설정 방법 (Step by Step)

Step 1️⃣ Claude Code 최신 버전으로 업데이트

npm update -g @anthropic-ai/claude-code

버전 확인:

claude --version

Step 2️⃣ 실험적 플래그 활성화

설정 파일을 열어요:

code ~/.claude/settings.json

아래 내용을 추가해요: 1이라는 건 팀 한 개라는 의미가 아니라 팀 설정을 키겠다 = true라는 의미에요! 

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

💡 셸 환경 변수로도 설정할 수 있어요. .bashrc 또는 .zshrc에 추가하면 세션 간에도 유지돼요:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

파일 저장 후 터미널을 재시작해요.

Step 3️⃣ 권한 설정 (중요! ⚠️)

팀원들이 파일을 읽고 명령어를 실행할 수 있도록 권한을 설정해줘야 해요.

권한이 너무 제한적이면 팀원들(에이전트)이 작업 도중 멈춰서 승인을 기다리게 돼요.

settings.json에 권한 설정을 추가해요:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Bash(git *)",
      "Bash(npm *)"
    ]
  }
}

⚠️ 보안 주의: 실제 프로젝트에서는 필요한 권한만 최소한으로 설정하고, .env, 시크릿 파일, SSH 키 등은 반드시 deny 목록에 넣어두세요.

Step 4️⃣ 새 Claude Code 세션 시작

claude

이제 Agent Teams를 사용할 준비가 됐어요! 🎉

---

5. 실제 사용 예시 프롬프트 모음

Agent Teams는 프롬프트에서 팀을 만들어달라고 명시적으로 요청하면 활성화돼요. 몇 가지 실제로 잘 동작하는 프롬프트 패턴을 소개할게요.

📌 예시 1: 다각도 설계 탐색

CLI 도구를 설계하고 있어요. 에이전트 팀을 만들어서 다양한 관점으로 탐구해주세요:
- UX 담당 팀원 한 명
- 기술 아키텍처 담당 팀원 한 명
- 악마의 변호인 역할을 하는 팀원 한 명
각 팀원이 자신의 관점에서 분석한 후, 서로 의견을 교환하고 findings.md에 정리해줘요.

이 예시는 세 가지 역할이 서로 독립적으로 탐구할 수 있어서 Agent Teams의 강점이 잘 나와요.

📌 예시 2: 경쟁 가설로 디버깅

사용자들이 앱이 메시지 하나를 보낸 후 연결이 끊긴다고 해요.
에이전트 팀을 만들어서 각자 다른 가설을 조사하게 해줘요:
- 팀원 A: 네트워크 타임아웃 이슈 조사
- 팀원 B: 메모리 누수 가능성 분석
- 팀원 C: 세션 관리 코드 점검
서로 대화하면서 각자의 이론을 반박하고, 합의된 내용을 debug-report.md에 업데이트해줘요.

📌 예시 3: 멀티 레이어 피처 개발

새로운 대시보드 기능을 만드는 에이전트 팀을 구성해줘요:
- 팀원 A: API 레이어 담당 (src/api/)
- 팀원 B: 프론트엔드 컴포넌트 담당 (src/components/)
- 팀원 C: 테스트 스위트 담당 (tests/)
각 팀원이 공유 작업 목록을 통해 진행 상황을 조율하고,
API 타입 정의가 완료되면 팀원 B에게 직접 메시지를 보내도록 해줘요.

📌 예시 4: QA 스웜

내 블로그가 http://localhost:4321/ 에서 실행 중이에요.
에이전트 팀으로 QA를 진행해줘요:
- 팀원 A: 페이지 로딩 속도 및 성능 점검
- 팀원 B: 링크 및 네비게이션 오류 확인
- 팀원 C: 모바일 반응형 레이아웃 체크
발견한 이슈는 qa-report.md에 정리해줘요.

---

6. 시각화 환경 세팅 (tmux / iTerm2)

Agent Teams는 모든 에이전트가 병렬로 작업하는 걸 실시간으로 볼 수 있을 때 진가를 발휘해요.

🖥️ 디스플레이 모드 종류

모드 설명 요구사항

in-process (기본값)	터미널 하나에서 Shift+↑/↓로 팀원 전환	없음
split panes	각 팀원이 별도 터미널 창 차지	tmux 또는 iTerm2

Claude Code가 자동으로 환경을 감지해요. 이미 tmux 세션 안에 있으면 split panes를, 아니면 in-process 모드로 실행돼요.

🔀 tmux 사용하기

# tmux 설치 (macOS)
brew install tmux

# tmux 세션 시작 후 Claude Code 실행
tmux new-session -s claude
claude

🍎 iTerm2 사용하기 (macOS)

1. iTerm2 설치
2. Settings → General → Magic 으로 이동
3. Python API 활성화
4. iTerm2 재시작
5. Claude Code 실행:

claude --teammate-mode tmux

이렇게 하면 팀 리더를 위한 창 하나와 각 팀원을 위한 별도 창이 열려요. 어떤 창이든 클릭해서 에이전트가 뭘 하는지 실시간으로 볼 수 있고, 개별 에이전트에게 직접 메시지를 보낼 수도 있어요.

⌨️ 유용한 단축키 (in-process 모드)

단축키 기능

Shift+↑ / Shift+↓	팀원 간 전환
Enter	선택한 팀원 세션 보기
Escape	현재 팀원 작업 중단
Shift+Tab	Delegate 모드 토글

---

7. 알아두면 좋은 팁들

💡 Delegate 모드 적극 활용하기

Shift+Tab으로 토글할 수 있는 Delegate 모드는 생각보다 중요해요.

이 모드를 켜면 팀 리더가 코드 작성, 테스트 실행, 구현 작업을 직접 하지 않고 조율만 하게 돼요. 리더가 혼자 다 해버리는 걸 막아주는 거예요. 팀원들이 작업을 제대로 받아서 실행하게 하려면 이 모드를 켜두는 게 좋아요.

💡 팀원에게 충분한 컨텍스트 주기

팀원들은 리더의 대화 기록을 상속받지 않아요. 그래서 스폰 프롬프트에 작업 관련 정보를 최대한 구체적으로 넣어줘야 해요.

# 별로 안 좋은 예
"보안 팀원을 생성해서 auth 모듈 리뷰해줘"

# 훨씬 나은 예
"보안 리뷰 팀원을 생성해줘. 역할: src/auth/ 디렉토리의 보안 취약점 검토.
집중 영역: JWT 토큰 처리, 세션 관리, 입력 검증.
앱은 httpOnly 쿠키에 저장된 JWT 토큰을 사용해요.
발견한 이슈는 severity 등급과 함께 보고해줘."

💡 팀원 수는 3~5명이 적당해요

너무 많은 팀원을 생성하면 조율 오버헤드와 토큰 비용이 급격히 증가해요. 공식 문서에서도 3~5명을 권장하고 있어요.

💡 같은 파일 동시 편집 피하기

두 팀원이 같은 파일을 동시에 수정하면 충돌이 발생해요. 병합 메커니즘이 없으니 작업을 나눌 때 파일 단위로 명확하게 영역을 구분해줘요.

💡 처음엔 읽기 전용 작업부터 시작

코드 리뷰, 버그 가설 조사처럼 파일을 읽기만 하는 작업으로 먼저 Agent Teams를 경험해보세요. 병렬 탐색의 가치를 확인한 후에 실제 코드 변경 작업으로 넘어가는 게 안전해요.

---

8. 현재 알려진 제한사항

실험적 기능인 만큼 몇 가지 제한사항이 있어요. 미리 알아두면 당황하지 않을 수 있어요.

제한사항 내용

세션 복구 불가	/resume, /rewind 명령어로 진행 중인 팀원 복구 안 됨
작업 상태 지연	팀원이 완료 표시를 놓치는 경우 있음 (수동으로 업데이트 가능)
종료 속도	팀원이 현재 요청 완료 후 종료돼서 시간이 걸릴 수 있음
팀은 하나만	세션당 팀 하나만 운영 가능
중첩 팀 불가	팀원이 또 다른 팀을 만들 수 없음
토큰 비용	팀원 수에 비례해서 토큰 사용량 증가

---

9. 어떤 상황에서 쓰면 좋을까요?

✅ Agent Teams가 빛나는 상황

• 병렬 탐색이 진짜 가치 있을 때: 여러 가설을 동시에 검증해야 할 때
• 여러 모듈 동시 개발: 프론트엔드, 백엔드, 테스트를 각각 다른 팀원이 담당
• 경쟁 가설 디버깅: 서로 다른 이론을 팀원들이 논쟁하며 수렴
• 다각도 코드 리뷰: 보안, 성능, 가독성을 각각 전문 팀원이 리뷰
• QA 스웜: 여러 관점에서 동시에 테스트

❌ 서브 에이전트나 단일 세션이 더 나은 상황

• 순차적 작업: 앞 작업이 끝나야 다음 작업이 가능한 경우
• 같은 파일 반복 수정: 충돌 위험이 있는 경우
• 의존성이 많은 작업: 팀원 간 조율 오버헤드가 오히려 걸림돌이 되는 경우
• 간단하고 빠른 작업: 오버헤드 대비 효용이 없는 경우

---

 

정리 : 스킬  VS 서브 에이전트 VS 팀  👀

3가지가 헷갈리실 수 있을 거라고 생각이 들어요

저도 처음엔 헷갈렸습니다..!!

되게 두루뭉술한 글들이 많아 확실히 정리해봤습니다.

스킬

/skills 폴더에는 **스킬(Skill)**을 정리한다. 스킬은 하나의 기능을 수행하는 “도구”에 가깝다. 예를 들어 테스트 생성, SQL 분석, 마이그레이션 생성처럼 특정 작업을 수행하는 재사용 가능한 단위다. 스킬 자체는 판단하지 않고, 요청이 들어오면 정해진 방식대로 실행하는 기능 모음이라고 보면 된다.

서브에이전트

/agents 폴더에는 **서브 에이전트(Sub-Agent)**를 정의한다. 서브 에이전트는 “역할을 가진 AI”다. 예를 들어 Test Agent, Refactor Agent, Review Agent처럼 책임이 분리되어 있다. 이 에이전트는 자신의 역할과 규칙을 가지고 있고, 필요할 때 /skills에 있는 스킬을 호출해서 작업을 수행한다. 즉, 스킬이 도구라면 서브 에이전트는 그 도구를 사용하는 담당자다.

팀

그리고 **팀(Team)**은 여러 서브 에이전트를 묶어 협업하게 만드는 상위 개념이다.

팀 설정은 위와 같이 환경변수로 설정해줘야 팀이 세팅됨!!

설계 담당, 리팩토링 담당, 테스트 담당처럼 서로 다른 역할의 에이전트 인스턴스들이 하나의 목표를 위해 함께 일하는 구조다.

정리하면, 스킬은 기능 단위, 서브 에이전트는 책임 단위, 팀은 협업 구조라고 이해하면 가장 명확하다.

 

마무리 🎬

Claude Code Agent Teams는 아직 실험적 기능이지만, AI 지원 개발의 패러다임이 바뀌고 있다는 걸 느끼게 해줘요.

진짜 이젠 여러명을 부리는 느낌이 들기 시작합니다..!

 

 

 

일은 인공지능이 하고 밥은 내가 먹으면 좋겠습니다..

너희들끼리 알잘딱깔센 해줘라ㅠㅠㅠ

속으론 이렇게 생각하고 있겠죠,..? ㅋㅋㅋ 미..미안 ㅠㅠㅠ

 

---

📚 참고 자료

• Claude Code 공식 문서 - Agent Teams
• From Tasks to Swarms - alexop.dev
• Claude Code Agent Teams Guide - AddyOsmani