Claude Code 병렬 에이전트 사용법 7단계 — 서브에이전트 설정부터 Worktre

“Claude Code는 한 번에 하나씩 순차적으로 작업을 처리한다”라고들 하는데, 사실 아니다. Claude Code 병렬 에이전트 사용법을 알면 인증 모듈, 데이터베이스, API 레이어를 동시에 조사하거나 리팩토링하는 것이 가능하다. 서브에이전트(subagent)라는 개념이 핵심인데, 각 서브에이전트가 독립된 컨텍스트 윈도우에서 병렬로 실행되면서 결과를 메인 대화로 모아준다. 순차 실행 대비 작업 시간이 크게 단축되는 것은 물론이고, worktree 격리를 걸면 서로의 코드 변경이 충돌하지 않는 구조까지 잡을 수 있다.

이 글에서는 서브에이전트를 정의하는 방법부터 병렬 실행 설정, worktree 격리, fork 모드, CLI 플래그 활용까지 단계별로 정리한다. 마지막에는 실전 체크리스트와 주의사항을 둔다.

서브에이전트 기본 구조 이해

Claude Code의 서브에이전트는 각각 독립된 컨텍스트 윈도우에서 실행된다. 커스텀 시스템 프롬프트, 도구 접근 권한, 독립적인 퍼미션을 가진다는 뜻이다. 메인 Claude Code 세션이 “팀장”이라면, 서브에이전트는 각자 맡은 영역만 파고드는 “팀원”에 해당한다.

서브에이전트는 .claude/agents/ 또는 ~/.claude/agents/ 디렉토리에 마크다운 파일로 정의한다. YAML frontmatter에 설정을 넣고, 그 아래에 시스템 프롬프트를 작성하는 구조다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

필수 필드는 name과 description 두 개뿐이다. 나머지는 모두 선택이다.

선택 필드 목록

필드	역할	기본값
`tools`	서브에이전트가 사용할 도구 목록	부모와 동일
`model`	사용할 모델 (sonnet, opus, haiku)	부모 모델 상속
`permissionMode`	권한 모드	부모와 동일
`isolation`	실행 격리 방식 (worktree 등)	없음
`background`	백그라운드 실행 여부	false
`maxTurns`	최대 턴 수	제한 없음

서브에이전트 파일 위치 선택 기준
프로젝트 전용 서브에이전트는 `.claude/agents/`에, 여러 프로젝트에서 공통으로 쓸 서브에이전트는 `~/.claude/agents/`에 둔다. 팀원과 공유가 필요하면 프로젝트 디렉토리 쪽이 Git으로 관리하기 편하다.

`tools` 필드에는 `Read`, `Glob`, `Grep`, `Bash`, `Edit`, `Write` 같은 도구를 지정한다. 코드 리뷰 전용 서브에이전트라면 `Edit`이나 `Write`를 빼는 것이 안전하다. 읽기 전용으로 제한하면 의도치 않은 코드 수정을 원천 차단할 수 있기 때문이다.

서브에이전트 중첩 제한

서브에이전트는 다른 서브에이전트를 스폰할 수 없다. 중첩 위임이 필요하면 Skills나 메인 대화에서 체이닝해야 한다. 이 제약은 실행 깊이가 무한히 늘어나는 것을 방지하기 위한 설계 결정이다.

Claude Code 병렬 에이전트 실행 설정

서브에이전트를 정의했으면 병렬로 실행하는 단계다. Claude Code 서브에이전트 공식 가이드에 따르면 여러 서브에이전트를 동시에 실행하여 독립적인 조사 경로에서 각각 별도로 탐색한 뒤, Claude가 결과를 종합하는 방식으로 동작한다.

예를 들어 메인 세션에서 이렇게 지시하는 것이 가능하다:

Research the authentication, database, and API modules in parallel using separate subagents

이 한 줄이면 Claude Code가 인증, 데이터베이스, API 모듈을 각각 별도 서브에이전트로 병렬 탐색한다.

background 필드와 Ctrl+B

background 필드를 true로 설정하면 해당 서브에이전트는 항상 백그라운드 태스크로 실행된다. YAML frontmatter에 background: true를 넣으면 된다. 서브에이전트가 포그라운드에서 실행 중일 때 Ctrl+B를 누르면 중간에 백그라운드로 전환할 수도 있다.

백그라운드 실행 시 도구 권한 주의
백그라운드 서브에이전트는 실행 전에 필요한 도구 권한을 미리 승인받는다. 승인받지 못한 도구는 auto-deny 처리된다. `Bash` 도구를 쓰는 서브에이전트라면 백그라운드 전환 전에 권한을 확인하는 것이 중요하다. 그렇지 않으면 핵심 명령어가 거부되어 작업이 중간에 멈추는 경우가 있다.

