Claude Code 상세 사용법 10: 병렬 에이전트와 워크트리 운영법 | DAKER 커뮤니티

Claude Code 상세 사용법 10: 병렬 에이전트와 워크트리 운영법

Claude Code에서 병렬 작업은 "여러 창을 많이 띄우기"가 아니다. 공식 문서는 subagents, agent view, agent teams, worktrees, /batch를 서로 다른 병렬화 방식으로 구분한다. 핵심 판단 기준은 파일 충돌 가능성, 사람이 계속 대화할 필요, 그리고 결과를 PR이나 테스트로 검증할 수 있는지다.

1. subagent는 메인 대화를 더럽히지 않을 때 쓴다

한 세션 안에서 "이 패키지가 어디서 쓰이는지 조사해", "마이그레이션 영향 파일을 찾아" 같은 보조 조사를 맡길 때 subagent가 맞다. 로그, 검색 결과, 파일 목록이 메인 대화를 압도할 때 특히 좋다. 단, 실제 수정을 맡길 때는 소유 파일과 검증 명령을 좁게 준다.

Investigate how authentication errors flow through this repo.
Return only the key files, risky paths, and recommended test commands.
Do not edit files.

2. agent view는 독립 작업 대시보드다

여러 작업을 background로 던지고 상태만 보고 싶으면 claude agents를 연다. 공식 문서 기준 research preview이며, 버전 확인은 claude --version으로 한다.

claude agents

입력창에 prompt를 넣고 Enter를 누르면 새 background session이 하나 생긴다. 다른 prompt를 또 넣으면 같은 대화의 follow-up이 아니라 두 번째 session이 시작된다. 따라서 prompt마다 "범위, 성공 기준, 멈출 조건"을 반복해서 써야 한다.

3. peek와 attach를 구분한다

agent view에서 Space는 peek다. 최근 출력, 질문, PR 정보를 짧게 보고 답할 수 있다. Enter나 오른쪽 화살표는 attach다. 전체 세션에 들어가서 일반 Claude Code처럼 명령, slash command, 코드 리뷰를 이어간다. 나올 때는 빈 prompt에서 왼쪽 화살표를 눌러 다시 background로 보낸다.

운영 패턴은 단순하다.

1. 세션 3개를 각각 독립 작업으로 dispatch
2. 20분 뒤 Needs input과 Ready for review만 확인
3. 막힌 세션은 peek에서 짧게 답변
4. PR이 생긴 세션만 attach해서 diff와 테스트 로그 확인
5. 오래된 세션은 /stop으로 닫기

4. 같은 파일을 만지면 worktree로 격리한다

병렬 AI 코딩의 흔한 실패는 두 agent가 같은 파일을 다른 방향으로 고치는 것이다. 이때는 git worktree를 쓴다. agent view는 편집이 필요할 때 각 session을 자체 worktree로 옮길 수 있다고 문서화돼 있지만, 사람이 직접 여러 Claude 세션을 돌릴 때도 worktree가 가장 단순한 충돌 방지책이다.

git worktree add ../app-auth-hardening -b cc/auth-hardening
git worktree add ../app-billing-tests -b cc/billing-tests

각 worktree에서 다른 Claude Code session을 열고, 끝나면 branch별 PR로 비교한다. 공통 파일을 바꾸는 refactor는 한 session이 owner가 되고 나머지는 read-only 조사로 제한하는 편이 안전하다.

5. 큰 일은 `/batch`를 바로 누르지 말고 먼저 쪼갠다

공식 문서의 /batch는 큰 변경을 5-30개의 worktree-isolated subagent 작업과 PR로 나누는 흐름이다. repo-wide migration처럼 경계가 분명한 작업에 맞다. 반대로 요구사항이 흔들리거나 제품 판단이 필요한 작업은 batch 전에 plan을 먼저 만든다.

Senior takeaway: Claude Code 병렬화는 속도가 아니라 merge 품질 문제다. agentic coding을 잘 쓰는 팀은 작업을 작게 나누고, worktree로 충돌을 줄이고, 마지막에는 사람이 코드 리뷰와 테스트 자동화 증거로 합친다. 이 규율이 있어야 클로드 코드가 개발 생산성을 실제로 올린다.