AI 코딩 에이전트는 Git 워크트리로 써야 충돌이 사라진다

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

AI 코딩 에이전트 두 개에게 각각 기능 개발과 버그 수정을 맡겼는데, 마지막에 파일이 뒤엉켜 한쪽 작업을 버린 적이 있으신가요? 문제는 에이전트의 코딩 실력보다 여러 작업이 같은 폴더와 브랜치를 공유하는 방식에 있을 가능성이 큽니다.

이때 의외로 유용한 도구가 Git의 워크트리(worktree)입니다. 저장소를 여러 번 복제하지 않고도 브랜치마다 독립된 작업 폴더를 만들 수 있어, AI 코딩 에이전트의 병렬 작업과 검토 과정을 훨씬 안전하게 분리합니다.

에이전트마다 작업 폴더를 하나씩 주면 수정 충돌이 줄어듭니다

브랜치만 나누고 폴더를 공유하면 충분하지 않습니다

사람이 직접 개발할 때는 한 폴더에서 브랜치를 바꿔 가며 작업해도 큰 불편이 없습니다. 그러나 여러 AI 코딩 에이전트를 동시에 실행하면 상황이 달라집니다. 한 에이전트가 의존성을 설치하거나 파일을 생성하는 동안 다른 에이전트가 브랜치를 전환하면, 아직 커밋하지 않은 변경과 빌드 결과물이 예상하지 못한 위치에 남을 수 있습니다.

Git 워크트리를 사용하면 하나의 저장소 이력을 공유하면서도 실제 작업 디렉터리는 분리됩니다. 예를 들어 첫 번째 에이전트는 로그인 오류를 고치고, 두 번째 에이전트는 결제 테스트를 추가하며, 세 번째 에이전트는 문서를 갱신하게 만들 수 있습니다. 각자 다른 브랜치와 폴더에서 움직이므로 같은 파일을 덮어쓰는 사고와 무심코 브랜치를 바꾸는 실수가 크게 줄어듭니다.

기본 저장소가 codeflow라면 아래처럼 형제 디렉터리에 작업 공간을 만들 수 있습니다. 브랜치가 아직 없다면 -b 옵션으로 생성하고, 이미 있는 브랜치라면 옵션 없이 연결합니다. 폴더 이름에 작업 목적을 넣어 두면 터미널 탭이 많아져도 대상을 빠르게 구분할 수 있습니다.

• git worktree add -b fix/login-timeout ../codeflow-login main — 로그인 오류 전용 폴더와 브랜치를 만듭니다.
• git worktree add -b test/payment-webhook ../codeflow-payment main — 결제 웹훅 테스트를 격리합니다.
• git worktree list — 연결된 폴더, 커밋, 브랜치 상태를 한 번에 확인합니다.
• git worktree remove ../codeflow-login — 작업이 끝난 폴더의 연결을 안전하게 해제합니다.

숨은 팁: 워크트리를 현재 저장소 내부가 아니라 형제 디렉터리에 두세요. 에이전트가 전체 프로젝트를 검색할 때 다른 워크트리의 파일까지 읽어 중복 분석하는 일을 피할 수 있습니다.

작업 단위는 기능보다 충돌 가능성으로 나누는 편이 낫습니다

에이전트 업무를 단순히 ‘프런트엔드’와 ‘백엔드’로 나누면 공용 타입, API 명세, 환경 설정 파일에서 다시 충돌할 수 있습니다. 더 실용적인 기준은 수정 파일의 겹침 여부입니다. 두 작업이 같은 스키마나 잠금 파일을 수정한다면 동시에 진행하지 말고, 선행 작업을 먼저 병합한 뒤 다음 워크트리를 최신 기준으로 갱신하는 편이 빠릅니다.

특히 package-lock.json, 데이터베이스 마이그레이션, 라우팅 테이블처럼 자동 생성되거나 순서가 중요한 파일은 한 에이전트에게만 소유권을 주는 것이 좋습니다. 코드 생성량보다 병합 시간을 줄이는 것이 실제 개발 속도에 더 큰 영향을 미칩니다. AI 도구가 많아져도 팀의 결정이 느려질 수 있다는 협업 플랫폼 관련 기사처럼, 도구의 수보다 작업 경계를 정하는 방식이 생산성을 좌우합니다.

