클로드 코드 다중 에이전트 병렬 코딩법

파일을 여러 클로드 코드 세션에서 동시에 고치면 변경 내용이 사라지거나 병합 시 충돌이 한꺼번에 발생합니다.

가장 빠른 해법은 조사에는 서브에이전트를 쓰고, 코드 편집에는 세션별 워크트리를 적용하는 것입니다. 여러 작업은 작업 분할, 파일 격리, 자동 테스트, 사람의 최종 병합이라는 네 단계로 관리해야 합니다.

이미 터미널에서 클로드 코드를 사용하는 개발자에게 적합합니다. 기능, 테스트, 문서를 동시에 처리해야 하는 팀 리더와 여러 세션을 원격 맥에서 운영하려는 엔지니어도 대상입니다.

마지막 업데이트: 2026년 8월 13일. 명령, 설정 항목과 정리 동작은 클로드 코드 공식 병렬 작업 문서, 공식 워크트리 문서, 깃 공식 워크트리 문서에서 다시 확인했습니다.

먼저 작업 유형에 따라 실행 방식을 나눕니다

클로드 코드의 병렬 기능은 모두 같은 역할을 하지 않습니다. 서브에이전트는 하나의 대화 안에서 별도 문맥으로 작업을 위임하고 결과 요약을 돌려줍니다. 검색, 로그 분석, 코드베이스 탐색처럼 결과만 필요한 일에 적합합니다.

반면 여러 세션이 실제 파일을 수정한다면 워크트리가 필요합니다. 공식 문서의 비교 기준도 이 구분을 따릅니다. 서브에이전트는 결과 전달에 초점이 있고, 워크트리는 서로 다른 깃 체크아웃에서 파일을 분리하는 데 초점이 있습니다.

에이전트 팀은 여러 클로드 코드 세션이 공용 작업 목록과 메시지로 협력하는 방식입니다. 팀원 간 논의가 필요한 복합 작업에 맞지만, 독립적인 변경에 비해 조정 부담과 토큰 사용량이 커질 수 있습니다. 팀원마다 같은 파일을 만지는 구조라면 에이전트 팀만으로 충돌이 해결되지는 않습니다. 자세한 차이는 공식 에이전트 팀 문서에서 확인할 수 있습니다.

작업 상황	우선 선택	파일 격리	결과 전달 방식	주의할 점
검색, 로그 분석, 구조 파악	서브에이전트	기본적으로 별도 문맥	상위 대화에 요약	출력 형식을 미리 지정
기능을 여러 세션에서 수정	워크트리 세션	별도 체크아웃과 브랜치	커밋 또는 패치	병합 순서 관리
여러 작업의 조정과 논의	에이전트 팀	팀원이 같은 영역을 피하도록 설계	작업 목록과 메시지	실험 기능과 비용 부담 확인
한 세션에서 백그라운드 작업 감시	에이전트 보기	편집 작업은 워크트리 사용	상태 화면에서 확인	로컬 기기 절전의 영향

파일 충돌을 막는 격리 규칙을 먼저 만듭니다

여러 터미널이 같은 폴더에서 실행되면 한 세션이 저장한 파일을 다른 세션이 곧바로 덮어쓸 수 있습니다. 작업이 끝난 뒤 깃 차이만 확인하는 방식으로는 이미 사라진 변경을 복구하기 어렵습니다.

클로드 코드에서는 다음처럼 세션마다 이름을 달리해 워크트리를 시작할 수 있습니다.

claude --worktree feature-auth
claude --worktree test-auth
claude --worktree docs-auth

각 세션은 기본적으로 저장소 안의 별도 워크트리와 새 브랜치에서 시작합니다. 워크트리는 파일을 분리하지만 깃 기록을 공유합니다. 따라서 “파일이 격리되었으니 병합도 자동으로 안전하다”라고 생각하면 안 됩니다. 브랜치 이름, 담당 파일, 병합 담당자를 작업표에 남겨야 합니다.

깃 자체에서도 다음 명령으로 상태를 확인할 수 있습니다.

git worktree list
git worktree remove 경로
git worktree prune

클로드 코드 공식 문서는 워크트리 폴더를 저장소에 추적하지 않도록 설정하고, 종료 뒤 남은 워크트리를 직접 정리하는 절차도 안내합니다. 특히 비대화형 실행에서는 자동 정리가 기대와 다를 수 있으므로 종료 후 목록을 확인해야 합니다.

