Claude Code 에이전트 팀이란?

코드 한 묶음을 보안, 성능, 테스트 세 관점에서 동시에 검토하고 싶을 때가 있습니다. 세션 하나에 순서대로 맡기면 앞에서 내린 결론이 뒤의 판단을 끌고 갑니다. 세션 세 개를 직접 띄워 놓고 결과를 손으로 옮기는 방법도 있지만, 서로 발견한 것을 넘겨받게 하려면 사용자가 중간에서 계속 전달해야 합니다.

Claude Code의 에이전트 팀은 이 중간 전달을 세션끼리 하게 만드는 기능입니다. 한 세션이 리더가 되어 작업을 나누고, 나머지 세션이 팀원으로 각자 맡은 일을 합니다. 팀원은 리더를 거치지 않고 서로 메시지를 보낼 수 있고, 사용자도 팀원 한 명에게 바로 말을 걸 수 있습니다.

다만 기본으로 꺼져 있는 실험 기능이고, 켜면 세션 하나일 때보다 토큰을 훨씬 많이 씁니다. 모든 작업에 맞는 기능이 아니라, 팀원이 서로를 기다리지 않고 독립적으로 움직일 수 있는 작업에 맞는 기능입니다.

서브에이전트와 무엇이 다른가

서브에이전트와 에이전트 팀은 둘 다 작업을 나눠 병렬로 돌립니다. 차이는 결과가 어디로 가는지입니다. 서브에이전트는 일을 마치면 결과를 호출한 세션에 돌려주고 끝납니다. 에이전트 팀의 팀원은 독립된 세션으로 남아서 서로 메시지를 보내고, 공유 작업 목록에서 다음 일을 직접 가져갑니다.

이름을 붙인 서브에이전트끼리도 메시지를 주고받을 수 있어서, 메시지를 보낼 수 있느냐만으로 둘을 가르면 틀립니다. 기준은 팀원이 공유 작업 목록과 메시지로 스스로 조율하며 독립 세션으로 오래 남는지입니다.

팀을 만들기 전에 더 가벼운 방법이 맞는지 먼저 봅니다. 결과만 받으면 되는 조사라면 서브에이전트로 충분합니다. 이미 따로 띄운 세션 사이에서 결과만 오가면 된다면 세션 간 메시징이 있고, 자동 조율 없이 병렬 세션을 직접 다루고 싶다면 Git 워크트리로 세션을 나눌 수도 있습니다.

팀을 이루는 네 가지

에이전트 팀은 네 부분으로 이루어집니다.

작업은 대기, 진행, 완료 세 상태를 가집니다. 다른 작업에 의존하는 작업은 그 작업이 끝나기 전에는 가져갈 수 없고, 앞 작업이 끝나면 사용자가 손대지 않아도 막힌 작업이 풀립니다. 여러 팀원이 같은 작업을 동시에 가져가려 할 때는 파일 잠금으로 겹치지 않게 합니다. 이 공유 작업 목록은 Task 도구를 쓸 수 있는 팀원에게 적용됩니다. 해당 도구가 없는 팀원은 메시지를 주고받으며 작업을 조율합니다.

각 에이전트의 메일박스는 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json 파일입니다. 메시지는 수신자의 메일박스에 쓰기가 성공했을 때만 전송된 것으로 처리되고, 디스크가 가득 차서 쓰기가 실패하면 보낸 쪽이 오류를 받습니다. 팀 구성은 ~/.claude/teams/{team-name}/config.json에, 작업 목록은 ~/.claude/tasks/{team-name}/에 저장됩니다. 팀 이름은 session- 뒤에 세션 ID의 앞 8자가 붙는 형태입니다.

config.json에는 세션 ID와 tmux 창 ID 같은 실행 중 상태가 들어 있어서, 직접 고치거나 미리 만들어 두면 다음 상태 갱신 때 덮어씌워집니다. 프로젝트 폴더의 .claude/teams/teams.json 같은 파일도 팀 구성으로 읽히지 않습니다. 팀 역할을 재사용하고 싶다면 뒤에서 다룰 서브에이전트 정의를 씁니다.

