git worktree로 에이전트 격리하려면

git worktree 에이전트 격리는 “한 클론·한 워킹 디렉터리”를 여러 에이전트가 공유하지 않게 막는 축입니다. 같은 저장소에 링크드 worktree를 추가하면 브랜치를 동시에 여러 경로에 체크아웃할 수 있고, 에이전트마다 독립된 HEAD·인덱스·작업 트리를 갖습니다. 가격·플랜·토큰 숫자는 다루지 않습니다.

이 글은 worktree 생성, 브랜치 규칙, 머지 전 점검만 정리합니다. 근거는 git-worktree 공식 문서입니다. 브랜치 이름·리뷰 게이트·경로 allowlist·PR 쪼개기는 별도 글(multi-agent-pr-workflow) 축입니다. 여기서는 워킹트리 격리에만 초점을 둡니다.

worktree는 어떻게 만드나?

한 줄 답: 메인 worktree에서 git worktree add로 경로와 브랜치를 지정합니다. 새 브랜치면 -b, 기존 브랜치면 경로만(또는 경로+커밋-ish), 실험용이면 -d/--detach입니다.

git-worktree 기준으로 저장소는 메인 worktree(clone/init으로 생긴 것)와 0개 이상의 링크드 worktree를 가집니다. 링크드 worktree는 객체·대부분의 refs/를 공유하고, HEAD·인덱스 등 per-worktree 파일만 분리합니다.

자주 쓰는 패턴:

# 1) 새 토픽 브랜치 + 링크드 worktree (경로 basename이 기본 브랜치명)
git worktree add ../wt-agent-a -b feat/TICKET-agent-a

# 2) 이미 있는 브랜치를 새 경로에 체크아웃
git worktree add ../wt-agent-b feat/TICKET-agent-b

# 3) 브랜치 없이 실험 (detached HEAD)
git worktree add -d ../wt-scratch

# 4) 목록·상태 확인
git worktree list
git worktree list --verbose

문서가 강조하는 편의 규칙:

git worktree add <path>만 주면, basename으로 브랜치를 만들고(-b와 유사) HEAD 기준에서 분기합니다.
<commit-ish>가 이미 다른 worktree에 체크아웃된 브랜치이면 add가 거절합니다. 같은 브랜치를 두 경로에 동시에 두려면 기본적으로 불가합니다(--force는 예외·위험).
끝나면 git worktree remove <path>로 제거합니다. 수동으로 폴더만 지우면 $GIT_DIR/worktrees 관리 파일이 남을 수 있어 prune이 필요합니다.
휴대 디스크·네트워크 마운트처럼 가끔 사라지는 경로면 git worktree lock으로 자동 prune을 막습니다.

에이전트 세션을 열 때 cwd를 그 에이전트 전용 worktree 경로로 고정합니다. 메인 트리에서 여러 에이전트가 checkout을 바꾸면 서로 덮어씁니다. worktree는 그 충돌을 경로 단위로 끊습니다.

Orca·Cursor 등 도구가 worktree를 감싸 주더라도, 바닥은 같은 git worktree add 모델입니다. 도구 UI에 의존하기 전에 git worktree list로 실제 경로·브랜치를 확인하는 습관이 안전합니다.

브랜치 규칙은?

한 줄 답: 에이전트 1 = worktree 1 = 브랜치 1입니다. 메인/main은 사람이 두고, 에이전트는 전용 브랜치만 체크아웃합니다. 다른 에이전트 브랜치·공유 통합 브랜치에 직접 commit하지 않습니다.

worktree 축에서 고정할 규칙:

규칙	이유 (git-worktree)
브랜치는 worktree마다 전용	같은 브랜치는 기본으로 한 worktree만 체크아웃 가능
이름에 역할·티켓·에이전트 ID	`list`만 봐도 소유자가 보임
메인은 사람·통합용	에이전트가 `main`에 직접 push/commit하지 않음
`-B`·`--force`는 예외 절차	기존 브랜치 리셋·중복 체크아웃 우회는 사고 유발
끝나면 `remove`	방치된 worktree는 stale admin + 디스크 낭비

이름 예:

../wt-a  →  feat/TICKET-123-api-auth     (agent-A)
../wt-b  →  feat/TICKET-123-ui-login     (agent-B)
../wt-c  →  chore/TICKET-123-ci-cache    (agent-C)

프롬프트·AGENTS.md에 넣을 한 줄:

cwd — 지정 worktree 절대/상대 경로만 편집.
branch — git branch --show-current가 배정 브랜치와 일치할 때만 커밋.
금지 — 다른 worktree 경로, main, 동료 에이전트 브랜치 checkout/push.
fetch 기준 — origin/main(또는 합의 base)을 fetch한 뒤 -b로 분기.