병렬 실행의 가장 큰 장점은 독립적인 작업을 동시에 돌려서 총 소요 시간을 줄이는 것이다. 인증 모듈 분석에 3분, DB 스키마 분석에 2분, API 엔드포인트 리뷰에 4분이 걸린다면, 순차 실행 시 9분이 소요되지만 병렬 실행 시에는 가장 긴 작업 기준 4분 정도면 완료된다.

병렬 실행에 적합한 작업 유형

모든 작업이 병렬에 적합한 것은 아니다. 다음 기준으로 판단하면 된다:

적합: 서로 다른 디렉토리나 모듈을 독립적으로 분석하는 작업
적합: 동일 코드베이스에서 읽기 전용 조사를 여러 관점에서 수행하는 작업
부적합: 한 서브에이전트의 출력이 다른 서브에이전트의 입력이 되는 순차 의존 작업
부적합: 같은 파일을 동시에 수정하는 작업 (충돌 발생)

같은 파일을 동시에 수정해야 하는 경우는 worktree 격리가 필요하다. 다음 섹션에서 다룬다.

Worktree 격리로 병렬 에이전트 충돌 방지

Claude Code 병렬 에이전트 사용법에서 가장 실용적인 기능 중 하나가 worktree 격리다. isolation 필드를 worktree로 설정하면 서브에이전트가 임시 git worktree에서 실행되어 저장소의 격리된 복사본을 받게 된다.

---
name: feature-builder
description: Builds a new feature in isolated worktree
tools: Read, Edit, Write, Bash
isolation: worktree
---

Implement the requested feature in the isolated worktree.
Focus on clean, testable code.

worktree 격리의 동작 방식은 다음과 같다:

서브에이전트 실행 시 현재 저장소 기반으로 임시 git worktree를 생성
서브에이전트는 이 격리된 복사본에서 자유롭게 파일을 수정
서브에이전트가 변경을 만들지 않으면 worktree가 자동으로 정리됨
변경이 있는 경우 워크트리와 브랜치를 유지하거나 제거할지 선택 가능

worktree 격리가 빛나는 시나리오
두 개의 서브에이전트가 각각 다른 접근 방식으로 같은 기능을 구현하게 하고, 결과를 비교해서 더 나은 쪽을 채택하는 A/B 구현 패턴에서 유용하다. 메인 브랜치를 오염시키지 않으면서 실험이 가능하기 때문이다.

worktree 없이 여러 서브에이전트가 같은 파일을 동시에 수정하면 git conflict가 발생한다. 격리를 걸면 각 서브에이전트가 독립된 브랜치에서 작업하므로 충돌 없이 병렬 수정이 가능해진다. 작업이 끝난 뒤 메인 브랜치에 merge하는 시점에서만 충돌을 해결하면 되는 방식이다.

Fork 모드로 컨텍스트 공유와 비용 절감

CLAUDE_CODE_FORK_SUBAGENT=1 환경변수로 활성화되는 Fork 모드는 일반 서브에이전트와 다른 실행 모델을 가진다.

일반 서브에이전트는 새로운 컨텍스트 윈도우에서 시작하지만, Fork 모드에서는 현재 대화의 전체 히스토리를 상속받아 실행된다. 부모와 동일한 시스템 프롬프트, 도구, 모델을 사용하는 것이 핵심이다.

항목	일반 서브에이전트	Fork 모드
컨텍스트	새로 시작	부모 히스토리 상속
시스템 프롬프트	커스텀 가능	부모와 동일
도구	커스텀 가능	부모와 동일
모델	커스텀 가능	부모와 동일
프롬프트 캐시	독립	부모 캐시 재활용
실행 방식	포그/백그라운드 선택	항상 백그라운드

Fork 모드의 가장 큰 이점은 부모의 프롬프트 캐시를 재활용하여 비용이 절감된다는 점이다. 대화가 길어질수록 컨텍스트 전송 비용이 커지는데, Fork 모드에서는 이미 캐시된 프롬프트를 그대로 쓰기 때문에 중복 비용이 줄어든다.

export CLAUDE_CODE_FORK_SUBAGENT=1
claude

환경변수를 설정한 상태에서 Claude Code를 실행하면 모든 서브에이전트 스폰이 자동으로 백그라운드에서 이루어진다.

병렬 서브에이전트 실행 시 토큰 비용에 대한 구체적 벤치마크는 공식 문서에도 명시되어 있지 않다. Fork 모드가 캐시 재활용으로 비용을 줄여준다는 것은 확인되지만, 정확한 절감 비율은 대화 길이와 모델에 따라 달라진다.

일반 모드와 Fork 모드 선택 기준

