시리즈: 클로드 코드 Team 기능 완전 가이드 (총 9편) | 4편

설정부터 실행까지, Team 기능 실전 가이드

클로드 코드 Team 기능을 실제로 켜고 돌려보려면 환경변수 하나, 설정 파일 몇 줄, 표시 모드 선택이 전부예요. 복잡할 것 같지만 의외로 간단하거든요. 이 글에서 활성화부터 권한 상속, IDE 연동까지 한 번에 정리해 드릴게요.

Summary

Team 기능은 실험 기능이라 환경변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정이 필수예요
표시 모드는 in-process, tmux, auto 세 가지이고, 상황에 따라 골라 쓰면 돼요
팀원은 리더의 권한 설정을 그대로 상속받기 때문에 권한 관리를 미리 챙겨야 해요
VS Code/JetBrains 등 IDE와 조합하면 더 편하게 팀을 운영할 수 있어요

이 글의 대상

Team 기능을 처음 써보려는데 어디서부터 시작해야 할지 모르는 분
settings.json이나 CLI 옵션을 직접 만져본 적 있는, 어느 정도 경험이 있는 분
IDE 환경에서 Team 기능을 연동해 쓰고 싶은 개발자

1. Team 기능 활성화하기

아직 실험 기능이라 별도로 켜줘야 해요. 방법은 두 가지예요.

방법 A: 터미널에서 환경변수 직접 설정

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

세션마다 매번 입력하기 귀찮으니까 .zshrc나 .bashrc에 넣어두는 게 편해요.

방법 B: settings.json에 영구 등록

~/.claude/settings.json 파일을 열어서 아래처럼 추가하면 돼요.

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

이렇게 해두면 CLI를 실행할 때마다 자동으로 Team 기능이 활성화돼요. 개인적으로는 이 방법을 추천해요 -- 한 번 세팅하면 잊어버려도 되거든요.

2. 표시 모드 선택: in-process vs tmux vs auto

팀원 에이전트의 출력을 어떻게 보여줄지 정하는 옵션이에요. CLI 실행 시 --teammate-mode 플래그로 지정하거나, settings.json의 teammateMode 필드로도 설정할 수 있어요.

모드	동작 방식	장점	단점
`in-process`	리더 프로세스 안에서 팀원 실행	별도 설치 불필요, 간단	출력이 섞일 수 있음
`tmux`	tmux 세션으로 팀원별 분리	각 팀원 출력을 독립 패널로 확인	tmux 설치 필요, IDE 통합 터미널에서 제약
`auto`	환경에 맞게 자동 선택	신경 쓸 게 적음	어떤 모드로 뜰지 예측이 어려울 수 있음

CLI에서 쓸 때는 이렇게 지정해요.

claude --teammate-mode tmux

settings.json에 넣으려면 이렇게요.

{
  "teammateMode": "in-process"
}

처음 시작한다면 in-process가 가장 무난해요. tmux에 익숙하고 여러 팀원의 작업을 동시에 모니터링하고 싶다면 tmux로 가면 되고요.

3. 권한 상속 구조 이해하기

여기가 꼭 알아둬야 할 부분이에요. 팀원은 리더의 permission 설정을 그대로 상속받아요.

리더가 --dangerously-skip-permissions 플래그로 실행했다면? 팀원도 마찬가지로 모든 권한이 열려요. 편하긴 하지만 위험할 수 있으니까, 프로덕션 환경에서는 절대 권장하지 않아요.

반대로 리더가 세밀하게 권한을 제한해뒀다면, 팀원도 동일한 제한 아래서 동작해요. 그래서 팀을 구성하기 전에 리더의 권한 설정부터 점검하는 게 중요해요.

리더 권한 설정 → 팀원 A (동일 권한)
                → 팀원 B (동일 권한)
                → 팀원 C (동일 권한)

이 구조를 모르면 "왜 팀원이 파일을 못 읽지?" 같은 상황에서 헤매게 돼요.

4. 로컬 저장 경로와 구조

Team 기능은 로컬에 두 가지 정보를 저장해요.

경로	역할
`~/.claude/teams/{team-name}/config.json`	팀 구성 정보 (역할, 팀원 수 등)
`~/.claude/tasks/{team-name}/`	작업 목록과 진행 상태

팀을 여러 개 만들어도 team-name으로 구분되니까 서로 충돌하지 않아요. 설정을 백업하거나 다른 머신에 복사할 때 이 경로를 알아두면 편해요.

5. IDE 연동 팁

