깃 공식 문서에 따르면 일반 저장소에는 주 작업 트리 1개와 연결 작업 트리 0개 이상을 둘 수 있습니다. 이 구조를 활용하면 여러 에이전트가 서로 다른 가지에서 작업할 수 있지만, 속도 향상은 에이전트 수가 아니라 작업 의존성, 파일 소유권, 테스트 문턱에 달려 있습니다. 먼저 인터페이스와 검증 방법을 정한 뒤 독립된 깃 워크트리나 원격 작업 공간에서 실행하고, 마지막에는 하나의 기준으로 검토하고 병합해야 합니다. (git-scm.com)
이 글은 한 저장소에서 여러 인공지능 코딩 에이전트를 돌리려는 개인 개발자, 기능 출시 주기를 줄이려는 소규모 개발팀, 병렬 에이전트용 원격 맥 환경을 설계하는 플랫폼 엔지니어를 위한 안내서입니다. 단순히 터미널을 여러 개 여는 방식이 왜 부족한지도 함께 다룹니다.
시작 전, 이 프로젝트는 정말 병렬 작업에 적합한가요?
병렬 인공지능 코딩은 모든 작업을 동시에 시작하는 방식이 아닙니다. 먼저 저장소의 작업을 다음 세 가지로 나눠야 합니다.
- 독립 작업: 서로 다른 디렉터리와 인터페이스를 다루며 바로 나눌 수 있는 작업입니다.
- 선행 작업: 데이터 구조, 공통 인터페이스, 인증 규칙처럼 다른 기능이 먼저 기다려야 하는 작업입니다.
- 공유 작업: 설정 파일, 핵심 모듈, 의존성 파일처럼 여러 에이전트가 동시에 수정하면 충돌하는 작업입니다.
예를 들어 결제 기능을 추가하는 프로젝트에서 화면, 단위 테스트, 문서화는 비교적 나누기 쉽습니다. 그러나 결제 인터페이스와 공통 오류 처리 모듈이 아직 정해지지 않았다면 세 에이전트를 먼저 실행해도 결과를 합치기 어렵습니다.
다음 조건이면 병렬 실행을 멈추고 기반 작업부터 끝내는 편이 낫습니다.
- 여러 작업이 같은 핵심 파일을 수정해야 합니다.
- 입력과 출력이 되는 인터페이스가 아직 합의되지 않았습니다.
- 요구 사항이 계속 바뀌고 있습니다.
- 테스트 명령이 없거나 성공 기준이 모호합니다.
- 하나의 에이전트가 만든 구조를 다른 에이전트가 계속 다시 설계해야 합니다.
병렬 인공지능 코딩의 첫 판단은 “몇 개를 실행할까”가 아니라 “어디까지 독립시킬 수 있을까”입니다.
작업을 나누기 전에 통일된 계약을 만드세요
각 에이전트에 긴 설명을 따로 보내면 같은 저장소를 보고도 서로 다른 결론을 내릴 수 있습니다. 작업마다 아래 내용을 짧은 계약으로 작성하고 저장소 안에 버전 관리하는 것이 좋습니다.
- 작업 목표
- 수정이 허용된 경로
- 수정하면 안 되는 경로
- 입력 인터페이스와 기대 출력
- 실행할 설치, 검사, 테스트 명령
- 완료로 인정할 조건
- 다른 작업에 넘길 산출물의 위치
- 실패했을 때 기록할 내용
예를 들어 사용자 화면을 담당하는 에이전트에는 화면 디렉터리와 해당 테스트만 수정하도록 제한합니다. 공통 형식 파일이나 데이터 모델을 바꿔야 한다면 직접 수정하지 말고 변경 요청으로 남기게 합니다.
계약 파일에는 작업 상태도 포함하세요.
- 대기
- 실행 중
- 검토 대기
- 테스트 실패
- 병합 가능
- 보류
대화 창은 작업 기록의 일부일 뿐입니다. 상태, 실패 원인, 실행 로그, 결과 파일은 저장소의 문서나 이슈에 남겨야 합니다. 그래야 담당자가 바뀌어도 같은 기준으로 이어서 검토할 수 있습니다.
여러 에이전트가 같은 파일을 고치지 않게 하려면 어떻게 하나요?
가장 확실한 방법은 파일 소유권과 개발 공간을 함께 분리하는 것입니다. 작업마다 별도 가지와 깃 워크트리를 만들면 한 에이전트의 현재 변경 사항이 다른 에이전트의 폴더에 바로 나타나지 않습니다.
깃 공식 문서의 기본 구조는 주 작업 트리와 연결 작업 트리입니다. 연결 작업 트리는 같은 저장소의 객체를 공유하지만, 작업 위치와 현재 가지, 색인 같은 일부 정보는 작업 트리별로 분리됩니다. 따라서 저장 공간을 완전히 복제하지 않으면서 동시에 여러 가지를 확인할 수 있습니다. (git-scm.com)
실행 예시는 다음과 같습니다.
git worktree add ../project-ui -b feature/ui
git worktree add ../project-test -b feature/test
git worktree add ../project-docs -b feature/docs
git worktree list
각 폴더에서 에이전트를 하나씩 실행합니다. 작업이 끝나면 다음 명령으로 공간을 정리합니다.
git worktree remove ../project-ui
git worktree prune
다만 깃 워크트리만 만들었다고 완전히 격리되는 것은 아닙니다. 다음 항목은 별도로 분리해야 합니다.
- 개발 서버 포트
- 임시 파일 경로
- 데이터베이스나 캐시
- 빌드 결과물
- 환경 변수
- 인증 토큰과 개인 키
비밀 값은 에이전트 작업 폴더에 그대로 복사하지 마세요. 필요한 값만 제한된 환경 변수로 주입하고, 읽기 권한과 네트워크 권한도 작업 목적에 맞춰 줄여야 합니다. 원격 에이전트는 명령을 자동 실행할 수 있으므로 프롬프트 삽입으로 코드가 외부로 전송될 위험도 있습니다. 커서 공식 문서도 백그라운드 에이전트가 인터넷에 접근하고 터미널 명령을 자동 실행할 수 있다는 점을 보안 위험으로 설명합니다. (docs.cursor.com)
시작 직후 준비해야 할 격리 환경
첫 단계: 저장소와 의존성을 고정합니다
모든 작업 트리를 같은 기준 가지에서 만들고, 런타임과 패키지 잠금 파일을 확인합니다. 한 에이전트만 다른 버전의 패키지를 설치하면 테스트 결과를 비교할 수 없습니다.
둘째 단계: 작업별 공간을 만듭니다
각 작업에 별도 가지, 폴더, 로그 위치를 배정합니다. 동일한 임시 경로를 공유하지 않도록 이름에 작업 식별자를 넣습니다.
셋째 단계: 실행 권한을 제한합니다
읽기 전용이 가능한 작업에는 쓰기 권한을 주지 않습니다. 외부 통신이 필요하지 않은 작업은 네트워크를 차단하는 편이 안전합니다.
넷째 단계: 시작 명령을 고정합니다
설치 명령, 빌드 명령, 테스트 명령, 개발 서버 명령을 문서에 적습니다. 커서의 원격 백그라운드 에이전트도 설치 명령과 시작 명령을 나눠 환경을 준비하도록 구성합니다. 설치 뒤 저장된 상태와 에이전트 실행 시 시작되는 프로세스를 구분할 수 있다는 점이 핵심입니다. (docs.cursor.com)
다섯째 단계: 중단 조건을 먼저 적습니다
다음 상황이면 에이전트를 계속 실행하지 않고 사람의 검토로 넘깁니다.
- 허용되지 않은 파일을 수정했습니다.
- 인터페이스 계약을 바꿨습니다.
- 테스트가 반복해서 같은 이유로 실패합니다.
- 새로운 외부 패키지를 임의로 추가했습니다.
- 비밀 값이나 개인 파일을 읽으려 합니다.
클로드 코드는 설치 문서에서 최소 운영 환경과 인증 조건을 안내하고 있습니다. 공식 문서 기준으로 최소 메모리는 4 기가바이트이며, 실행에는 노드 18 이상과 인터넷 연결이 필요합니다. 여러 에이전트를 한 컴퓨터에서 실행할 때는 이 기준이 에이전트마다 누적될 수 있으므로 실제 용량은 작업 종류와 빌드 부담을 함께 보고 정해야 합니다. (docs.anthropic.com)
병렬 실행 중에는 무엇을 기록해야 하나요?
실행 중에는 에이전트에게 계속 질문하기보다 프로젝트 기록을 중심으로 관리해야 합니다. 작업별로 다음 항목을 남기세요.
- 현재 상태
- 마지막으로 성공한 명령
- 실패한 명령과 오류 내용
- 수정한 파일 목록
- 생성한 산출물
- 다른 작업이 기다려야 하는 인터페이스
- 사람의 판단이 필요한 문제
의존 작업은 앞선 작업의 커밋이나 명세를 입력으로 받아야 합니다. 예를 들어 자료 계층을 만드는 에이전트가 아직 인터페이스를 확정하지 않았다면 화면 에이전트는 임의의 자료 형식을 만들지 말고 대기해야 합니다.
이 방식은 병렬성을 낮추는 것이 아니라 재작업을 줄이는 장치입니다. 의존 작업을 억지로 동시에 실행하면 나중에 두 결과를 모두 버리고 다시 만드는 상황이 생길 수 있습니다.
오픈핸즈처럼 샌드박스를 제공하는 도구는 실행 위치를 선택할 수 있습니다. 공식 문서에는 도커 샌드박스, 일반 프로세스 방식, 원격 샌드박스가 구분되어 있으며, 일반 프로세스 방식은 호스트와 컨테이너 격리가 없기 때문에 빠르지만 안전하지 않다고 설명합니다. (docs.openhands.dev)
생성된 코드를 하나의 기준으로 검증하는 순서
에이전트가 “완료”라고 보고한 순간은 병합 가능한 순간이 아닙니다. 각 가지에서 다음 순서로 자동 검증을 실행하세요.
- [ ] 허용 경로 밖의 파일이 변경되지 않았는지 확인합니다.
- [ ] 형식 검사와 정적 분석을 실행합니다.
- [ ] 단위 테스트를 실행합니다.
- [ ] 통합 테스트 또는 빌드를 실행합니다.
- [ ] 비밀 값, 의존성 취약점, 위험한 명령을 검사합니다.
- [ ] 변경 내용과 작업 계약이 일치하는지 검토합니다.
- [ ] 실패한 명령과 남은 문제를 기록합니다.
검증은 모든 가지에서 같은 명령으로 실행해야 합니다. 한 에이전트는 빠른 단위 테스트만 실행하고 다른 에이전트는 전체 빌드를 실행하면 결과를 공정하게 비교할 수 없습니다.
여러 구현 후보가 있을 때는 코드 양이 많은 결과를 고르지 마세요. 다음 기준으로 평가하는 편이 낫습니다.
- 계약을 얼마나 정확히 지켰는가
- 테스트가 실제 요구를 검증하는가
- 공유 모듈에 남긴 영향이 작은가
- 보안 권한과 외부 통신이 줄어들었는가
- 사람이 나중에 유지하기 쉬운가
오르카 공식 문서처럼 작업마다 별도 깃 워크트리와 에이전트 터미널을 두는 도구는 여러 후보를 나란히 비교하는 데 유리합니다. 그러나 도구가 격리를 만들어 주더라도 최종 선택과 검토 기준까지 자동으로 해결해 주는 것은 아닙니다. (onorca.dev)
병합은 작업이 끝난 순서가 아니라 의존성 순서로 진행하세요
첫 병합은 공통 인터페이스, 자료 구조, 공유 모듈처럼 다른 작업이 의존하는 가지부터 진행합니다. 그 다음 나머지 가지를 최신 기준으로 갱신하고 테스트를 다시 실행합니다.
권장 순서는 다음과 같습니다.
- 기반 인터페이스 가지를 검토하고 병합합니다.
- 병합된 기준을 다른 작업 가지에 반영합니다.
- 각 가지에서 전체 검증을 다시 실행합니다.
- 충돌이 난 파일은 자동 해결보다 소유자 검토를 우선합니다.
- 기능 가지를 작은 단위로 병합합니다.
- 마지막에 통합 테스트와 배포 전 검사를 실행합니다.
깃은 다른 연결 작업 트리에서 이미 사용 중인 가지를 다시 체크아웃하지 못하게 막는 보호 장치를 기본으로 제공합니다. 강제 옵션으로 우회할 수 있지만, 병렬 개발에서 이 보호 장치를 무시하면 같은 가지에 대한 변경 위치가 꼬일 수 있습니다. (git-scm.com)
언제 병렬 코딩이 오히려 더 느려지나요?
다음 상황에서는 단일 에이전트가 더 빠를 가능성이 큽니다.
- 핵심 파일을 여러 작업이 함께 수정합니다.
- 요구 사항이 아직 정리되지 않았습니다.
- 각 작업의 테스트 환경이 무겁습니다.
- 에이전트마다 같은 자료베이스와 개발 서버를 공유합니다.
- 사람이 모든 결과를 직접 비교해야 합니다.
- 충돌 해결에 드는 시간이 생성 시간보다 깁니다.
첫 주에는 에이전트 수보다 대기 시간, 충돌 수, 재작업 횟수, 사람의 검토 시간을 기록하세요. 병목이 작업 분할이라면 환경을 더 구매해도 해결되지 않습니다. 반대로 작업은 잘 나뉘었는데 환경 시작과 빌드 대기가 길다면 그때 원격 작업 공간이나 추가 맥 용량을 검토할 수 있습니다.
개인 개발자는 먼저 현재 장비에서 두 작업만 검증하는 것이 좋습니다. 소규모 팀은 작업 계약과 자동 검증을 저장소에 고정한 뒤 병렬 수를 늘려야 합니다. 장시간 실행되는 여러 에이전트와 브라우저 테스트가 필요하다면 맥 미니 렌탈 환경을 단기 작업 공간으로 비교해 볼 수 있습니다. 원격 환경을 도입하기 전에는 맥 개발 환경 점검 항목을 기준으로 접속, 권한, 저장 공간, 로그 보존을 확인하세요.
현재 노트북에서 여러 에이전트를 실행하는 방식은 초기 비용이 없다는 장점이 있지만, 메모리와 저장 장치를 함께 점유하고 개발 서버 포트와 비밀 값이 섞이기 쉽습니다. 반대로 장비를 바로 구매하면 유휴 시간에도 비용이 발생하고, 실제 병렬 작업량이 예상보다 적을 때 회수하기 어렵습니다. 작업 의존성 지도를 먼저 만든 뒤, 짧은 실험은 임시 맥 환경으로 검증하고 지속적으로 무거운 작업이 확인될 때만 장기 원격 환경이나 자체 장비를 선택하는 편이 합리적입니다. 필요하다면 맥 미니 대여 이용 안내에서 사용 기간과 접속 조건을 확인해 보세요.
병렬 인공지능 코딩은 여러 창을 동시에 여는 기술이 아닙니다. 작업을 독립시키고, 각 에이전트의 경계를 정하고, 같은 테스트 문턱을 통과시킨 뒤, 의존성 순서에 맞춰 결과를 수렴시키는 운영 방식입니다. 이 순서를 지키면 에이전트 수를 무작정 늘리지 않고도 어떤 작업을 병렬화할지 판단할 수 있습니다.