주의: 워크트리는 추적되지 않는 .env 파일을 자동으로 그대로 복사하지 않습니다. 필요한 파일만 포함 규칙으로 지정하고, 비밀값은 저장소에 커밋하지 않는 초기화 절차를 별도로 마련해야 합니다.

서브에이전트에는 읽을 범위와 반환 형식을 고정합니다

주 대화의 문맥이 검색 결과, 긴 로그와 파일 내용으로 가득 차면 정작 구현 판단에 필요한 정보가 묻힙니다. 이때 서브에이전트를 사용하면 조사 작업을 별도 문맥으로 분리할 수 있습니다. 서브에이전트는 부모 대화의 전체 기록을 그대로 물려받지 않으므로, 필요한 범위와 규칙을 명시해야 합니다. 이 동작은 공식 서브에이전트 문서에서 확인할 수 있습니다.

좋지 않은 지시는 다음과 같습니다.

저장소를 전부 살펴보고 인증 기능을 구현해 주세요.

이렇게 쓰면 에이전트가 전체 저장소를 반복해서 읽고, 결과도 장황하게 반환할 가능성이 큽니다. 다음처럼 목표와 반환 형식을 함께 지정하는 편이 낫습니다.

인증 모듈의 토큰 만료 처리만 조사하세요.
반환 형식은 다음 네 항목으로 제한하세요.
1. 관련 파일
2. 현재 동작
3. 실패 가능성이 있는 테스트
4. 구현 에이전트가 따라야 할 제안
코드 수정은 하지 마세요.

검색, 로그 분석, 의존성 확인은 읽기 전용 에이전트에 맡기고, 실제 수정 에이전트에는 요약된 결과만 전달합니다. 이렇게 하면 주 세션이 같은 파일을 여러 차례 읽는 일을 줄이고, 구현 에이전트가 조사와 코딩을 뒤섞는 문제도 줄어듭니다.

숨은 의존성을 작업표에서 제거합니다

표면적으로는 기능, 테스트, 문서가 서로 다른 작업처럼 보이지만 실제로는 같은 파일이나 생성물에 의존할 수 있습니다. 병렬 실행 전에 다음 항목을 표시해야 합니다.

• 여러 작업이 함께 참조하는 공개 인터페이스
• 데이터베이스 이전 파일과 초기화 스크립트
• 의존성 잠금 파일
• 자동 생성되는 코드와 스키마
• 공용 설정 파일과 빌드 설정
• 동일한 테스트 픽스처와 목 파일

공유 인터페이스를 먼저 확정해야 하는 작업이라면 인터페이스 담당 에이전트를 단일 소유자로 지정합니다. 다른 에이전트는 그 결과를 소비하되 같은 파일을 수정하지 않습니다. 잠금 파일이나 생성 코드도 같은 원칙을 적용해야 합니다.

예를 들어 인증 기능과 결제 기능이 모두 사용자 모델을 수정한다면 두 에이전트를 무작정 동시에 실행하면 안 됩니다. 사용자 모델의 변경안을 먼저 확정하고, 그 이후 인증과 결제의 구현을 병렬로 나누는 방식이 안전합니다.

다음 조건에 해당하면 병렬 실행보다 순차 실행으로 되돌리는 편이 낫습니다.

• 두 작업이 같은 핵심 파일을 수정합니다.
• 한 작업의 출력이 다른 작업의 입력이 됩니다.
• 데이터베이스 이전 순서가 결과를 좌우합니다.
• 공용 인터페이스가 아직 확정되지 않았습니다.

실행 환경을 워크트리마다 재현합니다

새 워크트리는 깨끗한 체크아웃이므로 의존성이나 가상 환경이 준비되어 있지 않을 수 있습니다. 한 세션에서만 설치한 패키지를 다른 세션도 사용할 것이라고 가정하면, 에이전트별로 서로 다른 상태에서 테스트하게 됩니다.

각 워크트리에서 다음 순서를 반복 가능한 명령으로 만들면 좋습니다.

git status
프로젝트별 의존성 설치 명령
환경 변수 검사 명령
정적 분석 명령
단위 테스트 명령

환경 변수는 비밀 저장소나 실행 환경에서 주입합니다. .worktreeinclude를 사용할 때도 복사 대상은 추적되지 않는 파일로 제한해야 합니다. 프로젝트가 원격 맥에서 실행된다면 초기화 스크립트에 개발 도구, 패키지 관리자, 런타임 버전 확인, 테스트 명령을 포함하는 것이 안전합니다.