Team 기능의 코어는 CLI이지만, IDE와 조합하면 훨씬 생산적이에요.

VS Code

통합 터미널에서 CLI 기반으로 팀 리더를 실행할 수 있어요
VS Code 확장 프로그램이 컨텍스트 전달, diff 뷰, PR UI 등을 제공해요
주의: VS Code 통합 터미널에서 tmux 기반 split-pane이 제대로 안 될 수 있어요. in-process 모드를 쓰거나 외부 터미널에서 실행하는 걸 추천해요

JetBrains (IntelliJ, PyCharm 등)

마찬가지로 CLI 기반 팀 리드 + JetBrains 플러그인 조합으로 사용해요
diff 확인이나 PR 리뷰 등은 JetBrains 내장 기능과 자연스럽게 붙어요

핵심은 CLI가 팀을 이끌고, IDE는 결과를 시각화하고 관리하는 역할이라는 거예요. 둘을 분리해서 생각하면 연동이 훨씬 수월해요.

6. 상황별 추천 세팅

어떤 세팅으로 시작할지 고민된다면 이 표를 참고하세요.

상황	추천 모드	이유
개인 개발 / 빠른 PoC	`in-process`	설정 최소, 바로 시작 가능
장시간 자동 운영	외부 터미널 + `tmux`	세션 유지, 모니터링 용이
VS Code 통합 터미널	`in-process`	tmux 호환 이슈 회피
멀티 팀원 동시 모니터링	`tmux`	각 팀원 패널 분리 확인

처음이라면 in-process로 시작해서 감을 잡고, 팀원이 많아지거나 장시간 돌려야 할 때 tmux로 전환하는 게 가장 자연스러운 흐름이에요.

핵심 정리

1. 활성화: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수 또는 settings.json에 등록
2. 표시 모드: in-process(간단), tmux(분리 모니터링), auto(자동) 중 상황에 맞게 선택
3. 권한: 팀원은 리더의 권한을 그대로 상속 → 리더 권한 설정이 곧 팀 전체 권한
4. 저장 경로: ~/.claude/teams/와 ~/.claude/tasks/에 팀 구성과 작업 정보 저장
5. IDE 연동: CLI가 팀 리더 역할, IDE는 시각화/관리 역할로 분리해서 활용

FAQ

Q. 환경변수를 설정했는데 Team 기능이 안 보여요. 왜 그런 거예요?

A. 환경변수 이름에 오타가 없는지 먼저 확인해 보세요. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS이고, 값은 반드시 1이어야 해요. settings.json에 넣었다면 JSON 문법 오류(쉼표, 따옴표 등)도 점검해 보세요.

Q. in-process와 tmux 중 뭘 골라야 할지 모르겠어요.

A. 처음 써보는 거라면 in-process로 시작하세요. 별도 설치도 필요 없고, 바로 동작하거든요. 팀원이 3명 이상이 되거나 작업이 오래 걸려서 각자의 진행 상황을 따로 보고 싶을 때 tmux로 옮기면 돼요.

Q. 팀원 권한을 리더와 다르게 설정할 수 있어요?

A. 현재는 불가능해요. 팀원은 리더의 권한 설정을 그대로 상속받는 구조예요. 그래서 팀을 만들기 전에 리더의 권한부터 적절히 세팅해두는 게 중요해요.

Q. `--dangerously-skip-permissions`로 실행하면 팀원도 전부 열려요?

A. 맞아요. 리더가 이 플래그를 쓰면 팀원 전체가 동일하게 모든 권한이 열려요. 로컬 테스트에서는 편하지만, 프로덕션이나 민감한 코드를 다룰 때는 절대 쓰지 마세요.

Q. VS Code 통합 터미널에서 tmux 모드가 제대로 안 돼요.

A. VS Code 통합 터미널은 tmux split-pane을 완전히 지원하지 않는 경우가 있어요. 두 가지 해결책이 있어요: in-process 모드로 바꾸거나, 외부 터미널(iTerm2, 기본 터미널 등)에서 실행하세요.

Q. 팀 설정 파일을 다른 컴퓨터로 옮길 수 있어요?

A. 네, ~/.claude/teams/{team-name}/config.json을 복사하면 돼요. 다만 로컬 경로나 환경변수가 다를 수 있으니 옮긴 후에 경로 설정을 한 번 확인해 보세요.

참고 자료 (References)

데이터 출처

