여러 AI 코딩 에이전트가 같은 프로젝트의 파일을 동시에 수정한다면, 각 작업에 별도 Git worktree를 주고 변경을 검토한 뒤 합치는 방법이 유용합니다. worktree는 같은 저장소에 연결된 독립 작업 폴더입니다. 파일 수정의 간섭을 줄이지만 보안 격리나 병합 충돌 방지를 보장하지는 않습니다.
Git worktree는 무엇을 나누고 무엇을 공유할까?
일반적인 저장소에서는 하나의 작업 폴더에서 파일을 고칩니다. Git worktree를 사용하면 같은 저장소에 연결된 작업 폴더를 여러 개 둘 수 있습니다. 각 폴더는 자체 작업 파일과 체크아웃 상태를 가지면서 Git 객체와 대부분의 참조 등 저장소 데이터를 공유합니다. 구체적인 동작은 Git 공식 문서를 참고하세요.
예를 들어 한 에이전트가 화면을 만들고 다른 에이전트가 API를 개선한다면 서로 다른 브랜치와 폴더를 배정할 수 있습니다. 한쪽이 파일을 수정하는 동안 다른 쪽의 작업 파일이 즉시 바뀌지는 않습니다. 다만 같은 기능이나 파일을 각자 변경했다면 마지막에 합칠 때 충돌하거나 기능상 불일치가 생길 수 있습니다.
| 비교 항목 | 같은 작업 폴더 | 별도 worktree |
|---|---|---|
| 파일 수정 | 동시 변경이 서로의 작업에 바로 영향을 줄 수 있음 | 작업 파일이 분리되어 직접 간섭이 줄어듦 |
| 저장소 데이터 | 동일 저장소 사용 | Git 저장소의 객체와 대부분의 참조를 공유 |
| 결과 통합 | 작업 경계가 섞이기 쉬움 | 브랜치별 차이를 검토하고 통합 가능 |
| 보안 | 실행 권한에 따름 | 별도 보안 샌드박스가 아님 |
작업을 나누는 기준은 폴더보다 책임이다
worktree를 여러 개 만든다고 해서 병렬 작업이 자동으로 효율적이 되지는 않습니다. 먼저 각 작업의 목표, 수정 범위와 다른 작업이 기대하는 결과를 정하세요. 예를 들어 화면과 API를 나눈다면 응답 형식과 오류 처리 방식부터 맞추는 편이 좋습니다.
가상의 쇼핑몰 프로젝트라면 화면 에이전트에는 상품 목록 컴포넌트, API 에이전트에는 상품 조회 API를 맡길 수 있습니다. 두 에이전트 모두 같은 상품 데이터 형식을 참조하게 하고, 완료 기준에 각자의 테스트와 통합 테스트를 명시합니다. 이 구성은 설명을 위한 예시이며 특정 제품의 실측 결과가 아닙니다.
복잡한 협업에서 역할 분담과 검토 흐름은 멀티 에이전트 협업 사례도 함께 볼 수 있습니다.
시작과 통합은 어떻게 진행할까?
1. 현재 작업과 기준점을 확인한다
시작하기 전 git status로 기존 수정사항을 확인하고 보존하세요. worktree를 새로 만든다고 기존 폴더의 미커밋 파일이 새 폴더에 자동으로 복사되지는 않습니다. 어떤 커밋을 기준으로 작업할지 결정하고 작업별 브랜치 이름과 폴더 경로가 이미 사용 중인지 확인합니다.
2. 작업별 폴더와 브랜치를 만든다
아래는 저장소 루트에서 실행하는 예시입니다. 경로와 브랜치 이름은 실제 환경에 맞게 변경하세요.
git worktree add -b feature/catalog-ui ../catalog-ui HEAD
git worktree add -b feature/catalog-api ../catalog-api HEAD
git worktree list
각 폴더에서 별도로 에이전트를 실행하고 담당 범위를 명시합니다. Git은 기본적으로 같은 브랜치를 여러 worktree에 동시에 체크아웃하는 것을 제한하므로 작업마다 별도 브랜치를 사용하는 편이 안전합니다. 이 예시는 새 브랜치를 만드는 명령이므로 이미 같은 이름의 브랜치가 있다면 그대로 실행하지 마세요.
3. 각 결과를 검토하고 순서대로 합친다
에이전트별로 변경 파일, 테스트 결과, 알려진 한계를 기록하게 합니다. 이후 사람이 git diff와 테스트 결과를 확인하고 프로젝트의 병합 절차에 따라 하나씩 통합합니다. 두 작업이 각각 성공해도 함께 동작한다는 뜻은 아니므로, 통합 후에는 계약과 실제 동작을 다시 검증해야 합니다.
작업이 끝난 폴더는 보존할 변경과 브랜치를 먼저 확인한 뒤 Git의 worktree remove 절차로 정리합니다. 미커밋 변경이 있을 수 있으므로 무조건 삭제하는 명령을 자동화하지 않는 것이 좋습니다. 구체적인 옵션과 제한은 Git 공식 문서에서 확인하세요.
worktree로 해결되지 않는 위험
공유 자원: 분리된 폴더에서도 같은 데이터베이스, 개발 서버 포트, 원격 서비스, 환경 변수나 자격증명에 접근할 수 있습니다. 테스트 데이터와 포트를 작업별로 분리하고 외부 변경 권한은 별도로 제한해야 합니다.
보안 경계: 에이전트가 운영체제 권한을 가진 채 실행된다면 다른 파일이나 네트워크에 접근할 수 있습니다. worktree는 파일 정리 도구이지 보안 샌드박스가 아닙니다. 실행 권한과 위험한 명령의 통제는 AI 에이전트 로컬 권한 관리에서 이어서 다룹니다.
통합 비용: 수정 범위가 넓거나 서로 의존하는 작업이라면 나중에 병합하고 검증하는 비용이 병렬화의 이익을 넘을 수 있습니다. 시작 전 공통 인터페이스를 정하고, 진행 중에도 변경 사항을 공유해야 합니다.
자주 묻는 질문
worktree마다 저장소를 새로 복제해야 하나요?
아닙니다. 연결된 worktree는 같은 Git 저장소를 공유하면서 별도의 작업 폴더를 제공합니다. 독립적인 보안 경계가 필요하면 별도의 실행 환경과 권한 정책을 고려해야 합니다.
worktree를 쓰면 충돌이 없어지나요?
작업 중 한 폴더에서 서로 파일을 덮어쓰는 문제는 줄일 수 있지만, 같은 코드를 서로 다르게 수정하면 병합 충돌이 생길 수 있습니다. 충돌이 없어도 동작이 맞는지는 별도로 검증해야 합니다.
참고 자료
다음 한 걸음
내 환경에서 막힌 부분은 실행 단계와 함께 질문해 주세요. 바꿔 만든 결과도 함께 나눌 수 있습니다.