💥「worktree로 격리했었는데 왜 중요한 파일이 사라진 걸까요」
병렬로 작업을 진행하기 위해 Claude Code에서 worktree를 사용해 보려고 합니다.
이런 방식으로 도입한 분들이 많으실 텐데요. 실제로 worktree는 메인 작업 디렉토리를 오염시키지 않고 여러 브랜치를 동시에 처리할 수 있는 매우 유용한 기능입니다. 그러나 Windows 환경의 경우, 이 “격리되어 있다는” 전제가 여러 개발자 커뮤니티에서 보고된 것처럼 조용히 무너지는 경우가 있습니다.
더욱 곤란한 점은, 오류 메시지가 나타나거나 경고가 표시되지 않는다는 점입니다. worktree를 삭제하는 순간, 알아채지 못하는 사이에 원래 삭제되어서는 안 될 파일까지 연관되어 버리는 — 이러한 사례들이 GitHub의 이슈, Qiita, note와 같은 기술 정보 공유 공간에서 구체적으로 보고되기 시작했습니다.
이 글에서는 왜 Windows 환경에서 이 현상이 발생하는지, 그 기술적인 메커니즘부터 실제로 어떤 회피 패턴을 구성하여 재발을 방지할 수 있는지까지, 처음 worktree라는 단어를 접하는 사람도 이해할 수 있도록, 하나씩 꼼꼼하게 설명해 드릴 것입니다. 읽어 낼 때쯤에는 “왜 위험한가”, “무엇을 해야 하는가”가 명확하게 정리된 상태가 될 것입니다.
🧩 애초에 worktree란 무엇인지, 여기부터 차근차근 정리하겠습니다
먼저 전제 확인입니다. Git 워트리(worktree)는 Git에 표준적으로 제공되는 기능으로, 하나의 리포지토리에 대해 여러 개의 “작업 디렉토리”를 동시에 가질 수 있도록 해주는 메커니즘입니다.
평소에 사용하는 폴더와 다른 위치에 동일한 리포지토리의 다른 브랜치를 체크아웃한 작업 폴더를 추가로 만들 수 있도록 구성하면 이해하기 쉬울 것입니다. Claude Code 공식 문서에서도 여러 세션을 개별 워크트리에 분리하여 하나의 터미널에서 신규 기능을 개발하는 동시에 다른 터미널에서 병렬적으로 버그 수정 작업을 진행할 수 있다고 설명하고 있습니다.
Claude Code에서는 claude --worktree (약어는 -w)라는 명령어를 전달하는 것만으로, 리포지토리의 루트 직하에 있는 .claude/worktrees/ 폴더 안에 자동으로 격리된 작업 공간이 생성됩니다. 이름을 생략하면 Claude가 자동으로 임의의 이름을 할당해주는 기능입니다.
일견하면 이것だけで 안전하게 병렬 작업이 가능해 보일 수 있습니다. 그러나 이 “자동으로 만들어, 자동으로 삭제”라는 라이프사이클의 부분에 Windows 특유의 함정이 존재한다는 것입니다.
Windows에서만 발생하는 “삭제되지 않아야 할 파일이 삭제되는” 현상에 대한 설명입니다.
출처: note 원문
번역: Gemma 3(.44) 초벌 + 교정 7청크
원문 보기 | 출처: note.com