켜는 방법

환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 설정하면 켜집니다. 셸 환경에 넣어도 되고, settings.json의 env에 넣어도 됩니다.

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

이 변수가 없으면 세션을 시작해도 팀이 설정되지 않고 팀 디렉터리도 만들어지지 않으며, Claude가 팀원을 만들거나 제안하지도 않습니다. 이미 다른 설정이 들어 있는 settings.json이라면 지우지 말고 env 항목만 추가합니다.

켜기 전에 알아 둘 점이 세 가지 있습니다.

첫째, 켜면 평소의 위임 방식도 달라집니다. Claude는 서브에이전트에 스스로 이름을 붙일 수 있고, 에이전트 팀이 켜져 있으면 이름이 붙은 서브에이전트가 팀원으로 시작됩니다. 팀을 요청하지 않은 위임에서도 팀원이 생길 수 있다는 뜻입니다. 이 동작이 싫으면 같은 변수를 0으로 바꿉니다. 새 세션을 열 필요 없이, 설정 파일을 저장하면 실행 중인 세션에 반영되고 그다음에 만드는 서브에이전트부터 일반 서브에이전트로 시작됩니다.

둘째, 0으로 바꿔도 다른 설정 소스가 1을 다시 켜 둘 수 있습니다. 프로젝트 설정, 로컬 설정, --settings로 넘긴 값은 사용자 설정보다 나중에 적용되므로 거기서 1로 두었다면 그쪽이 이깁니다. 조직의 관리 설정이 켜 두었다면 관리자에게 바꿔 달라고 해야 합니다.

셋째, 팀원 생성에는 대화형 세션이 필요합니다. claude -p 같은 비대화형 모드와 Agent SDK 세션에서는 이름이 붙은 서브에이전트도 일반 서브에이전트로 실행됩니다.

첫 팀 만들기

켜고 나면 자연어로 원하는 일과 팀원을 설명하면 됩니다. 처음에는 코드를 쓰지 않는 작업이 낫습니다. 경계가 분명하고 병렬 조사의 이점이 바로 보이는 일, 예를 들어 풀 리퀘스트 검토, 라이브러리 조사, 버그 원인 조사가 그렇습니다. 병렬 구현에 따라오는 조율 문제를 겪지 않고 팀의 동작을 볼 수 있습니다.

방금 만든 인증 모듈 변경분을 읽기 전용으로 검토할 팀원 세 명을 만들어 주세요.
- security: 토큰 처리와 세션 관리, 입력 검증만 봅니다
- failure: 실패 경로와 예외 처리, 재시도와 경계 상태만 봅니다
- tests: 테스트가 비어 있는 곳과 회귀 위험만 봅니다
코드는 고치지 말고, 지적마다 파일 위치와 재현 근거를 함께 보고해 주세요.
모두 끝날 때까지 기다린 뒤 중복을 합치고, 근거가 없는 지적은 따로 표시해 주세요.

이 프롬프트는 팀원 수, 각자의 렌즈, 수정 금지, 보고 형식, 마무리 방식을 한 번에 정합니다. “에이전트 세 명을 써 줘”처럼 쓰면 같은 곳을 세 번 읽는 팀이 되기 쉽습니다. 팀원에게 붙일 이름도 프롬프트에서 정해 주면 이후 “failure 팀원에게 물어봐”처럼 이름으로 부를 수 있습니다.

실제로 팀이 만들어졌는지는 프롬프트 입력창 아래의 에이전트 패널에서 봅니다. 그런데 서브에이전트도 팀원과 같은 패널에 나타납니다. 패널에 이름이 보인다는 이유만으로 팀이라고 판단할 수 없고, Claude가 팀 대신 서브에이전트를 만든 경우도 있습니다. 그럴 때는 에이전트 팀으로 만들어 달라고 다시, 명시적으로 요청합니다.