로컬 환경에서 발생하는 절전, 메모리 경쟁, 터미널 종료도 확인해야 합니다. 백그라운드 세션은 기기가 잠자기나 종료 상태가 되면 영향을 받을 수 있으며, 공식 에이전트 보기 문서도 세션이 로컬 환경에서 실행된다는 제한을 안내합니다. 장시간 작업이라면 세션 상태와 기기 전원 정책을 함께 점검해야 합니다.

완료 선언 대신 공통 검증 결과를 받습니다

에이전트가 “완료했습니다”라고 말하는 것만으로는 인수 조건을 충족했다고 볼 수 없습니다. 모든 작업은 다음 네 가지를 반환하도록 고정하는 편이 좋습니다.

1. 변경 파일과 커밋
2. 실행한 테스트와 결과
3. 아직 남은 제한 사항
4. 문제가 생겼을 때 되돌리는 방법

주 세션이나 별도의 검토 에이전트는 같은 기준으로 정적 분석, 단위 테스트, 통합 테스트와 빌드를 실행해야 합니다. 에이전트가 자신의 변경만 검사하면 다른 브랜치의 변경과 결합했을 때 생기는 문제를 놓칠 수 있습니다.

특히 생성 코드와 잠금 파일이 바뀐 경우에는 변경 이유를 기록해야 합니다. 이유가 불분명한 대규모 변경은 병합 전에 중단하고, 필요한 파일만 다시 생성하도록 지시해야 합니다.

병합은 의존성 순서와 승인 지점으로 통제합니다

병합은 모든 브랜치를 한 번에 합치는 작업이 아닙니다. 먼저 공용 인터페이스나 이전 파일처럼 다른 작업의 기반이 되는 변경을 병합합니다. 그 다음 독립 기능, 테스트, 문서 순서로 진행하고, 매번 전체 검증을 실행합니다.

두 에이전트가 같은 기능의 대체 구현을 제출했다면 두 결과를 억지로 합치지 않아야 합니다. 성능, 테스트 통과, 유지보수성, 변경 범위를 기준으로 하나를 선택하고 나머지는 폐기하는 편이 안전합니다.

병합 전에는 다음 확인표를 통과시킵니다.

• [ ] 브랜치가 최신 기준 브랜치에서 시작했는지 확인했습니다.
• [ ] 담당 파일과 공용 파일을 구분했습니다.
• [ ] 테스트 명령과 결과를 기록했습니다.
• [ ] 환경 변수와 비밀값이 커밋되지 않았습니다.
• [ ] 생성 코드와 잠금 파일의 변경 이유를 확인했습니다.
• [ ] 병합 후 다시 실행할 검증 명령을 정했습니다.
• [ ] 실패 시 되돌릴 커밋이나 브랜치를 보존했습니다.

상황별 선택 조건을 적용합니다

다음 조건으로 실행 방식을 고르면 불필요한 병렬화를 줄일 수 있습니다.

• 조사 결과만 필요하면 서브에이전트를 선택합니다. 파일 수정이 발생하면 워크트리를 추가합니다.
• 여러 세션이 서로 다른 파일만 수정하면 워크트리 기반 병렬 세션을 선택합니다. 공용 파일이 있으면 담당자를 한 명으로 제한합니다.
• 에이전트끼리 직접 논의하고 작업 목록을 공유해야 하면 에이전트 팀을 선택합니다. 단순한 기능 분할이면 서브에이전트로 되돌립니다.
• 한 작업이 다른 작업의 출력에 의존하면 먼저 순차 실행합니다. 인터페이스와 생성물을 확정한 뒤 병렬화를 재개합니다.
• 장시간 여러 세션을 유지해야 하지만 로컬 맥이 절전이나 자원 경쟁을 일으키면 원격 맥을 검토합니다. 짧은 작업이나 물리 장치가 필요한 작업은 로컬 환경이 더 적합할 수 있습니다.
• 세션 수가 늘어날수록 토큰 사용과 테스트 시간이 함께 커지므로 각 작업에 중지 조건, 최대 재시도 횟수와 사람의 승인 지점을 지정합니다.

병렬 코딩의 핵심은 에이전트를 많이 띄우는 것이 아닙니다. 어떤 작업을 분리할 수 있고, 어떤 파일을 한 명만 소유해야 하며, 어느 시점에 사람이 병합을 승인할지를 미리 정하는 데 있습니다. 클로드 코드의 병렬 기능을 처음 도입하는 팀이라면 작은 기능 하나로 워크트리 생성부터 병합 후 테스트까지 검증한 뒤 범위를 넓히는 편이 좋습니다.

