Claude Code 가이드

Claude Code 가이드 #13 — Agent Teams 실전 가이드

팀 에이전트가 파일을 못 만드는 이유부터 --dangerously-skip-permissions까지. Agent Teams 권한 모델과 실전 구성법.

2026-03-05

Claude Code 가이드 #13 — Agent Teams로 팀원 에이전트를 띄웠는데, 파이썬 스크립트를 만들라고 하면 "권한이 없다"고 거부당한 경험이 있나요? 이 편에서는 Agent Teams의 동작 원리, 권한 모델, 그리고 --dangerously-skip-permissions까지 실전 기준으로 정리합니다.

※ 이 글은 2026년 3월 기준, Claude Code 공식 문서 기반으로 작성됐습니다. Agent Teams는 실험적 기능(experimental)입니다.

Agent Teams란 무엇인가?

Agent Teams는 여러 개의 독립 Claude Code 세션이 하나의 프로젝트에서 협업하는 기능입니다. 2026년 2월에 실험적 기능으로 추가됐습니다.

기존 서브에이전트(Subagent)와의 핵심 차이:

항목	서브에이전트	Agent Teams
실행 방식	부모 세션 안에서 격리 실행	독립 세션 (별도 프로세스)
통신	결과를 부모에게만 보고	팀원 간 직접 메시지 교환
구조	부모 → 자식 (단방향)	lead + teammates (양방향)
권한	부모의 권한 상속	각 세션이 독립적 권한
작업 조율	없음	공유 task list

Agent Teams란 무엇인가? — CLI 실행 화면과 출력 결과 — Claude Code 가이드 #13 — Agent Teams 실전 가이드 — CLI 실행 화면과 출력 결과 (출처: 공식 문서 및 벤치마크 데이터 기반)

📌 참고: Agent Teams는 실험적 기능이라 환경변수로 활성화해야 합니다. 기본 상태에서는 사용할 수 없습니다.

Agent Teams 활성화 방법

Agent Teams를 사용하려면 환경변수를 설정해야 합니다. 두 가지 방법이 있습니다.

방법 1: 환경변수로 직접 실행
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

방법 2: settings.json에 영구 설정
# ~/.claude/settings.json 또는 .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

활성화 후 Claude Code에서 팀을 구성할 수 있습니다. lead(리더)가 teammates(팀원)를 생성하고, 각 팀원에게 작업을 배분합니다.

팀 구성 예시 — 프롬프트
포스팅 만들땐 TeamCreate로 에이전트 팀생성해줘.
에이전트 팀으로 프로젝트 코드를 병렬 리뷰하고,
각 팀원이 변경하기 전에 반드시 plan approval 받도록 해줘.
모든 팀원 모델은 Sonnet으로 설정해줘.

왜 팀 에이전트가 파일을 못 만드나?

핵심 원인: 각 팀원 세션이 독립적인 권한 모드를 갖기 때문입니다.

Claude Code에는 4가지 권한 모드가 있습니다:

모드	동작	팀원 에이전트에서?
Ask permissions	매 동작마다 사용자 승인 요청	팀원이 파일 생성/수정/명령 실행 때마다 멈춤
Auto accept edits	파일 편집만 자동 승인	파일은 되지만 `python` 등 셸 명령은 여전히 차단
Plan mode	읽기만 가능, 실행 불가	아무것도 실행 못함 (계획 수립 전용)
dontAsk	모든 동작 자동 승인	`--dangerously-skip-permissions`로만 활성화

팀원 에이전트에게 "파이썬으로 크롤링 스크립트 만들어"라고 시키면, 팀원은 다음 작업을 순서대로 시도합니다:

파일 생성 (crawler.py) → 파일 쓰기 권한 필요
pip install (requests, beautifulsoup4) → 셸 명령 실행 권한 필요
python crawler.py 실행 → 셸 명령 실행 권한 필요

기본 모드(Ask permissions)에서는 이 세 단계 모두에서 사용자 승인을 기다립니다. 팀원 에이전트는 독립 세션이라 사용자가 직접 승인 UI를 보기 어렵고, 결과적으로 "권한이 없다"며 작업이 멈추는 것입니다.