리더가 팀원을 기다리지 않고 직접 구현을 시작하는 일도 있습니다. 눈에 띄면 “팀원들이 작업을 끝낼 때까지 기다린 뒤에 진행해 주세요”라고 말합니다.

팀원 화면을 보고 말 걸기

팀원은 완전한 독립 세션이라 사용자가 직접 추가 지시를 하거나 방향을 바꿀 수 있습니다. 기본 모드에서 쓰는 키는 다음과 같습니다.

유휴 상태의 팀원 행은 다른 팀원이나 서브에이전트가 일하는 동안 패널에 남습니다. 패널의 모든 에이전트가 유휴가 되면 30초 뒤 행이 숨겨지고, 팀원의 다음 턴에 다시 나타납니다. 숨겨졌을 뿐 팀원은 계속 실행 중이고 이름으로 메시지를 보낼 수 있습니다. 유휴 팀원이 세 명 이상이면 세 번째 뒤의 행들이 “N명이 유휴 상태” 한 줄로 접히고, 선택한 뒤 Enter를 누르면 펼쳐집니다.

팀원 대화를 보는 동안 입력한 일반 텍스트와 스킬은 그 팀원에게 전달되고, 내장 명령은 리더 세션에 적용됩니다. 그래서 /compact, /clear, /rewind는 리더의 대화를 건드리므로 실행 전에 확인을 묻습니다. /model과 /fast는 이 화면에서 실행되지 않습니다. 팀원의 모델과 빠른 모드는 만들어질 때 정해지기 때문입니다.

표시 모드: 한 화면 또는 분할 창

팀원을 보여 주는 방식은 두 가지입니다.

• in-process: 모든 팀원이 메인 터미널 안에서 실행됩니다. 어느 터미널에서나 되고 추가 설정이 필요 없습니다. 기본값입니다.
• 분할 창: 팀원마다 자기 창을 가집니다. 모든 출력을 한꺼번에 볼 수 있고 창을 눌러 바로 대화할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

~/.claude/settings.json의 teammateMode로 기본값을 바꿉니다.

{
  "teammateMode": "auto"
}

값은 네 가지입니다. "in-process"는 기본값이고, "auto"는 이미 tmux 세션 안에 있거나 it2 CLI가 설치된 iTerm2일 때만 분할 창을 쓰고 아니면 in-process로 돌아갑니다. "tmux"는 분할 창을 켜고 tmux와 iTerm2 중 환경에 맞는 쪽을 자동으로 고릅니다. "iterm2"는 iTerm2 네이티브 분할 창을 명시하며 it2가 없으면 설치 명령과 함께 오류를 냅니다. 한 세션에서만 바꾸려면 플래그를 씁니다.

claude --teammate-mode auto

이 플래그는 실험 기능이라 claude --help에 나오지 않습니다.

분할 창 준비물은 다음과 같습니다. tmux는 패키지 관리자로 설치하고, macOS에서 가장 잘 동작하며 iTerm2에서 tmux -CC로 쓰는 것이 권장됩니다. iTerm2는 it2 CLI를 설치하고 iTerm2 → Settings → General → Magic → Enable Python API를 켭니다. VS Code 통합 터미널, Windows Terminal, Ghostty에서는 분할 창이 지원되지 않으므로 이 환경에서는 in-process를 씁니다.

팀원이 패널에 안 보여서 tmux를 의심하게 되면 PATH에서 찾을 수 있는지 확인합니다.

which tmux

팀원 수와 모델

팀원 수에 하드 한도는 없지만 현실적인 한도가 있습니다. 토큰 비용은 팀원 수에 따라 늘고, 팀원이 많을수록 메시지와 작업 조율, 충돌 가능성이 늘며, 어느 지점부터는 팀원을 더해도 속도가 비례해서 오르지 않습니다. 대부분의 작업은 팀원 3–5명으로 시작하는 것이 균형이 맞습니다. 독립적인 작업이 15개라면 3명으로 시작합니다. 집중된 팀원 셋이 산만한 팀원 다섯보다 낫습니다.

