Parallel Code는 Claude Code, Codex CLI, Gemini CLI, Copilot CLI 같은 AI 코딩 도구를 git worktree 단위로 병렬 실행하는 오픈소스 데스크톱 앱입니다. 슬로건은 “Ten agents. Ten branches. One afternoon.”입니다. 과장이 섞여 있어도 방향은 분명합니다. 이제 개발자는 하나의 에이전트가 끝날 때까지 기다리는 대신, 여러 해결책을 동시에 만들고 diff를 비교할 수 있습니다.
이 글은 Parallel Code를 실무에 도입할 때의 사용법과 주의점을 정리합니다. 핵심 키워드는 Parallel Code, git worktree AI agent, AI 코딩 에이전트 병렬 실행, Claude Code Codex Gemini 워크플로우입니다.
AI 코딩 에이전트는 빠르지만 항상 한 번에 정답을 내지는 않습니다. 같은 버그를 맡겨도 어떤 에이전트는 작은 패치를 만들고, 어떤 에이전트는 구조를 갈아엎고, 어떤 에이전트는 테스트를 먼저 추가합니다. 한 번에 하나씩 시도하면 시간이 오래 걸립니다. 병렬로 시도하면 여러 후보 diff를 놓고 고를 수 있습니다.
특히 다음 작업에서 병렬 실행이 효과적입니다.
반대로 요구사항이 명확하고 수정 범위가 작은 작업에는 굳이 병렬 실행이 필요 없습니다. 버튼 라벨 변경, 타입 오류 한 줄 수정, 문서 오타 수정에 5개 에이전트를 돌리는 것은 비용 낭비입니다. Parallel Code는 “모든 작업을 병렬화”하는 도구가 아니라 “불확실성이 큰 작업에서 후보를 빨리 모으는” 도구로 보는 편이 맞습니다.
Parallel Code는 작업을 만들 때 main 브랜치에서 새 git branch를 만들고, 별도 git worktree를 설정합니다. 각 에이전트는 자기 worktree 안에서만 파일을 바꿉니다. 그래서 동시에 여러 에이전트를 돌려도 같은 폴더에서 충돌하지 않습니다. 마음에 드는 결과는 사이드바에서 main으로 merge하고, 아닌 결과는 버리면 됩니다.
이 구조는 터미널 여러 개를 띄워 수동으로 worktree를 관리하는 방식과 비슷하지만, GUI와 diff review가 붙어 있습니다. README 기준으로 Parallel Code는 작업별 터미널, 내장 diff viewer, inline review comments, progress timeline, task notes, PR CI status watcher, Dockerfile 기반 sandbox, coverage badge, QR code 기반 모바일 모니터링 같은 기능을 제공합니다.
중요한 것은 git worktree가 안전망의 전부는 아니라는 점입니다. worktree는 파일 충돌을 줄여 주지만, 에이전트가 외부 네트워크에 접근하거나 홈 디렉터리를 읽거나 패키지를 설치하는 위험까지 자동으로 막지는 않습니다. 에이전트별 sandbox와 승인 정책은 별도로 유지해야 합니다.
Parallel Code를 쓰기 전에는 저장소 상태를 먼저 정리해야 합니다. main 또는 develop 브랜치가 최신인지 확인하고, 작업 중인 변경이 남아 있다면 커밋하거나 stash해야 합니다. 병렬 작업의 기준점이 지저분하면 나중에 어떤 에이전트가 만든 변경인지 구분하기 어렵습니다.
또한 테스트 명령과 빌드 명령을 문서화해야 합니다. 에이전트에게 “고쳐줘”라고만 말하면 각자 다른 검증 기준을 적용합니다. package.json script, Makefile, CI workflow 중 실제로 통과해야 할 명령을 명확히 알려줘야 합니다. 예를 들어 “수정 후 npm test와 npm run typecheck를 실행하고 실패 로그를 요약하라”처럼 적습니다.
Node 프로젝트라면 node_modules symlink 방식이 편하지만, 패키지 설치가 필요한 작업에서는 주의가 필요합니다. 각 worktree에서 lockfile을 바꾸면 결과 비교가 어려워질 수 있습니다. 의존성 추가가 목적이 아니라면 “새 패키지 추가 금지”를 프롬프트에 넣는 것이 좋습니다.
병렬 에이전트에서 프롬프트는 더 중요합니다. 여러 후보를 비교하려면 입력 조건이 같아야 합니다. 다음 형식을 추천합니다.
예를 들어 “결제 실패 후 재시도 버튼이 비활성화된 채 유지되는 버그를 수정하라. checkout 모듈 안에서만 수정하고 결제 API 인터페이스는 바꾸지 마라. 새 패키지는 추가하지 마라. npm test -- checkout과 npm run typecheck를 실행하라. 마지막에 원인과 변경 파일을 요약하라.” 정도로 써야 비교 가능한 결과가 나옵니다.
프롬프트가 흐리면 에이전트 간 차이가 아이디어 차이가 아니라 해석 차이로 벌어집니다. 그러면 diff 비교가 어려워집니다.
Parallel Code의 장점은 여러 diff를 놓고 고르는 것입니다. 하지만 기준 없이 보면 가장 그럴듯한 설명을 한 에이전트를 선택하게 됩니다. 실무에서는 설명보다 diff가 중요합니다.
추천 기준은 다섯 가지입니다. 첫째, 수정 범위가 문제에 비해 과하지 않은가. 둘째, 기존 public API와 데이터 구조를 깨지 않는가. 셋째, 실패를 재현하는 테스트가 추가됐는가. 넷째, 타입·린트·빌드가 통과했는가. 다섯째, 예외 처리와 롤백 경로가 있는가.
여러 에이전트가 만든 좋은 부분을 합치는 것도 가능합니다. 한 에이전트가 원인을 잘 찾고, 다른 에이전트가 테스트를 잘 썼다면 사람이 둘을 조합하면 됩니다. 이때 무작정 merge하지 말고 main에서 새 브랜치를 만들어 필요한 패치만 cherry-pick하거나 직접 반영하는 편이 안전합니다.
개인 도구로 시작할 때는 버그 수정과 작은 리팩터링에 쓰는 것이 좋습니다. 팀 도구로 확장할 때는 규칙이 필요합니다. 병렬 에이전트 결과를 그대로 PR로 올릴 수 있는지, 사람이 squash해서 올려야 하는지, AI 생성 브랜치 이름 규칙은 무엇인지, 실패한 후보는 언제 삭제하는지 정해야 합니다.
또한 에이전트가 남긴 커밋 메시지와 PR 설명을 그대로 쓰면 안 됩니다. AI는 변경 이유를 과장하거나 테스트 실행 여부를 부정확하게 쓸 수 있습니다. PR 생성 전 사람이 실제 실행 로그를 확인하고 설명을 다시 써야 합니다.
보안 측면에서는 외부 명령 승인 정책이 필수입니다. Parallel Code가 worktree를 분리해도, 각 에이전트가 사용하는 CLI의 권한은 별도입니다. npm install, curl, git push, 배포 명령, 환경변수 출력은 승인 대상이어야 합니다. Dockerfile 기반 sandbox를 쓸 수 있다면 위험한 실험 작업부터 적용하는 것이 좋습니다.
병렬 실행은 wall-clock time을 줄이지만 총 토큰 사용량과 로컬 리소스 사용량은 늘립니다. 그래서 모든 작업에 10개 에이전트를 쓰는 전략은 오래 못 갑니다. 추천은 2단계입니다. 먼저 가벼운 작업은 1개 에이전트로 처리합니다. 불확실성이 큰 작업만 3개 후보를 돌립니다. 보안·마이그레이션·대형 리팩터링처럼 리스크가 큰 작업은 5개 이상을 고려합니다.
생산성 지표도 감으로 보면 안 됩니다. 작업당 걸린 시간, 선택된 후보 비율, 폐기된 후보 이유, 리뷰에서 발견된 문제, 최종 버그 재발 여부를 기록하면 병렬 실행이 실제로 도움이 되는지 알 수 있습니다. 한 달 정도 기록하면 어떤 에이전트가 어떤 작업에 강한지도 보입니다.
Parallel Code의 가치는 AI에게 코드를 더 많이 맡기는 데 있지 않습니다. 여러 해결책을 안전하게 격리해 놓고, 개발자가 더 빨리 좋은 선택을 하게 만드는 데 있습니다. git worktree와 명확한 리뷰 기준을 함께 쓰면 병렬 에이전트는 장난감이 아니라 실전 개발 프로세스가 됩니다.
