📝 Originally published at forge.workstyle.tech.

여러 코딩 에이전트(Claude Code나 Codex 등)를 테스트하다 보면 다음과 같은 고민에 부딪히게 됩니다. "같은 리포지토리에서 서로 다른 태스크를 동시에 진행하고 싶지만, 작업이 서로 간섭한다", "에이전트 A와 에이전트 B의 결과를 나란히 놓고 비교하고 싶다".

이를 해결하는 것이 바로 git worktree를 사용한 병렬 실행 환경입니다. 이 기사에서는 전용 데스크톱형 ADE(Agent Development Environment)를 예로 들어, 설정부터 병렬 비교, 배포 승인까지의 흐름을 정리합니다. 특정 도구에 의존하지 않는 사고방식을 중심으로 다루므로, 자신의 환경에 맞춰 변형하여 활용할 수 있습니다.

왜 git worktree인가

git worktree는 하나의 리포지토리로부터 **여러 개의 작업 디렉토리(working directory)**를 분리해낼 수 있는 메커니즘입니다. 브랜치마다 독립된 폴더가 준비되므로 다음과 같은 사용이 가능해집니다.

• 태스크 A는 에이전트에게 맡기면서, 태스크 B는 다른 에이전트에게 맡긴다.
• 각각의 변경 사항이 별도의 디렉토리에 격리되므로 파일 충돌이 발생하지 않는다.
• 동일한 과제를 여러 에이전트에게 풀게 하고, diff를 나란히 놓고 품질을 비교한다.

브랜치 전환(git checkout)을 하면 작업 트리(working tree)는 하나뿐이지만, worktree를 사용하면 물리적으로 다른 장소에서 병행 작업할 수 있다는 것이 핵심입니다.

사전에 준비할 것

환경을 구축하기 전에 다음 사항들이 갖춰져 있는지 확인합니다.

• 코딩 에이전트의 CLI(예: Claude Code)와 해당 에이전트의 로그인 인증이 완료된 상태
• git 및 node(프로젝트의 CI에서 사용하는 런타임)
• 에이전트를 통합 관리하는 ADE 앱 본체

에이전트 인증은 홈 디렉토리 설정(예: ~/.claude)에 저장되며, ADE 측에서 이를 자동으로 참조하는 방식이 일반적입니다. 이미 CLI로 로그인되어 있다면, 추가적인 로그인 설정은 필요 없는 경우가 많아 GUI에서 연결하는 것만으로 바로 사용할 수 있습니다.

설정 흐름

1. 앱을 실행하고 초기 권한 부여하기

최초 실행 시 홈 디렉토리에 대한 접근 권한을 요청하면 허용합니다. 기존 설정 임포트를 권장하는 메시지가 뜨면, 필요하지 않을 경우 스킵해도 무방합니다.

2. 리포지토리 추가하기

작업 대상 리포지토리를 등록합니다. 처음부터 운영(production) 리포지토리를 사용하기보다는, 연습용으로 작은 샘플 리포지토리부터 시작하는 것을 추천합니다. 추가하면 git 상태를 읽어와 기본 브랜치(대부분 main)가 기준(base ref)으로 설정됩니다.

3. 워크트리(태스크) 생성하기

태스크 이름을 지정하여 새로운 워크트리를 만듭니다. 이것이 main으로부터 독립된 git worktree가 되어, 다른 태스크와 간섭하지 않는 작업 공간이 됩니다. 태스크 이름은 add-readme-section과 같이 내용을 알 수 있게 설정하면 나중에 추적하기 쉽습니다.

4. 에이전트 할당하기

워크트리마다 사용할 에이전트를 선택합니다. 인증은 앞서 언급한 설정을 자동으로 참조하므로, 로그인되어 있다면 즉시 실행할 수 있습니다.

5. 프롬프트를 입력하여 실행하기

"README에 사용법 섹션을 추가해줘"와 같은 구체적인 지시를 내려 실행합니다.

6. 병렬로 비교하기

이 부분이 병렬 환경의 진정한 가치입니다. 동일한 과제에 대해 단계 3~4를 반복하여 -2, -3과 같이 여러 개의 워크트리를 만들고, 서로 다른 에이전트를 할당합니다. 화면(pane)을 분할하면 각각의 진행 상황을 동시에 모니터링하고 결과를 나란히 비교할 수 있습니다.

리뷰부터 배포까지

각 워크트리의 diff 뷰를 통해 변경 내용을 확인합니다. AI를 이용한 차분 평가(annotation) 기능이 있다면 리뷰의 1차 스크리닝 용도로 사용할 수 있습니다.

좋은 결과가 나왔다면 commit & push를 합니다. 여기서부터는 자동화된 파이프라인(pipeline)에 태우는 것이 정석입니다.

1. PR 생성 — push를 트리거로 풀 리퀘스트(Pull Request)가 생성됨
2. CI 실행 — 테스트(예: node --test)가 자동으로 실행됨
3. 배포 — 운영 환경 반영은 수동 트리거(Run workflow)로 설정하여, **인간의 승인 게이트(approval gate)**를 거침

에이전트가 작성한 코드라 할지라도, CI와 인간의 승인을 거치는 흐름은 바꾸지 않는 것이 안전하게 운영하는 요령입니다. 자동 생성된 코드이기 때문에 더욱이 기계적인 테스트와 사람의 눈이라는 이중 구조를 유지해야 합니다.

주의해야 할 포인트

PATH 문제

가장 흔히 발생하는 트러블은 "에이전트의 CLI를 찾을 수 없음"입니다. 버전 관리 도구(fnm 또는 nvm 등)를 통해 node나 CLI를 설치한 경우, 이들은 셸 프로파일(.zshrc 등)에서 초기화되어야 비로소 PATH에 등록됩니다.

ADE가 실행하는 셸이 이 프로파일을 읽어오지 않으면 명령어를 찾을 수 없습니다. 만약 "명령어를 찾을 수 없습니다"라는 메시지가 나온다면, 셸 프로파일의 초기화 행을 확인하십시오.

인증 중복

여러 계정을 전환하는 경우, 인증 리프레시(refresh)가 중복되지 않도록 방어되어 있는 구현이 많습니다. 기본적으로 홈 디렉터리 설정에 맡겨두면 문제없습니다.

요약

• git worktree를 사용하면 여러 코딩 에이전트를 간섭 없이 병렬 실행할 수 있다
• 동일한 과제를 여러 에이전트에게 풀게 하고, diff를 나란히 배치하여 품질을 비교할 수 있다
• 리뷰는 diff 뷰로 진행하고, 운영 반영은 CI + 인간의 승인 게이트로 보호한다
• 가장 큰 함정은 PATH이다. 버전 관리 도구의 초기화가 셸 프로파일에 포함되어 있는지 확인한다

대부분의 환경에서는 새로 설치할 것이 많지 않으며, 기존의 CLI 인증을 연결하는 것만으로 병렬 에이전트 개발을 시작할 수 있습니다. 우선 연습용 리포지터리에서 동일한 지시를 2~3개의 에이전트에게 던져 비교하는 것부터 시도해 보시기 바랍니다.