작업 크기도 중요합니다. 너무 작으면 조율 비용이 이득보다 크고, 너무 크면 팀원이 확인 없이 오래 달려가서 헛수고가 될 위험이 큽니다. 함수 하나, 테스트 파일 하나, 검토 한 건처럼 결과물이 분명한 단위가 알맞고, 팀원당 5–6개 작업이 있으면 모두가 놀지 않고 누가 막혀도 리더가 재배정할 수 있습니다.

모델은 프롬프트에서 지정할 수 있습니다.

팀원 네 명을 만들어 이 모듈들을 병렬로 리팩터링해 주세요. 팀원은 모두 Sonnet으로 실행해 주세요.

팀원 모델은 다음 순서로 정해지고, 먼저 해당하는 쪽이 이깁니다.

1. 팀원을 만드는 프롬프트에 적은 모델
2. 서브에이전트 정의로 만든 팀원이면 정의의 model(inherit는 리더 모델)
3. inherit가 아닌 값으로 설정된 CLAUDE_CODE_SUBAGENT_MODEL
4. 리더의 현재 모델

선택한 모델이 조직의 availableModels 허용 목록에서 막히면 대체 모델이 쓰입니다. opus 같은 패밀리 별칭은 허용 목록이 허용하는 그 패밀리의 최신 버전으로, 그 밖의 값은 리더의 모델로 바뀝니다. 그래서 보고서에 모델을 적을 일이 있다면 요청한 모델이 아니라 실제로 실행된 모델을 확인해서 적습니다. 팀원의 모델과 빠른 모드는 생성 시점에 고정되고, 기본적으로 리더의 노력 수준(effort)을 이어받습니다.

구현 전에 계획부터 시키기

복잡하거나 위험한 작업은 팀원이 구현하기 전에 계획부터 세우게 할 수 있습니다. 리더를 먼저 plan mode로 바꾼 뒤 팀원을 요청하면, 그 팀원은 계획이 준비될 때까지 읽기 전용 plan mode에서 일하고 계획이 끝나면 리더에게 승인 요청을 보냅니다.

여기서 승인 방식을 알아 둬야 합니다. 팀원을 만든 뒤 그 팀원의 권한 모드를 바꾸지 않았다면, 계획 승인 요청은 도착하는 즉시 자동 승인됩니다. 리더가 계획을 읽고 판단하는 단계가 없습니다. 리더가 계획을 직접 검토하게 하려면 in-process 팀원의 화면에서 Shift+Tab을 눌러 그 팀원을 plan mode로 바꿉니다. 이 경우에는 리더가 계획을 승인하거나 수정하라고 돌려보내며, 사용자에게 승인을 묻지는 않습니다.

작업 목록으로 일 나누기

공유 작업 목록은 리더가 만들고 팀원이 처리합니다. 배정은 두 가지 방식입니다. 리더에게 “이 작업은 이 팀원이 맡아 줘”라고 말해 직접 배정하거나, 팀원이 일을 끝낸 뒤 아직 배정되지 않았고 막히지 않은 다음 작업을 스스로 가져가게 둡니다.

작업 수가 모자라면 팀원 일부가 놀게 됩니다. 그럴 때는 작업을 더 잘게 나누라고 리더에게 말합니다. 반대로 팀원이 일을 끝냈는데 작업 상태가 완료로 안 바뀌어 의존 작업이 막혀 있는 경우도 있습니다. 작업이 실제로 끝났는지 확인하고, 상태를 직접 바꾸거나 리더에게 팀원을 재촉하라고 말합니다.

권한은 어떻게 적용되나

팀원은 리더의 권한 모드로 시작합니다. 예외는 dontAsk 모드로, 이 모드는 이어받지 않습니다. 리더를 --dangerously-skip-permissions로 실행했다면 팀원도 같은 모드로 실행됩니다. 생성한 뒤에는 팀원별로 모드를 바꿀 수 있지만, 생성하는 시점에 팀원별 모드를 정할 수는 없습니다.