자주 묻는 운영 판단

메인 맥에서 여러 세션을 실행하는 방식은 설정이 빠르지만, 절전과 자원 경쟁, 의존성 설치 차이, 장시간 빌드 중단이라는 한계가 있습니다. 반대로 원격 맥은 세션을 분리해 유지하기 쉽지만 인증, 비용, 초기화와 정리 절차를 관리해야 합니다.

클로드 코드 다중 에이전트를 일시적으로 사용한다면 현재 장비에서 먼저 워크트리와 테스트 절차를 검증하는 것이 합리적입니다. 매일 반복되는 빌드와 장시간 세션이 필요하다면 원격 맥 운영 도움말과 맥 미니 대여 환경을 비교해 실제 세션 수와 사용 시간에 맞춰 판단해야 합니다.

기존 로컬 방식은 작업 중인 맥의 절전 상태에 영향을 받고, 여러 워크트리의 의존성을 따로 맞춰야 하며, 빌드와 테스트가 같은 자원을 놓고 경쟁할 수 있습니다. 반면 Zutcloud의 원격 맥 방식은 임시 개발 환경을 분리해 쓰는 선택지가 될 수 있습니다. 다만 장기간 고정된 고부하 작업이나 물리 장치 연결이 핵심인 프로젝트라면 직접 보유한 맥이 더 적합할 수 있으므로, 계획한 세션 수와 온라인 시간을 먼저 계산한 뒤 필요한 기간만 원격 맥을 검토하는 것이 안전합니다.

FAQ

클로드 코드에서 여러 에이전트를 동시에 시작하려면 어떻게 해야 하나요?

조사나 로그 분석처럼 결과만 필요한 작업은 하나의 대화에서 서브에이전트로 나누는 편이 적합합니다. 여러 세션을 직접 운영하려면 각 터미널에서 서로 다른 워크트리 이름을 지정해 시작합니다. 팀 단위 조정이 필요하면 에이전트 팀을 검토할 수 있지만 실험 기능이고 토큰 사용량과 조정 부담이 커질 수 있습니다.

서브에이전트와 워크트리는 어떤 차이가 있나요?

서브에이전트는 대화의 문맥을 분리해 조사나 검토 결과를 상위 대화로 돌려주는 실행 단위입니다. 워크트리는 파일을 별도 체크아웃으로 분리하는 깃 기능입니다. 따라서 서브에이전트는 문맥 격리이고 워크트리는 파일 격리입니다. 코드를 동시에 수정한다면 두 기능을 함께 쓰는 편이 안전합니다.

클로드 코드 다중 세션에서 파일 충돌을 피하는 방법은 무엇인가요?

각 세션을 서로 다른 브랜치와 워크트리에서 실행하고, 공통 인터페이스나 잠금 파일은 한 에이전트만 수정하게 해야 합니다. 작업 시작 전에 변경 파일 목록과 생성물을 선언하면 충돌 가능성이 낮아집니다. 병합은 의존성이 적은 변경부터 하나씩 진행하고, 매번 테스트를 다시 실행해야 합니다.

클로드 코드 에이전트가 서로 다른 브랜치에서 병렬 작업할 수 있나요?

가능합니다. 클로드 코드의 워크트리 실행은 별도 체크아웃과 브랜치를 만들어 여러 세션이 같은 저장소에서 동시에 작업하도록 돕습니다. 다만 저장소의 기록 자체는 공유하므로 브랜치 전략과 병합 규칙이 필요합니다. 워크트리를 삭제하기 전에 커밋이나 패치가 보존되었는지 반드시 확인해야 합니다.

원격으로 여러 클로드 코드 세션을 실행하려면 어떤 환경이 필요한가요?

원격 맥에는 깃 저장소, 클로드 코드 실행 환경, 프로젝트 의존성, 인증 정보와 테스트 도구가 준비되어야 합니다. 비밀값은 저장소에 직접 기록하지 말고 안전한 환경 변수나 초기화 절차로 주입해야 합니다. 또한 기기가 잠자기 상태로 전환되지 않는지, 세션 종료 후 워크트리가 정리되는지도 확인해야 합니다.

더 읽기

• 병렬 에이전트 작업을 위한 파일 격리와 안전한 작업 공간 설계
• 여러 프로젝트에서 에이전트 기억과 작업 규칙을 나누는 방법