multi-agent-pr-workflow와의 경계: 그 글은 PR 단위·리뷰 승인·경로 allowlist·충돌 예방을 다룹니다. 이 글의 브랜치 규칙은 “어느 디렉터리에 어떤 브랜치가 앉아 있는가”를 worktree로 고정하는 쪽에 가깝습니다. 둘 다 쓰면 “격리(worktree) + 리뷰(PR)”가 됩니다.

-d detached worktree는 실험·일회성 검증에만 쓰고, 머지 후보 작업은 이름 있는 브랜치에 둡니다. detached에서만 쌓인 커밋은 나중에 브랜치로 옮기는 비용이 큽니다.

머지 전 점검은?

한 줄 답: 해당 worktree 안에서 status·diff·테스트·base rebase/merge를 끝낸 뒤 PR을 엽니다. 깨끗할 때만 git worktree remove하고, 머지 권한은 사람(또는 필수 검사)에 둡니다.

worktree별 머지 전 체크리스트:

위치 확인 — pwd와 git rev-parse --show-toplevel이 배정 worktree인지 확인합니다.
브랜치 확인 — git branch --show-current · git worktree list에서 해당 경로의 브랜치가 기대한 이름인지 봅니다.
깨끗함 — git status에 의도하지 않은 untracked·modified가 없어야 합니다. remove도 기본으로 clean worktree만 허용합니다(unclean은 --force).
base 동기화 — git fetch origin 후 origin/main(합의 base) 위로 rebase 또는 merge. 충돌은 그 worktree에서 해결합니다.
로컬 검증 — 프로젝트 합의 테스트·린트·빌드를 그 경로에서 실행합니다. 메인 트리 결과를 대리로 쓰지 않습니다.
범위 — git diff origin/main...HEAD로 파일 목록이 에이전트 담당 경로와 맞는지 봅니다(상세 allowlist는 PR 워크플로 글).
PR·리뷰 — push 후 PR. Approve·머지는 사람/CODEOWNERS. 에이전트끼리만 승인하지 않습니다.
정리 — 머지 후(또는 폐기 후) git worktree remove ../wt-…. 폴더만 삭제했다면 메인에서 git worktree prune으로 관리 파일을 걷습니다. 옮긴 뒤에는 git worktree repair를 문서대로 씁니다.

위험한 지름길:

메인 worktree에서 다른 에이전트 브랜치로 잠깐 checkout해 “한곳에 모아” 머지 준비.
unclean worktree를 --force로 반복 삭제하며 작업 중 파일을 날림.
같은 브랜치를 --force로 두 worktree에 올려 인덱스·커밋이 엇갈리게 함.

서브모듈이 있는 슈퍼프로젝트는 문서상 다중 체크아웃 지원이 불완전합니다. 에이전트 병렬이 필요하면 서브모듈 경계를 먼저 줄이거나, 클론 분리를 검토합니다.

자주 묻는 질문

clone을 여러 개 두는 것과 뭐가 다르나요?
worktree는 객체 저장소를 공유하고 링크드 트리만 추가합니다. 디스크·fetch 비용이 클론 여러 개보다 보통 작습니다. 격리는 “디렉터리·HEAD” 단위입니다.

multi-agent-pr-workflow랑 겹치지 않나요?
겹치는 단어(브랜치·에이전트)는 있어도 축이 다릅니다. PR 워크플로 = 리뷰·경로·충돌 예방. 이 글 = git worktree add/list/remove로 워킹트리 격리.

같은 브랜치를 두 에이전트가 쓰면?
기본 add가 거절합니다. 억지로 --force하지 말고 브랜치를 쪼갭니다.

worktree를 폴더만 지웠어요.
$GIT_DIR/worktrees에 stale 항목이 남을 수 있습니다. git worktree prune으로 정리하고, 다음부터는 remove를 씁니다.

무엇을 기억하면 되나?

에이전트 격리 = 링크드 worktree + 전용 브랜치입니다. 만들 때는 git worktree add(-b / 기존 브랜치 / -d), 규칙는 1 에이전트 · 1 경로 · 1 브랜치, 머지 전에는 그 경로에서 status·base·테스트 후 사람 리뷰입니다. PR·리뷰 세부는 multi-agent-pr-workflow를 봅니다.

공식 문서는 어디인가?

git-worktree — add / list / remove / lock / prune / repair
같은 문서의 DESCRIPTION — main vs linked worktree, 브랜치 중복 체크아웃 거절
같은 문서의 EXAMPLES — 긴급 수정용 임시 worktree 후 remove