출처	설명	링크
Claude Code CLI Reference	CLI 옵션, 플래그 상세	CLI Reference
Agent Teams 공식 문서 (EN)	Team 기능 전체 가이드	Agent Teams (EN)
Agent Teams 공식 문서 (KO)	Team 기능 한국어 가이드	Agent Teams (KO)
VS Code 연동 가이드	VS Code 확장 및 통합	VS Code 가이드
JetBrains 연동 가이드	JetBrains 플러그인 연동	JetBrains 가이드

핵심 인용

"Team 기능은 CLI 중심으로 동작하며, IDE는 이를 보조하는 역할로 조합해 사용한다." -- Agent Teams 공식 문서

다음 편 예고

[5편] 개발 팀 운영 모델 설계

검증 병렬화가 구현 병렬화보다 ROI가 높은 이유
Implementer, Reviewer, QA, Security 역할 분배 방법
파일/모듈 소유권 기반의 태스크 분해로 충돌 제거하기

'AI' 카테고리의 다른 글

클로드 코드 Team 기능 완전 가이드 (총 9편) \| 6편 리서치/기획 팀 운영 모델 설계: 경쟁 가설과 교차 검증으로 결론의 질을 올리는 법 (0)	2026.02.14
클로드 코드 Team 기능 완전 가이드 (총 9편) \| 5편 개발 팀 운영 모델 설계: 검증 병렬화로 진짜 속도를 내는 법 (0)	2026.02.14
클로드 코드 Team 기능 완전 가이드 (총 9편) \| 3편 핵심 구성요소 완벽 해설 — 리더, 팀원, Task list, 메일박스 (0)	2026.02.14
클로드 코드 Team 기능 완전 가이드 (총 9편) \| 2편 서브에이전트 vs Team, 언제 뭘 써야 할까 (0)	2026.02.14
클로드 코드 Team 기능 완전 가이드 (총 9편) \| 1편 Team 기능이란? 단순 병렬이 아닌 협업 런타임의 이해 (0)	2026.02.14

클로드 코드 Team 기능 완전 가이드 (총 9편) | 4편 설정부터 실행까지, Team 기능 실전 가이드

설정부터 실행까지, Team 기능 실전 가이드

Summary

이 글의 대상

목차

1. Team 기능 활성화하기

방법 A: 터미널에서 환경변수 직접 설정

방법 B: settings.json에 영구 등록

2. 표시 모드 선택: in-process vs tmux vs auto

3. 권한 상속 구조 이해하기

4. 로컬 저장 경로와 구조

5. IDE 연동 팁

VS Code

JetBrains (IntelliJ, PyCharm 등)

6. 상황별 추천 세팅

핵심 정리

FAQ

Q. 환경변수를 설정했는데 Team 기능이 안 보여요. 왜 그런 거예요?

Q. in-process와 tmux 중 뭘 골라야 할지 모르겠어요.

Q. 팀원 권한을 리더와 다르게 설정할 수 있어요?

Q. `--dangerously-skip-permissions`로 실행하면 팀원도 전부 열려요?

Q. VS Code 통합 터미널에서 tmux 모드가 제대로 안 돼요.

Q. 팀 설정 파일을 다른 컴퓨터로 옮길 수 있어요?

참고 자료 (References)

데이터 출처

핵심 인용

다음 편 예고

'AI' 카테고리의 다른 글

티스토리툴바

설정부터 실행까지, Team 기능 실전 가이드

Summary

이 글의 대상

목차

1. Team 기능 활성화하기

방법 A: 터미널에서 환경변수 직접 설정

방법 B: settings.json에 영구 등록

2. 표시 모드 선택: in-process vs tmux vs auto

3. 권한 상속 구조 이해하기

4. 로컬 저장 경로와 구조

5. IDE 연동 팁

VS Code

JetBrains (IntelliJ, PyCharm 등)

6. 상황별 추천 세팅

핵심 정리

FAQ

Q. 환경변수를 설정했는데 Team 기능이 안 보여요. 왜 그런 거예요?

Q. in-process와 tmux 중 뭘 골라야 할지 모르겠어요.

Q. 팀원 권한을 리더와 다르게 설정할 수 있어요?

Q. --dangerously-skip-permissions로 실행하면 팀원도 전부 열려요?

Q. VS Code 통합 터미널에서 tmux 모드가 제대로 안 돼요.

Q. 팀 설정 파일을 다른 컴퓨터로 옮길 수 있어요?

참고 자료 (References)

데이터 출처

핵심 인용

다음 편 예고

'AI' 카테고리의 다른 글

티스토리툴바

Q. `--dangerously-skip-permissions`로 실행하면 팀원도 전부 열려요?