1. 예상 수정 파일을 에이전트에게 먼저 나열하게 합니다.
2. 두 작업의 파일 목록이 겹치면 공용 파일 담당자를 한 명으로 지정합니다.
3. 독립성이 높은 작업만 별도 워크트리에서 동시에 시작합니다.
4. 선행 브랜치가 병합되면 나머지 브랜치를 리베이스하거나 최신 기준 브랜치와 동기화합니다.

복제 비용은 줄이고 실행 환경은 더 꼼꼼히 분리해야 합니다

Git 데이터는 공유해도 캐시와 포트까지 공유할 필요는 없습니다

워크트리는 일반적인 git clone을 여러 번 수행하는 것보다 효율적입니다. 객체 데이터와 저장소 이력을 공유하므로 큰 프로젝트에서도 작업 공간을 비교적 빠르게 추가할 수 있습니다. 다만 소스 폴더가 분리되었다고 해서 실행 환경까지 자동으로 격리되는 것은 아닙니다. 같은 개발 서버 포트, 데이터베이스, 임시 파일 경로를 사용하면 에이전트끼리 여전히 간섭합니다.

예를 들어 두 워크트리에서 모두 개발 서버를 3000번 포트로 실행하면 나중에 시작한 프로세스가 실패합니다. 테스트 데이터베이스도 하나를 공유하면 한쪽 테스트의 데이터 삭제가 다른 쪽 결과에 영향을 줍니다. 따라서 폴더, 브랜치, 포트, 테스트 데이터를 하나의 세트로 관리해야 비로소 독립적인 AI 코딩 환경이 됩니다.

비용 측면에서도 작은 요령이 있습니다. 프로젝트에 따라 모든 워크트리에서 의존성을 새로 설치하면 디스크 사용량과 설치 시간이 커집니다. 패키지 관리자의 전역 캐시나 콘텐츠 주소 기반 저장소는 공유하되, 프로젝트 내부의 빌드 결과와 실행 상태는 분리하세요. 심볼릭 링크로 전체 의존성 폴더를 억지로 공유하면 한 작업의 패키지 변경이 다른 작업에 즉시 반영될 수 있으므로 주의해야 합니다.

• 포트: 로그인 작업은 3101, 결제 작업은 3102처럼 워크트리별 번호를 정합니다.
• 데이터베이스: 스키마 또는 데이터베이스 이름 뒤에 브랜치 식별자를 붙입니다.
• 캐시: 다운로드 캐시는 공유해도 빌드 캐시와 테스트 결과 폴더는 따로 둡니다.
• 컨테이너: Compose 프로젝트 이름을 다르게 지정해 네트워크와 볼륨 충돌을 막습니다.
• 로그: 워크트리 이름이 들어간 로그 경로를 사용해 어느 에이전트의 실행인지 남깁니다.

생활 해킹: 포트 번호를 매번 기억하지 말고 워크트리 폴더명에서 짧은 숫자를 정해 .env.local에 기록하세요. 터미널 제목에도 같은 식별자를 넣으면 잘못된 서버를 종료하는 실수가 줄어듭니다.

환경 변수 파일은 복사보다 템플릿 생성이 안전합니다

새 워크트리를 만들었는데 애플리케이션이 실행되지 않는 가장 흔한 이유는 Git에서 제외된 환경 변수 파일이 없기 때문입니다. 그렇다고 기본 폴더의 .env를 그대로 복사하면 운영 키나 개인 토큰이 여러 디렉터리에 흩어집니다. 에이전트가 파일 전체를 읽거나 로그에 출력할 가능성도 커집니다.

대신 .env.example에는 변수 이름과 안전한 로컬 기본값만 두고, 비밀값은 비밀 관리 도구나 세션 단위 주입 방식으로 전달하는 편이 좋습니다. 코드 보안의 기본 개념은 지식백과의 코드 보안 설명도 함께 참고할 수 있습니다. 워크트리는 충돌을 줄여 주는 기능이지, 민감정보까지 자동으로 보호하는 보안 경계는 아닙니다.

1. 추적 가능한 .env.example에 필요한 변수 목록을 유지합니다.
2. 워크트리 생성 직후 로컬 전용 설정 파일을 템플릿에서 생성합니다.
3. 실제 비밀값은 필요한 명령을 실행하는 동안에만 주입합니다.
4. 에이전트에게 설정 파일 원문을 출력하지 말라는 작업 규칙을 전달합니다.
5. 커밋 전 git status와 비밀정보 탐지 결과를 함께 확인합니다.