Agent Teams 활성화 방법 — 설정 구조와 워크플로우 다이어그램 — Claude Code 가이드 #13 — Agent Teams 실전 가이드 — 설정 구조와 워크플로우 다이어그램 (출처: 공식 문서 및 벤치마크 데이터 기반)

⚠️ 막히는 케이스: "Auto accept edits" 모드로 해도 안 되는 이유 — 이 모드는 파일 편집만 자동 승인합니다. python, pip install, npm run 같은 셸 명령 실행은 여전히 승인이 필요합니다. 파이썬 크롤링처럼 셸 실행이 포함된 작업은 이 모드로도 부족합니다.

--dangerously-skip-permissions 완전 해설

--dangerously-skip-permissions는 Claude Code의 모든 권한 확인을 건너뛰는 플래그입니다. 이름에 "dangerously"가 붙은 이유가 있습니다.

이 플래그가 하는 것

파일 생성/수정/삭제 → 자동 승인
셸 명령 실행 (python, npm, git 등) → 자동 승인
외부 API 호출 → 자동 승인
시스템 설정 변경 → 자동 승인

이 플래그가 위험한 이유

악의적 프롬프트에 의한 임의 코드 실행 가능
rm -rf 같은 파괴적 명령어도 확인 없이 실행
API 키, 환경변수 등 민감 정보 유출 가능
Anthropic 공식 문서에서도 프로덕션 사용 금지 명시

skip-permissions 실행 방법
# 단독 세션 — 모든 권한 건너뛰기
claude --dangerously-skip-permissions

# Agent Teams + skip-permissions
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --dangerously-skip-permissions

⚠️ 막히는 케이스: --dangerously-skip-permissions를 썼는데도 팀원이 권한 에러를 낸다면 — lead 세션만 skip-permissions로 띄우고, teammate 세션은 기본 모드로 생성됐을 수 있습니다. settings.json에 "env"로 팀 전체에 적용되도록 설정하세요.

skip-permissions 없이 팀 에이전트 운영하기

--dangerously-skip-permissions가 부담된다면, 더 안전한 방법이 있습니다.

방법 1: allowedTools로 필요한 도구만 허용

settings.json에서 특정 도구만 자동 승인할 수 있습니다.

settings.json — 선택적 권한 부여
// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(python *)",
      "Bash(pip install *)",
      "Bash(node *)"
    ]
  }
}

이렇게 하면 파일 편집과 특정 셸 명령만 자동 승인되고, 그 외 명령은 여전히 승인을 요구합니다.

방법 2: Plan mode → 승인 → 실행 패턴

팀원을 Plan mode로 시작시키고, 계획을 확인한 뒤 실행 권한을 부여하는 패턴입니다.

Plan → 승인 → 실행 워크플로우
# 1. Plan mode로 시작 (읽기 전용)
# 팀원이 "무엇을 할지" 계획만 세움

# 2. 계획 확인 후 /permissions 로 권한 변경
/permissions
# → Auto accept edits 또는 필요한 도구 허용

# 3. 실행 승인
# 팀원이 계획대로 작업 실행

💡 팁: 팀 에이전트로 포스팅을 만들 때는 Plan mode → 승인 패턴이 가장 안전합니다. 파이썬 크롤링처럼 셸 실행이 반복되는 작업에는 allowedTools로 Bash(python *)만 허용하는 것이 실용적입니다.

언제 skip-permissions를 써도 되나?

Anthropic 공식 문서에서도 --dangerously-skip-permissions의 사용 시나리오를 구분합니다.

✅ 써도 되는 상황	❌ 쓰면 안 되는 상황
로컬 개발 머신에서 개인 작업	프로덕션 서버/CI 환경
신뢰할 수 있는 프로젝트의 반복 작업	신뢰할 수 없는 레포 클론 후 실행
광고 수정, H2 재작성 등 단순 유지보수	외부 입력을 처리하는 자동화
검증 스크립트 일괄 실행	여러 사용자가 접근하는 공유 환경

왜 팀 에이전트가 파일을 못 만드나? — 에러 해결 프로세스 흐름도 — Claude Code 가이드 #13 — Agent Teams 실전 가이드 — 에러 해결 프로세스 흐름도 (출처: 공식 문서 및 벤치마크 데이터 기반)