Fork 모드는 부모 대화의 맥락이 서브에이전트에게도 필요한 경우에 유리하다. 예를 들어 “지금까지 논의한 아키텍처 결정 사항을 바탕으로 각 모듈을 구현해라” 같은 지시를 내릴 때, Fork 모드라면 서브에이전트가 이전 대화 내용을 이미 알고 있으므로 별도 설명이 불필요하다.

반면 서브에이전트마다 전혀 다른 역할과 도구가 필요한 경우에는 일반 모드가 맞다. 코드 리뷰어에게는 Read만, 디버거에게는 Bash까지 주는 식으로 도구를 제한하려면 커스텀 서브에이전트 정의가 필요하기 때문이다.

–agents CLI 플래그로 빠른 테스트

서브에이전트를 파일로 만들지 않고도 CLI에서 바로 정의하는 방법이 있다. --agents 플래그에 JSON을 전달하면 세션 한정 서브에이전트가 생성된다. 디스크에 저장되지 않으므로 빠른 테스트나 자동화 스크립트에 적합하다.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

이 명령 한 줄로 code-reviewer와 debugger 두 개의 서브에이전트가 세션에 등록된다. description, prompt, tools, model 등 YAML frontmatter와 동일한 필드를 JSON으로 지원하는 구조다.

CLI 에이전트 활용 패턴

CI/CD 파이프라인에서 Claude Code를 호출할 때 --agents 플래그가 유용하다. 예를 들어 PR이 올라오면 자동으로 코드 리뷰 서브에이전트와 보안 검사 서브에이전트를 병렬로 실행하는 스크립트를 구성할 수 있다.

# CI 스크립트 예시 구조
claude --agents "$AGENT_CONFIG" \
  "Review the changes in this PR for code quality and security issues using both subagents in parallel"

파일 기반과 CLI 서브에이전트는 저장 방식과 용도 면에서 차이가 있다:

항목	파일 기반 (.claude/agents/)	CLI (–agents)
저장	디스크에 영구 저장	세션 종료 시 소멸
공유	Git으로 팀 공유 가능	환경변수·스크립트로 공유
수정	파일 편집	JSON 문자열 수정
용도	반복 사용하는 에이전트	실험·자동화·일회성 테스트

JSON 에이전트 설정 관리법
`–agents` JSON이 길어지면 별도 JSON 파일에 저장해두고 `claude –agents “$(cat agents.json)”`으로 읽어오면 관리가 쉬워진다. Git에는 커밋하되 `.claude/agents/` 마크다운 파일로 전환할 시점을 정해두는 편이 낫다.

## Claude Code 병렬 에이전트 실전 체크리스트

서브에이전트 설정부터 병렬 실행까지의 과정을 체크리스트로 정리한다. 실무 적용 시 놓치기 쉬운 항목을 포함한다.

서브에이전트 정의 체크리스트

name과 description 필수 필드를 모두 채웠는가
tools 목록이 최소 권한 원칙에 맞는가 (읽기 전용 에이전트에 Write 도구를 주지 않았는가)
model 선택이 작업 복잡도에 맞는가 (단순 검색은 haiku, 코드 분석은 sonnet)
파일 위치가 적절한가 (프로젝트 전용 → .claude/agents/, 글로벌 → ~/.claude/agents/)
시스템 프롬프트가 역할과 출력 형식을 명확히 정의하는가

병렬 실행 체크리스트

병렬 대상 작업이 서로 독립적인가 (순차 의존성이 없는가)
같은 파일을 수정하는 서브에이전트가 있다면 isolation: worktree를 설정했는가
백그라운드 실행 서브에이전트의 도구 권한을 미리 승인했는가
Fork 모드가 필요한 경우 CLAUDE_CODE_FORK_SUBAGENT=1 환경변수를 설정했는가
서브에이전트 설정 및 실행 옵션 문서를 참고하여 최신 필드를 확인했는가

트러블슈팅 체크리스트

서브에이전트가 도구를 사용하지 못한다면 → 백그라운드 실행 시 auto-deny 여부를 확인
worktree 서브에이전트의 변경 사항이 보이지 않는다면 → 별도 브랜치에 저장되었는지 확인
Fork 모드에서 서브에이전트가 의도와 다르게 동작한다면 → 부모 대화 히스토리에 혼란을 줄 수 있는 이전 지시가 없는지 확인
서브에이전트 중첩 호출이 실패한다면 → 서브에이전트는 다른 서브에이전트를 스폰할 수 없으므로 메인 대화에서 체이닝으로 전환

주의사항과 제약

Claude Code 병렬 에이전트 사용법을 익힐 때 알아두어야 할 제약 사항을 정리한다.

중첩 스폰 불가