팀원이 권한을 요청하는 프롬프트는 리더 세션에 나타납니다. 팀원 여러 명의 요청이 리더 화면에 몰리면 마찰이 커지므로, 팀을 만들기 전에 자주 쓰는 작업을 권한 설정에서 미리 허용해 두면 중단이 줄어듭니다.

분할 창을 쓸 때는 플래그 하나를 조심합니다. in-process 팀원은 리더의 실시간 허용·거부 규칙을 그대로 따르지만, 분할 창 팀원에게 --allowedTools는 전달되지 않습니다. 이 플래그로만 허용해 둔 작업은 분할 창 팀원에서는 미리 승인된 것이 아닙니다. 미리 승인하려면 리더를 시작할 때 --settings로 permissions.allow에 규칙을 넣습니다.

claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'

이 규칙은 그 세션의 리더와 분할 창 팀원 모두에 적용됩니다. --disallowedTools와 --tools는 분할 창 팀원에게도 이어집니다(Claude Code v2.1.309 이상).

에이전트끼리 보내는 메시지는 사용자의 확인이 아닙니다. 팀원은 권한 프롬프트를 승인할 수 없고, 사용자를 대신해 동의할 수도 없으며, 작업이 거부된 팀원이 다른 팀원에게 부탁해서 확인을 우회할 수도 없습니다. 자동 모드에서는 분류기가 다른 에이전트가 “승인받았다”고 전한 내용을 신뢰할 수 없는 입력으로 다루고, 전달 전에 메시지를 검토합니다.

팀원에게 무엇을 알려 줘야 하나

팀원은 CLAUDE.md, MCP 서버, 스킬을 일반 세션처럼 로드하지만 리더의 대화 기록은 받지 못합니다. 받는 것은 리더가 쓴 생성 프롬프트입니다. 리더와 한참 이야기한 끝에 “이제 팀을 만들자”고 했다면, 그 이야기에서 나온 결정과 제약이 팀원에게 가지 않는다는 뜻입니다.

그래서 생성 프롬프트에 작업별 세부 사항을 직접 적습니다.

보안 검토 팀원을 만들어 주세요. 프롬프트: "src/auth/ 인증 모듈을 읽고 보안 취약점을
찾아 주세요. 토큰 처리, 세션 관리, 입력 검증을 중점으로 봅니다. 앱은 JWT를
httpOnly 쿠키에 저장합니다. 문제마다 심각도를 붙여 보고해 주세요."

파일 범위, 이미 정해진 전제(어떤 방식으로 토큰을 저장하는지 같은), 보고 형식이 들어 있습니다. 팀원이 이 전제를 모르면 이미 정해진 부분을 다시 의심하느라 시간을 씁니다.

같은 파일을 두 명이 고치면

두 팀원이 같은 파일을 편집하면 한쪽 변경이 덮어씌워질 수 있습니다. 읽기 전용 검토는 같은 파일을 여럿이 봐도 충돌이 없지만, 수정이 들어가면 팀원마다 맡는 파일 집합을 나눕니다. 프런트엔드 팀원은 화면 코드만, 백엔드 팀원은 서버 코드만 고치는 식입니다. 여러 팀원이 같은 문제를 발견했다면 수정은 한 명에게만 맡깁니다.

팀이 파일이나 브랜치를 알아서 분리해 준다고 가정하지 않습니다. 격리가 필요하다면 별도의 작업 디렉터리를 쓰는 구성을 직접 정합니다. 팀원별 테스트를 통과했더라도 합친 뒤 전체 테스트를 다시 돌려야 하는 이유도 여기에 있습니다.

토큰 비용과 팀을 만들 가치

팀원마다 자기 컨텍스트 윈도우를 갖기 때문에 토큰 사용량은 활성 팀원 수에 따라 늘어납니다. 팀원 세 명이 단일 세션의 정확히 세 배를 쓴다고 계산할 수는 없고, 프롬프트 길이, 읽는 파일 크기, 대화량, 중복 조사, 모델에 따라 달라집니다. 연구, 검토, 새 기능 작업에서는 추가 토큰이 보통 값어치를 하고, 일상적인 작업에서는 세션 하나가 더 효율적입니다.