⚠️ 막히는 케이스: 외부에서 받은 레포를 --dangerously-skip-permissions로 열면, 레포에 포함된 .claude/settings.json이나 .mcp.json이 악의적 명령을 자동 실행할 수 있습니다. 이것이 실제 보안 취약점(CVE-2026-21852)으로 보고된 사례입니다. 신뢰할 수 없는 레포에서는 절대 사용하지 마세요.

실전: 팀 에이전트 구성 예시

실무에서 자주 쓰는 팀 구성 패턴입니다.

패턴 1: 콘텐츠 생성 팀

포스팅이나 문서를 만들 때 사용하는 구성입니다.

콘텐츠 생성 팀 프롬프트
# 팀 역할 구성
Editor Lead (Sonnet)  — 방향 설정, 최종 승인
SEO Reviewer (Sonnet) — 검색의도, 내부링크 검수
Content Builder A (Sonnet) — 포스트 초안 작성
Content Builder B (Sonnet) — 포스트 초안 작성

# 권한 설정: plan approval 모드
# → 각 팀원이 파일 변경 전 계획을 Editor Lead에게 보고
# → 승인 후 실행

패턴 2: 크롤링/자동화 팀

파이썬 크롤링처럼 셸 실행이 필요한 작업입니다.

크롤링 팀 — allowedTools 방식 (권장)
# .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(python *)",
      "Bash(pip install *)",
      "Bash(curl *)",
      "Bash(node --check *)"
    ]
  }
}

크롤링 팀 — skip-permissions 방식 (빠르지만 위험)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --dangerously-skip-permissions

💡 팁: 크롤링 작업에는 allowedTools 방식을 권장합니다. python과 pip만 허용하면 의도치 않은 rm이나 git push 같은 위험한 명령은 여전히 차단됩니다.

팀 작업 모니터링 — 표시 모드

Agent Teams가 작업하는 동안 진행 상황을 볼 수 있는 두 가지 모드가 있습니다.

in-process (기본): 하나의 터미널 안에서 모든 팀원의 출력을 합쳐서 표시
split panes: tmux나 iTerm2를 사용해 각 팀원을 별도 패널에 표시

split panes 모드를 쓰면 각 팀원이 뭘 하고 있는지 실시간으로 볼 수 있어서, 권한 문제가 발생했을 때 어떤 팀원이 멈췄는지 바로 파악할 수 있습니다.

팀 에이전트 트러블슈팅

Agent Teams 사용 중 자주 발생하는 문제와 해결법입니다.

⚠️ 막히는 케이스: Agent Teams가 활성화 안 됨 — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수가 설정되지 않았습니다. settings.json의 env 블록에 추가하거나, 실행 시 앞에 붙이세요.

⚠️ 막히는 케이스: 팀원이 파일을 생성/실행하지 못하고 멈춤 — 기본 Ask permissions 모드 때문입니다. allowedTools로 필요한 도구를 허용하거나, --dangerously-skip-permissions를 사용하세요.

⚠️ 막히는 케이스: lead는 skip-permissions인데 teammate는 아님 — --dangerously-skip-permissions는 실행한 세션에만 적용됩니다. 팀원 세션도 같은 설정을 갖으려면 .claude/settings.json의 permissions.allow를 프로젝트 레벨로 설정하세요.

⚠️ 막히는 케이스: 팀원끼리 같은 파일을 동시에 수정해서 충돌 발생 — Agent Teams의 공유 task list를 활용해서 파일 단위로 작업을 분배하세요. 같은 파일을 두 팀원에게 할당하지 마세요.

요약 및 관련 편

정리하면:

Agent Teams 팀원이 파일 생성/셸 실행을 못하는 이유는 독립 세션의 기본 권한 모드(Ask permissions) 때문
--dangerously-skip-permissions는 모든 권한을 건너뛰는 플래그로, 로컬 개인 작업에서만 사용
더 안전한 방법은 allowedTools로 필요한 도구만 선택적으로 허용하는 것
프로덕션/공유 환경에서는 Plan mode → 승인 → 실행 패턴 사용