워크트리를 늘리기만 하면 오히려 검토 순서가 무너집니다

작업 종료 조건과 병합 순서를 먼저 적어 두세요

워크트리를 몇 초 만에 만들 수 있다는 점 때문에 작업 공간을 지나치게 늘리는 실수가 생깁니다. 에이전트 다섯 개가 모두 코드를 작성해도 사람이 검토할 수 있는 변경은 한정적입니다. 오래된 기준 브랜치에서 만든 결과가 쌓이면 나중에는 작은 수정 하나를 병합하기 위해 여러 충돌을 해결해야 합니다.

실제로는 ‘에이전트 수’보다 검토 가능한 동시 변경 수를 기준으로 제한하는 편이 좋습니다. 한 사람이 검토한다면 활발한 코드 작업은 두세 개 정도로 두고, 나머지는 조사나 테스트 설계처럼 파일 변경이 적은 업무로 배치할 수 있습니다. 각 워크트리에는 성공 조건, 실행할 테스트, 수정 금지 파일을 짧은 작업 메모로 남겨 두세요.

병합은 기반 변경부터 진행합니다. 예컨대 타입 정의를 바꾸는 브랜치를 먼저 병합하고, 그 타입을 사용하는 화면과 테스트 브랜치를 차례로 갱신합니다. 서로 의존하는 변경을 동시에 독립 작업처럼 취급하면 에이전트가 같은 문제를 각기 다른 방식으로 해결해 코드 일관성이 깨집니다.

• 브랜치마다 하나의 명확한 목적만 둡니다.
• 커밋 전 테스트 명령과 기대 결과를 작업 지시에 포함합니다.
• 공용 타입이나 스키마 변경 브랜치를 가장 먼저 검토합니다.
• 병합 직전 에이전트가 변경 파일과 위험 요소를 요약하게 합니다.
• 완료된 워크트리는 상태를 확인한 뒤 제거해 작업 목록을 가볍게 유지합니다.

강제 삭제, 오래된 기준점, 커밋 없는 이동이 사고를 만듭니다

첫 번째 흔한 실수는 변경이 남은 워크트리를 정리하려고 강제 삭제부터 시도하는 것입니다. 먼저 해당 폴더에서 git status를 확인하고, 필요한 변경은 커밋하거나 패치로 보관해야 합니다. 폴더를 파일 탐색기에서 직접 지웠다면 Git의 연결 정보가 남을 수 있으므로 git worktree prune으로 사라진 작업 폴더의 메타데이터를 정리합니다.

두 번째 실수는 며칠 전에 만든 워크트리에서 그대로 작업을 계속하는 것입니다. 그동안 기본 브랜치의 API나 타입이 바뀌었다면 에이전트가 이미 폐기된 구조를 기준으로 코드를 만들 수 있습니다. 작업을 재개할 때는 기준 브랜치의 변경을 확인하고, 테스트를 다시 실행한 뒤 수정에 들어가야 합니다. 소스 보호 관점의 추가 배경은 코드 보안 요약 자료에서 살펴볼 수 있습니다.

세 번째 실수는 에이전트에게 ‘이 폴더에서 알아서 고쳐 달라’고만 지시하는 것입니다. 현재 브랜치, 수정 허용 범위, 실행 가능한 명령, 완료 기준이 없으면 다른 워크트리의 변경을 다시 구현하거나 설정 파일까지 손댈 수 있습니다. 작업 폴더가 분리되었다는 사실만으로 작업 의도까지 분리되지는 않습니다. 마지막으로 에이전트가 남긴 변경 파일, 테스트 결과, 미해결 위험을 받아 적은 뒤 워크트리를 닫아야 다음 작업자가 안전하게 이어받을 수 있습니다.

1. 강제 제거부터 하지 않기: 미커밋 변경과 새 파일을 먼저 확인합니다.
2. 오래된 브랜치로 바로 재개하지 않기: 최신 기준점과 차이를 점검합니다.
3. 폴더만 던져 주지 않기: 허용 파일과 완료 조건을 명시합니다.
4. 병합 후 방치하지 않기: 불필요한 워크트리와 로컬 브랜치를 정돈합니다.