Claude Code 에이전트 여러 개를 동시에 실행하는 방법

Claude Code 에이전트를 병렬로 실행하는 네 가지 방법

서브에이전트: 한 세션 안의 병렬 도우미

서브에이전트는 자체 컨텍스트 창, 시스템 프롬프트, 도구를 가져요. 내 대화를 보지 못하고 요약만 돌려보내기 때문에 메인 세션의 컨텍스트가 작게 유지돼요. Claude Code에는 Explore(읽기 전용)와 Plan 같은 기본 서브에이전트가 있고, 직접 추가할 수도 있어요.

1. 서브에이전트 정의하기

   .claude/agents/(프로젝트와 공유) 또는 ~/.claude/agents/(나만 사용)에 Markdown 파일을 만드세요. 필수 항목은 name과 description뿐이고, tools는 쓸 수 있는 도구를 제한하며 model은 모델을 골라요.

   ---
   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 give
   specific, actionable feedback on quality, security and best practices.

2. Claude가 여러 개를 동시에 돌리게 하기

   병렬로 해 달라고 요청하세요. 예를 들어 “auth, billing, search 모듈을 병렬로 리뷰해 줘”처럼요. Claude가 만드는 서브에이전트는 기본적으로 백그라운드에서 시작되고, 한 번에 최대 20개까지 돌며, 끝나면 결과를 보고해요. /tasks를 입력하면 볼 수 있어요.

3. 파일을 수정하는 서브에이전트에게 별도 worktree 주기

   서브에이전트의 frontmatter에 isolation: worktree를 추가하거나, 에이전트에 worktree를 쓰라고 Claude에게 요청하세요. 그러면 각자 저장소의 임시 복사본을 수정하고, 변경이 없으면 복사본은 삭제돼요.

git worktree에서 Claude Code 세션을 병렬로 실행하기

1. worktree 폴더를 무시 목록에 넣기

   Claude Code는 저장소 루트의 .claude/worktrees/에 worktree를 만들어요. 저장소에 커밋이 최소 하나 있어야 해요.

   echo ".claude/worktrees/" >> .gitignore

2. 작업마다 세션을 하나씩 시작하기

   터미널마다 다른 이름으로 claude --worktree(또는 -w)를 실행하세요. 각각 자기 폴더와 기본 브랜치를 바탕으로 한 worktree-<name> 브랜치를 가져요.

   # 터미널 1
   claude --worktree feature-auth
   
   # 터미널 2
   claude --worktree bugfix-login

3. 필요한 미추적 파일 복사하기

   새 worktree에는 추적 중인 파일만 있어요. .env 같은 파일을 .worktreeinclude 파일(gitignore 문법)에 적어 두면 Claude Code가 복사해 줘요.

   .env
   .env.local

4. 머지하고 정리하기

   세션이 끝나면 변경이 없는 worktree는 브랜치와 함께 삭제되고, 변경이 있으면 남길지 물어봐요. 브랜치는 다른 브랜치처럼 머지하세요. 헤드리스 -p 실행은 묻지 않으니 git worktree remove로 직접 지우세요.

5. 또는 데스크톱 앱 쓰기

   Cmd+N(Windows는 Ctrl+N)으로 새 세션을 열고, 시작하기 전에 Worktree를 켜세요. 기본값은 꺼져 있어요. 세션은 분할 화면으로 나란히 띄울 수 있어요.

출처: Anthropic의 worktree 문서(영어)

--bg와 agent view로 쓰는 백그라운드 세션

claude --bg "<prompt>"는 백그라운드에서 세션을 시작하고 바로 돌아오니, 여러 개를 연달아 시작할 수 있어요. 각 세션은 무언가를 수정하기 전에 자기 worktree로 옮겨가요. claude agents로 목록을 보고, claude logs <id>, claude attach <id>, claude stop <id>로 세션 하나를 관리해요.

터미널을 닫아도 계속 실행되지만, 컴퓨터가 꺼지면 멈춰요. Agent view는 리서치 프리뷰예요. 지켜보지 않는 실행에 대해서는 Claude Code 백그라운드 에이전트 실행하는 법을 보세요.

Agent teams: 서로 대화하는 에이전트

Agent teams는 실험적 기능이라 기본적으로 꺼져 있어요. 셸이나 settings.json의 env 블록에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해 켠 다음, 작업에 대해 Claude에게 “팀원 세 명을 만들어 줘”라고 요청하세요. 팀원들은 작업 목록을 공유하고 서로 메시지를 주고받으며, 터미널이나 tmux·iTerm2의 분할 창에 표시돼요.

• 대화형 세션에서만 돼요. -p와 Agent SDK에서는 팀원을 만들지 않아요.
• 세션당 팀은 하나이고 중첩 팀은 안 되며, 프로세스 내 팀원은 /resume으로 복원되지 않아요.
• 팀원들은 체크아웃 하나를 공유하니 각자 다른 파일을 맡기세요.
• 비용이 훨씬 커요. Anthropic 문서에 따르면 팀원이 plan mode로 돌 때 팀은 단일 세션의 약 7배 토큰을 써요.

병렬 에이전트가 서로 덮어쓰지 않게 하기

• 두 에이전트가 같은 파일을 건드릴 수 있다면 각자 worktree를 주세요. worktree 안의 세션은 메인 체크아웃을 수정할 수 없고, 그 서브에이전트도 마찬가지예요.
• Agent team에서는 파일 단위로 일을 나누세요. 두 팀원이 한 파일을 수정하면 서로 덮어써요.
• 모든 서브에이전트와 세션은 같은 사용 한도를 쓰므로, 여러 개를 돌리면 사용량이 몇 배로 늘어요. 간단한 서브에이전트에는 model: haiku를 쓰세요.
• 같은 테스트나 개발 서버를 돌리는 에이전트끼리 포트가 충돌할 수 있으니 각자 다른 포트를 주세요.

병렬 에이전트를 일자리가 있는 팀으로 바꾸세요

worktree와 agent teams는 내가 지켜보는 작업 하나를 나눠요. Crewmark는 여러 Claude Code나 Codex 세션을 각자 직무, 목표, 근무 시간을 가진 직원으로 돌리고, 보드 하나에서 업무를 줘요.

1. 직무마다 직원 한 명

   SEO 전문가, 소프트웨어 엔지니어, UI 디자이너가 각자 자기 대화에서 자기 지침과 목표를 가지고 일해요.

2. 모두를 위한 보드 하나

   가장 잘 맞는 직원에게 이슈를 배정하세요. 각 직원은 하트비트마다 깨어나 다음 이슈를 가져가고 진행하며 댓글을 남기니, 누가 무엇을 하는지 한눈에 보여요.

3. 서로가 아니라 나에게 물어봐요

   검토나 권한이 필요하면 직원이 나에게 메시지를 보내고 다음 일로 넘어가요. AI 직원이란 무엇인지 읽어 보세요.

Claude Code 멀티 에이전트 FAQ