팀의 가치는 비용을 낸 만큼 더 나은 결과가 나왔는지로 봅니다. 팀을 만들지 말아야 할 때를 먼저 정리합니다.

• 한 파일의 작은 수정, 한 함수의 오타 수정처럼 작업이 하나로 끝나는 일
• 앞 작업의 결과가 있어야 뒤 작업을 시작할 수 있는 순차 작업
• 같은 파일을 여러 곳에서 고쳐야 하는 작업
• 의존 관계가 많아서 팀원이 서로를 기다리게 되는 작업

팀이 잘 맞는 일은 이쪽입니다.

• 보안·성능·테스트처럼 관점을 나눈 병렬 코드 검토
• 원인이 불분명한 버그를 가설별로 나눠 조사하는 일
• 프런트엔드, 백엔드, 테스트처럼 소유 범위가 분리되는 새 모듈이나 기능

원인이 불분명한 버그는 팀원들이 서로의 가설을 반박하게 하는 편이 좋습니다. 한 에이전트는 그럴듯한 설명 하나를 찾으면 거기서 멈추기 쉽지만, 팀원 각자가 다른 이론을 맡고 서로 반박하게 하면 끝까지 살아남은 이론이 실제 원인일 가능성이 높아집니다.

사용자가 메시지 하나만 보내면 연결이 끊긴다는 신고가 있습니다. 가설을 나눠 조사할
팀원 다섯 명을 만들어 주세요. 팀원끼리 서로의 가설을 반박하려고 토론하고, 마지막에
합의된 결론을 조사 문서에 정리해 주세요.

팀원들이 같은 결론에 이르렀다고 그것이 증거는 아닙니다. 같은 잘못된 전제를 공유했을 수 있습니다. 팀원 각자에게 코드 위치와 재현 조건을 보고하게 하고, 리더가 합친 뒤에는 사용자가 실제 코드와 테스트로 다시 확인합니다.

hooks로 기준 세우기

팀원이 일을 마치거나 작업이 만들어지고 완료되는 순간에 규칙을 적용하고 싶다면 hooks를 씁니다.

예를 들어 TaskCompleted에서 테스트를 돌려 실패하면 2로 끝나게 하면, 테스트가 깨진 채로 작업이 완료 처리되는 일을 막을 수 있습니다.

역할을 서브에이전트 정의로 재사용하기

보안 검토자나 테스트 실행자처럼 자주 쓰는 역할은 서브에이전트 정의로 한 번 만들어 두고 팀원으로도 쓸 수 있습니다. 팀원을 요청할 때 정의 이름을 말하면 됩니다.

security-reviewer 에이전트 유형으로 팀원을 만들어 인증 모듈을 점검해 주세요.

in-process 팀원에는 정의의 tools, model, disallowedTools, effort가 적용되고 본문은 기본 시스템 프롬프트에 추가 지시로 붙습니다. 팀원은 정의의 skills를 적용받지 않고 프로젝트와 사용자 설정의 스킬을 로드합니다. mcpServers는 분할 창 팀원에게만 적용되고 in-process 팀원은 이 필드를 무시합니다. 같은 정의라도 표시 모드에 따라 적용되는 필드가 다르므로, 중요한 제한을 정의에 넣었다면 실제 팀원에서 효과가 있는지 확인합니다.

끝내고 정리하기

작업을 마치면 이름으로 종료를 요청합니다.

researcher 팀원에게 종료하라고 전해 주세요.

리더가 종료 요청을 보내면 팀원은 승인해서 정상 종료하거나, 이유를 달아 거부할 수 있습니다. 팀원은 현재 요청이나 도구 호출을 마친 뒤 종료하므로 시간이 걸릴 수 있습니다.

