Paseo 병렬 개발의 핵심: worktree와 origin/main으로 작업 경계 만들기
인증 기능과 결제 기능을 동시에 맡겼는데 두 에이전트가 같은 설정 파일을 번갈아 바꾸고 있다. 에이전트를 두 개 실행했다는 사실만으로 작업이 격리되지는 않는다. Paseo에서 병렬 개발을 안정적으로 운영하려면 workspace가 가리키는 디렉터리와 브랜치부터 확인해야 한다.
대상: 여러 에이전트로 독립적인 변경을 진행하는 개발자. 2026-11-07 공식 문서 기준. 아래 생성 명령은 독자 환경에서 실행할 예시이며, 이 글 작성 중 저장소나 브랜치를 생성하지 않았다.
1. workspace 하나에 에이전트가 여러 개 있을 수 있다
workspace는 작업 디렉터리와 에이전트, 터미널, 브라우저 등을 묶는 작업 공간이다. worktree는 그 공간을 Git의 별도 디렉터리와 브랜치로 뒷받침하는 방식이다. 같은 workspace의 두 에이전트는 같은 파일을 볼 수 있으므로 “에이전트별 독립 작업”이 필요하면 별도 worktree를 만들어야 한다.
반대로 구현 직후 리뷰어가 동일한 diff를 읽어야 한다면 같은 workspace에서 읽기 전용으로 검토하는 방식이 자연스럽다. 격리는 무조건 많이 만드는 것보다 동시에 쓰기를 수행하는 범위에 맞추는 편이 낫다.
| 작업 조합 | 권장 운영 방식 |
|---|---|
| 서로 독립적인 기능 두 개 구현 | 별도 worktree와 별도 브랜치 |
| 구현 완료 후 동일 diff 리뷰 | 해당 workspace에서 읽기 전용 리뷰 |
| 같은 파일을 수정하는 연속 단계 | 선행 작업 완료 후 순차 실행 |
2. 시작 기준은 origin/main처럼 명확히 지정한다
원본 저장소 디렉터리에서 다음처럼 작업 공간을 만들 수 있다. 예시는 POSIX 셸의 줄 연결 문법이다. PowerShell에서는 한 줄로 실행하거나 해당 셸의 문법에 맞춰 바꾼다.
paseo workspace create \
--isolation worktree \
--mode branch-off \
--new-branch feature/auth-flow \
--worktree-slug auth-flow \
--base origin/main
공식 문서는 모호한 main 대신 origin/main을 권한다. main은 로컬 브랜치로 먼저 해석되므로 마지막으로 갱신한 시점에 머물 수 있다. 다만 이름을 명확히 쓴 것만으로 네트워크 fetch 성공까지 입증되지는 않는다. 최신 커밋이 중요한 작업이라면 원격 갱신 결과와 실제 생성된 HEAD를 확인한다.
이미 존재하는 브랜치를 살필 때는 checkout-branch, PR을 따로 검사할 때는 checkout-pr 모드를 사용할 수 있다. 신규 기능을 분기하는 경우와 기존 변경을 여는 경우를 섞지 않는 것이 핵심이다.
3. paseo.json을 수정했는데 setup이 바뀌지 않는 이유
worktree 생성에 쓰이는 paseo.json은 선택한 base 브랜치에 커밋된 버전에서 읽힌다. 원본 디렉터리에서 파일을 편집만 해 두었다면 새 worktree에 반영된다고 기대해서는 안 된다.
{
"worktree": {
"setup": "npm ci"
},
"scripts": {
"test": { "command": "npm test" }
}
}
이 예시는 package-lock.json과 test 스크립트가 있는 Node 프로젝트용이다. Python 프로젝트라면 그 저장소에 맞는 환경 준비 명령으로 바꾼다. 설정 파일만 복사해서 모든 프로젝트에 통용된다고 생각하면 setup 단계부터 실패한다.
Git에 없는 필요한 로컬 파일은 .worktreeinclude로 선택 복사할 수 있다. 다만 worktree가 DB·스토리지·외부 계정까지 자동으로 격리하는 것은 아니다. 동일한 개발 DB를 향하는 .env를 복사했다면 파일은 분리돼도 데이터는 공유된다. 병렬 실행 전에 데이터베이스 이름, 큐 이름과 테스트 자원도 분리할지 결정한다.
4. 에이전트에게 파일 경계와 완료 조건을 함께 준다
다음은 독립 작업을 맡길 때 사용할 지시문 예시다.
현재 auth-flow workspace에서 로그인 오류 처리를 구현하라.
먼저 실제 작업 경로와 브랜치를 확인하라.
담당 범위는 인증 모듈과 그 테스트다.
다른 작업자의 변경을 되돌리지 말고 공용 설정 변경은 근거를 남겨라.
완료 시 diff 요약, 실행한 검사, 남은 한계를 보고하라.
worktree가 제공하는 것은 Git 작업 영역의 경계다. 요구사항 누락이나 잘못된 구현까지 막지는 않는다. 결과를 합치기 전에는 실제 diff와 테스트 결과를 확인하고, 공용 인터페이스를 바꾼 작업끼리는 통합 확인을 추가한다.
5. archive를 단순히 탭 닫기로 생각하지 않는다
공식 문서상 worktree를 사용하는 마지막 활성 workspace가 archive되면 teardown을 거쳐 worktree가 제거된다. 따라서 미커밋 변경과 필요한 산출물을 정리하기 전에 archive하는 습관은 피한다.
권장 마무리 순서는 diff 확인, 필요한 변경의 커밋·전달, 통합 여부 확인, 마지막으로 archive다. 테스트 결과나 스크린샷이 worktree 안에만 있다면 보관 위치도 확인한다. 병렬 개발의 속도는 에이전트 수보다, 각 작업의 시작점과 종료점이 얼마나 명확한가에 크게 좌우된다.
댓글
댓글 쓰기