git worktree 정리한 뒤 에이전트에게 넘기려면?
에이전트에게 저장소를 넘기기 전에 메인·링크드 worktree가 서로 무엇을 물고 있는지를 먼저 정리하지 않으면, 에이전트는 남의 수정·미추적 파일·잘못된 브랜치를 자기 작업으로 오인합니다. git worktree 에이전트 핸드오프는 “폴더만 열기”가 아니라 깨끗한(또는 의도만 남긴) worktree 경로·브랜치·범위를 넘기는 절차입니다.
이 글은 **왜 먼저 정리? · 넘길 체크리스트? · 남은 dirty 표시?**만 다룹니다. git-worktree-agent는 worktree 생성·격리, agent-git-status-gate는 턴 종료 후 porcelain 게이트입니다. 여기서는 핸드오프 직전 정리만 정리합니다. 요금·제휴·C++ 예제는 없습니다.
근거는 git-worktree입니다. remove는 깨끗한 worktree만 기본 제거하고, 불결하면 --force가 필요합니다. list로 경로·브랜치·locked/prunable을 확인합니다.
왜 worktree를 먼저 정리하나?
한 줄 답: 링크드 worktree는 객체·대부분의 refs는 공유하고 HEAD·인덱스는 worktree마다 분리합니다. 더러운 트리를 그대로 넘기면 에이전트가 공유 저장소 위 남의 인덱스·미추적을 자기 범위로 삼거나, 나중에 git worktree remove가 거절됩니다.
정리해야 하는 이유:
- 핸드오프 경계가 흐려집니다. 사람이 쓰던 메인 worktree에 스테이징·미추적·부분 편집이 남아 있으면, 에이전트 cwd를 그 경로로 두면 의도치 않은 파일을 커밋·삭제 후보로 봅니다.
- 제거·이동이 막힙니다. 문서상
git worktree remove는 tracked 수정·untracked가 없는 clean worktree만 기본 허용합니다. 불결하면-f/--force가 필요하고, 잠긴 worktree는 force를 두 번 요구합니다. “나중에 지울 임시 트리”를 더러운 채로 두면 정리 비용이 커집니다. - 같은 브랜치 중복 체크아웃이 거절됩니다.
git worktree add는 이미 다른 worktree에 체크아웃된 브랜치를 기본으로 거절합니다(--force는 예외·위험). 핸드오프용 전용 브랜치를 만들기 전에, 기존 worktree가 그 브랜치를 물고 있지 않은지list로 확인해야 합니다. - 방치된 관리 파일이 남습니다. 폴더만 지우고
remove를 안 하면$GIT_DIR/worktrees항목이 남아prune이 필요합니다. 에이전트에게 “없는 경로”를 cwd로 주면 바로 실패합니다.
실무 한 줄: 에이전트용 경로를 add하기 전에, 사람이 쓰던 트리는 커밋·stash·별도 worktree 분리·삭제 중 하나로 상태를 확정합니다. “일단 넘기고 에이전트가 알아서”는 경계가 아닙니다.
에이전트에게 넘길 체크리스트는?
한 줄 답: 넘기기 전에 목록 확인 → 범위 worktree 확보 → 깨끗함(또는 허용 dirty) 확정 → 프롬프트에 경로·브랜치·금지를 적습니다. cwd만 말해 주는 것은 체크리스트가 아닙니다.
핸드오프 체크리스트:
| 단계 | 명령·산출 | 통과 기준 |
|---|---|---|
| 1. 목록 | git worktree list / list --verbose | 경로·HEAD·브랜치·locked/prunable 파악 |
| 2. 전용 트리 | git worktree add -b <branch> <path> [<base>] 또는 기존 브랜치 add <path> <branch> | 에이전트 전용 경로·브랜치 1:1 |
| 3. 깨끗함 | 그 경로에서 git status --porcelain | 비어 있거나, 허용 목록만 남음 |
| 4. 스코프 | 프롬프트/AGENTS.md | cwd=절대경로, branch=git branch --show-current 일치 시에만 커밋 |
| 5. 금지 | 프롬프트 | 다른 worktree 경로, main 직접 커밋, 동료 브랜치 checkout |
| 6. 종료 후 | git worktree remove <path> (필요 시 정리 후) | clean이면 기본 remove; 불결하면 정리 후 제거 |
복붙용 핸드오프 블록:
Handoff (agent):
- cwd: /abs/path/to/wt-ticket-123
- branch: feat/TICKET-123-agent (must match `git branch --show-current`)
- base: origin/main (already fetched); do not checkout main
- scope: only paths under this worktree; no edits in other worktrees
- dirty policy: porcelain empty before done, OR only paths listed below
- Allowed dirty (if any): (none) | path1 path2
- Do not: git worktree remove/move on other trees; do not --force remove without human자주 쓰는 생성·확인:
# 현재 worktree 지도
git worktree list
git worktree list --verbose
# 에이전트 전용 링크드 worktree + 새 브랜치
git worktree add -b feat/TICKET-123-agent ../wt-ticket-123 origin/main
# 이미 있는 전용 브랜치를 새 경로에 (다른 worktree가 안 물고 있을 때)
git worktree add ../wt-ticket-123 feat/TICKET-123-agent
# 핸드오프 직전 깨끗함 확인 (해당 경로에서)
cd ../wt-ticket-123
git status --porcelain실험만 필요하면 문서의 -d/--detach로 throwaway worktree를 만들 수 있습니다. 장기 에이전트 작업에는 이름 있는 전용 브랜치가 추적·리뷰에 유리합니다.
작업이 끝나면 해당 링크드 worktree는 git worktree remove <path>로 제거합니다. 수동으로 폴더만 지웠다면 메인(또는 다른) worktree에서 git worktree prune으로 낡은 관리 항목을 치웁니다. 휴대·네트워크 마운트면 lock/unlock을 문서대로 씁니다.
남은 dirty는 어떻게 표시하나?
한 줄 답: 핸드오프 시점에 남겨야 하는 변경은 커밋하거나, 별도 worktree/브랜치로 분리하거나, 프롬프트에 경로 목록으로 명시합니다. “조금 dirty해도 됨”만 적고 경로를 안 주면 표시가 아닙니다.
표시 방법(우선순위):
| 방법 | 언제 | git-worktree와의 관계 |
|---|---|---|
| 커밋까지 끝내기 | 사람 작업이 논리적으로 끝난 덩어리 | 에이전트 트리를 clean으로 add/remove하기 쉬움 |
| 별도 worktree로 분리 | 사람 진행 중 작업을 건드리면 안 될 때 | 기존 더러운 메인은 유지, 에이전트는 add한 clean 경로만 |
| stash (예외) | 아주 짧은 주차 | 핸드오프 블록에 stash 존재·이름 명시; 에이전트에게 stash pop 금지 기본 |
| 허용 dirty 목록 | 에이전트가 이어서 고칠 파일만 남을 때 | porcelain에 그 경로만 있는지 Done 게이트와 맞춤 |
| 의도적 untracked | 리포트·산출물 | .gitignore 또는 allowlist; 조용히 -uno로 숨기지 않음 |
프롬프트에 적을 때:
Remaining dirty (intentional):
- M src/api/handler.go # continue: add auth header check
- ?? artifacts/repro.log # keep; do not commit unless asked
All other porcelain lines = stop and report.하지 말 것:
- dirty 메인에서 에이전트를 돌리며 “알아서 stash/commit”만 시키기.
git worktree remove -f로 더러운 트리를 지워 핸드오프를 “깨끗해 보이게” 만들기(작업 손실).- 같은 브랜치를
--force로 두 worktree에 물린 채 에이전트에게 넘기기. - 발명한 플래그·도구 전용 옵션을 문서인 양 적기. 바닥은
git worktree서브커맨드와git status --porcelain입니다.
한 줄 정리: 핸드오프 = list로 지도 확인 · 전용 worktree/브랜치 확보 · porcelain으로 깨끗함(또는 허용 목록) 확정 · 남은 dirty는 경로로 명시. 생성 축(git-worktree-agent)·종료 게이트(agent-git-status-gate)와 시점만 다릅니다.
FAQ
git-worktree-agent 글과 무엇이 다른가요?
그 글은 링크드 worktree를 만들어 에이전트를 격리하는 법입니다. 이 글은 이미 더러운 트리를 정리·분리한 뒤 넘기는 직전 체크리스트입니다. add/list/remove는 같고, 질문이 “만들기”가 아니라 “넘기기 전 상태”입니다.
agent-git-status-gate와는?
그 글은 에이전트 턴이 끝난 뒤 porcelain으로 통과/중단하는 게이트입니다. 이 글은 시작 전에 사람이 트리를 정리하고 허용 dirty를 표시하는 쪽입니다. 둘 다 porcelain을 쓰지만 시점과 소유자가 다릅니다.
remove가 거절되면?
트리가 unclean입니다. 문서대로 수정·untracked를 정리한 뒤 다시 remove하거나, 정말 버릴 때만 --force를 씁니다. 잠긴 worktree는 force를 두 번 요구합니다. 에이전트 프롬프트에 “막히면 -f로 지워라”를 기본으로 넣지 않습니다.
prune는 언제?
링크드 worktree 디렉터리를 remove 없이 지운 뒤, $GIT_DIR/worktrees에 남은 항목을 치울 때입니다. 핸드오프 전에 list에 prunable이 보이면 경로·관리 상태를 맞춘 다음 에이전트 cwd를 정합니다.
출처 (Sources)
- git-worktree —
add/list/remove/prune/lock, clean remove 규칙, 공유 vs per-worktree - git-status — 핸드오프·Done에서 쓰는
--porcelain - 인접 축: git-worktree-agent(생성·격리), agent-git-status-gate(종료 게이트)