종료와 변경 사항은 다른 문제입니다. 팀원을 끝내도 이미 수정한 파일은 그대로 남습니다. 작업 목록에서 완료로 표시된 것과 병합 가능한 상태인 것도 다릅니다. 종료 전에 수정한 파일, 통과한 테스트, 아직 확인하지 못한 부분을 리더에게 정리하게 하고, 병합이나 배포처럼 다른 사람에게 영향을 주는 단계는 팀원의 완료 판단과 별개로 사용자가 승인합니다.

디스크에 남는 것도 정리해 둡니다. 팀 구성 디렉터리는 세션이 끝날 때 지워지지만, 작업 목록은 세션이 끝난 뒤에도 ~/.claude/tasks/{team-name}/에 남습니다. 보관 기간은 cleanupPeriodDays 설정으로 바꿉니다. 정리를 하겠다고 이 내부 디렉터리를 직접 지우는 방식은 쓰지 않습니다. 실행 중인 팀의 작업이나 메시지를 잃을 수 있습니다.

분할 창을 쓴 뒤 tmux 세션이 남아 있다면 먼저 목록으로 세션 이름을 확인합니다. 이 명령은 조회만 합니다.

tmux ls

목록에서 팀이 만든 세션만 골라 종료합니다. 종료 명령은 세션 안에서 돌고 있는 작업을 끝내므로 다른 용도로 쓰는 세션은 끄지 않습니다.

종료는 tmux kill-session -t 뒤에 확인한 세션 이름을 붙여 실행합니다. 꺾쇠 괄호가 들어간 자리 표시자를 그대로 복사하면 셸이 리다이렉션으로 읽어 실패하므로, 종료 명령은 코드 블록에 두지 않고 이름을 확인한 뒤 직접 입력합니다.

알려진 제한

실험 기능이어서 현재 제한이 있습니다.

• 재개 불가: /resume과 /rewind는 in-process 팀원을 복원하지 않습니다. 세션을 재개한 뒤에 리더가 사라진 팀원에게 메시지를 보내려 할 수 있고, 그럴 때는 새 팀원을 만들게 합니다.
• 작업 상태 지연: 팀원이 작업을 완료로 표시하지 못해 의존 작업이 막힐 수 있습니다.
• 느린 종료: 팀원은 진행 중인 요청을 끝낸 뒤 종료합니다.
• 세션당 한 팀: 한 세션은 정확히 하나의 팀만 가지며 세션 사이에 팀을 공유할 수 없습니다.
• 중첩 팀 없음: 팀원은 자기 팀원을 만들 수 없고 리더만 팀을 관리합니다.
• 리더 고정: 팀을 만든 세션이 끝까지 리더이고 팀원을 리더로 올릴 수 없습니다.
• 분할 창 환경: VS Code 통합 터미널, Windows Terminal, Ghostty에서는 분할 창이 지원되지 않습니다.
• in-process 팀원의 백그라운드 서브에이전트 없음: 그 팀원이 만드는 서브에이전트는 포그라운드에서 실행됩니다.

막혔을 때 확인할 곳

마무리 정리

• 에이전트 팀은 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 켜는 실험 기능입니다. 켜면 이름이 붙은 서브에이전트가 팀원이 될 수 있으니, 의도하지 않은 팀이 싫다면 0으로 되돌립니다.
• 결과만 필요한 일은 서브에이전트가, 서로 반박하고 조율해야 하는 일은 팀이 맞습니다. 순차 작업과 같은 파일 수정에는 팀이 불리합니다.
• 처음에는 읽기 전용 검토나 원인 조사처럼 코드를 쓰지 않는 작업을 팀원 3명 안팎으로 시작합니다. 팀원마다 렌즈, 파일 범위, 보고 형식을 프롬프트에 적습니다.
• 수정이 들어가는 팀은 파일 소유를 나누고, 합친 뒤 전체 테스트를 다시 돌립니다. 병합과 배포는 팀의 완료 보고와 별개로 사용자가 승인합니다.
• 끝낼 때는 팀원에게 종료를 요청하고, 남은 작업 목록과 tmux 세션은 직접 확인합니다.