서브에이전트가 내부에서 또 다른 서브에이전트를 호출하는 것은 불가능하다. 실행 깊이가 1단계로 제한된다. 복잡한 작업 분기가 필요하면 메인 세션에서 순차적으로 서브에이전트를 호출하거나, Skills를 활용해서 로직을 체이닝해야 한다.

Agent Teams 상세 문서 부재

Agent Teams(에이전트 팀) 기능의 상세 설정과 메시징 프로토콜 문서는 별도 조사가 필요한 상태다. 공식 문서에도 아직 명시되어 있지 않은 부분이 있으므로, 팀 단위 에이전트 오케스트레이션이 필요한 경우 서브에이전트 병렬 실행으로 대체하는 편이 현실적이다.

maxTurns 튜닝

프로덕션 환경에서 maxTurns와 auto-compaction 튜닝에 대한 사례는 공식 문서에 명시되어 있지 않다. maxTurns를 너무 낮게 잡으면 서브에이전트가 작업을 완료하지 못하고 중단되고, 너무 높게 잡으면 토큰 소비가 늘어나는 트레이드오프가 있다. 초기에는 기본값으로 시작하고 실제 작업 패턴을 보면서 조정하는 접근이 안전하다.

한국어 문서 참고 시 주의

한국어 공식 가이드의 번역 완성도는 미확인 상태다. 정확한 필드명이나 동작 방식은 영문 서브에이전트 상세 문서를 기준으로 확인하는 것이 안전하다.

도구 권한 최소화 원칙
서브에이전트에게 `Bash` 도구를 줄 때는 신중해야 한다. 특히 `isolation: worktree` 없이 `Bash`와 `Write`를 모두 허용하면 예상치 못한 파일 변경이 메인 브랜치에 직접 반영된다. 읽기 전용 조사 서브에이전트는 `Read`, `Glob`, `Grep`만 허용하는 것이 원칙이다.

## 다음 단계: 병렬 에이전트 너머

서브에이전트 병렬 실행이 익숙해지면 다음으로 살펴볼 영역이 몇 가지 있다. Claude Code의 hooks 기능을 활용하면 서브에이전트 실행 전후에 조건부 검증 로직을 삽입할 수 있다. 코드 리뷰 서브에이전트가 끝난 뒤 자동으로 린트를 돌리는 식의 파이프라인 구성이 가능해진다.

MCP 서버와의 연동도 확장 가능한 방향이다. 서브에이전트 정의에 mcpServers 필드를 추가하면 외부 API를 직접 호출하는 도구를 서브에이전트에게 제공할 수 있다. 그리고 서브에이전트 병렬 구성에 익숙해졌다면 Claude Code agent teams 오케스트레이션까지 시야를 넓혀볼 여지가 있다.

팀에서 Claude Code 멀티 에이전트 개발 환경을 도입할 때, 서브에이전트를 어떤 단위로 분리하고 어떤 작업에 worktree 격리를 적용할지가 첫 번째로 결정해야 할 Claude Code 병렬 에이전트 사용법의 설계 포인트다.

Claude Code 병렬 에이전트 3가지 차이점 — 세션·서브에이전트·팀 완전 비교 – Claude Code에서 병렬 작업을 처리하는 세 가지 방식 — 데스크톱 병렬 세션, 서브에이전트, Agent Teams — 의 아키텍처·…
Claude Code 웹 버전 사용법 — 브라우저 AI 코딩 시작하는 7단계 – Claude Code 웹 버전은 로컬 설정 없이 브라우저에서 AI 코딩 에이전트를 실행한다. GitHub 연동, 클라우드 환경 설정, 병렬…
Claude Code settings.json 전체 옵션 50개 완전 정복 — 권한·샌드박스·hooks 가이드 – Claude Code settings.json 전체 옵션 가이드. 5단계 우선순위 체계, permissions allow/deny 규칙, …

Claude Code 병렬 에이전트 사용법 7단계 — 서브에이전트 설정부터 Worktree 격리까지

목차

서브에이전트 기본 구조 이해

선택 필드 목록

서브에이전트 중첩 제한

Claude Code 병렬 에이전트 실행 설정

background 필드와 Ctrl+B

병렬 실행에 적합한 작업 유형

Worktree 격리로 병렬 에이전트 충돌 방지

Fork 모드로 컨텍스트 공유와 비용 절감

일반 모드와 Fork 모드 선택 기준

–agents CLI 플래그로 빠른 테스트

CLI 에이전트 활용 패턴

서브에이전트 정의 체크리스트

병렬 실행 체크리스트

트러블슈팅 체크리스트

주의사항과 제약

중첩 스폰 불가

Agent Teams 상세 문서 부재

maxTurns 튜닝

한국어 문서 참고 시 주의

관련 글