using-git-worktrees

개요

using-git-worktrees란 무엇인가요?

using-git-worktrees는 obra/superpowers 리포지토리에 포함된 워크플로 스킬로, 기능 개발을 위한 독립된 Git worktree를 만드는 과정을 단계별로 안내합니다. worktree를 어떤 위치에, 어떤 방식으로 만들지 표준화해, 하나의 작업 디렉터리에서 브랜치를 계속 바꿔가며 작업할 필요 없이 여러 브랜치를 동시에 안전하게 다룰 수 있게 해줍니다.

직접 worktree 위치를 감으로 정하거나, 추적되거나 무시되지 않은 디렉터리 때문에 위험을 감수할 필요가 없습니다. 이 스킬은 디렉터리 선택과 검증 절차를 명시적으로 규정해, 구현 작업은 확실히 분리하면서 메인 프로젝트 트리는 깔끔하게 유지하는 것을 목표로 합니다.

이 스킬은 누구를 위한 것인가요?

이 스킬은 다음과 같은 개발자를 위해 설계되었습니다.

• 여러 기능 또는 버그 수정을 병렬로 진행하는 개발자
• 프로젝트마다 반복해서 사용할 수 있는 Git worktree 규칙을 갖고 싶어 하는 팀/개발자
• worktree 디렉터리가 올바른 위치에 생성되어 커밋을 더럽히지 않는다는 확신이 필요한 경우
• 커맨드라인 Git을 사용하고, 간단한 셸 명령 실행에 익숙한 사람

특히, 문서화된 일관된 Git 워크플로를 갖추고 싶고, 임시 혹은 장기간 유지되는 기능 작업 환경을 더 안전하게 띄워 올리고 싶은 팀에 적합합니다.

using-git-worktrees는 어떤 문제를 해결하나요?

using-git-worktrees는 여러 브랜치를 다룰 때 자주 발생하는 문제들을 줄여 줍니다.

• 브랜치 전환 부담: 하나의 디렉터리에서 stash와 checkout을 반복하지 않고도 여러 브랜치를 동시에 작업할 수 있습니다.
• 지저분한 프로젝트 루트: 임시 디렉터리나 worktree 폴더가 여기저기 흩어져 쌓이는 일을 막아 줍니다.
• worktree 폴더의 실수로 인한 커밋: worktree를 만들기 전에 로컬 worktree 디렉터리가 Git에서 무시되는지 확인하는 단계를 워크플로에 포함합니다.
• 머신마다 다른 관례: CLAUDE.md에 정의된 디렉터리 선호도와 기존 디렉터리를 함께 확인해, 프로젝트마다 표준화된 레이아웃을 쓰도록 유도합니다.

Git worktree를 자주 쓰거나, 이제부터 안전하게 활용해 보고 싶다면, 이 스킬이 가볍고 의견이 잘 드러난 절차를 제공해 줍니다.

언제 using-git-worktrees를 쓰면 좋은가요?

다음과 같은 상황에서 using-git-worktrees 사용을 추천합니다.

• 현재 작업 디렉터리와 분리된 환경이 필요한 기능 개발을 막 시작하려는 경우
• 이미 존재하는 설계나 계획을 바탕으로 구현을 시작하면서, 이를 위한 깨끗한 worktree에서 작업하고 싶은 경우
• 리포지토리에서 이미 .worktrees 또는 worktrees 디렉터리를 사용하고 있고, 해당 관례를 계속 따르고 싶은 경우

반대로 다음과 같은 경우에는 활용도가 낮을 수 있습니다.

• 항상 한 번에 하나의 브랜치에서만 작업하고, 여러 작업 사본이 필요 없는 경우
• 이미 내부적으로 worktree를 다른 방식으로 관리하는 엄격하고 자동화된 도구를 사용 중인 경우

이런 특수한 경우를 제외하면, using-git-worktrees 플로를 채택하는 것만으로도 Git 워크플로가 훨씬 예측 가능하고 안전해질 수 있습니다.

사용 방법

설치 및 기본 설정

환경에 using-git-worktrees 스킬을 추가하려면 obra/superpowers 리포지토리에서 스킬을 설치합니다.

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

설치 후에는 다음을 수행하세요.

1. 리포지토리 체크아웃에서 skills/using-git-worktrees/SKILL.md 파일을 엽니다.
2. 디렉터리 선택 규칙과 안전성 검증 단계를 이해할 수 있도록 처음부터 끝까지 한 번 읽어 봅니다.
3. 추가 worktree 디렉터리를 만들어도 괜찮다고 생각되는 Git 리포지토리 안에서 작업 중인지 확인합니다.

Git과, 스킬 설명에 나오는 명령을 실행할 수 있는 셸 이외에 별도의 의존성은 필요하지 않습니다.

핵심 워크플로: 분리된 기능 작업 시작하기

새로운 기능 작업을 시작하면서 분리된 작업 공간이 필요하다면, using-git-worktrees에 담긴 상위 레벨 플로를 따라가면 됩니다.

1. 워크플로 선언하기 (본인과 도우미/도구에게 알리는 용도):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. worktree 디렉터리 결정: 디렉터리 선택 프로세스를 통해 어디에 worktree를 만들지 결정합니다(다음 섹션 참조). 이렇게 하면 worktree가 임의의 경로에 흩어지지 않습니다.

3. 안전성 검증 수행: 선택된 디렉터리 종류(프로젝트 로컬 vs. 글로벌)에 맞는 안전성 검증을 실행합니다. 이 단계는 worktree 폴더가 실수로 커밋되는 일을 방지하는 데 필수입니다.

4. 필요한 브랜치에 대한 Git worktree 생성: 예를 들어 다음과 같이 실행합니다.

   git worktree add <path-to-worktree> <branch-name>
   

5. 새 worktree로 이동한 뒤, 그곳에서 구현 작업을 진행합니다. 원래 작업 사본은 코드 리뷰, 간단한 수정, 기타 작업을 위한 깨끗한 상태로 남겨둘 수 있습니다.

새로운 기능, 스파이크, 실험 등을 시작하면서 기존 작업 디렉터리를 건드리고 싶지 않을 때마다 이 플로를 반복해서 사용하면 됩니다.

디렉터리 선택 절차

using-git-worktrees는 worktree가 어디에 위치해야 하는지에 대한 우선순위를 정해 두어, 매번 고민하지 않고 일관된 위치에 만들 수 있게 합니다.

1. 기존 worktree 디렉터리 우선 사용

리포지토리 루트에서 다음 우선순위에 따라 worktree 디렉터리를 확인합니다.

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

• .worktrees가 존재하면, 그 디렉터리를 사용합니다.
• .worktrees가 없고 worktrees만 존재하면, worktrees를 사용합니다.
• 둘 다 없다면 다음 단계로 넘어갑니다.

이 규칙을 통해 동일한 프로젝트 안에서는 이전에 사용하던 선택을 계속 유지할 수 있습니다.

2. CLAUDE.md에서 프로젝트 선호도 확인

표준 worktree 디렉터리가 없다면, 프로젝트 루트의 CLAUDE.md에 선호 디렉터리가 문서화되어 있는지 확인합니다.

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

CLAUDE.md에 worktree 디렉터리 규칙이 정의되어 있다면, 추가 질문 없이 그 규칙을 그대로 따릅니다. 이렇게 하면 프로젝트 차원에서 선호하는 worktree 레이아웃을 중앙에서 관리할 수 있습니다.

3. 선호도가 없을 때 새 위치를 정하기

기존 디렉터리도 없고 CLAUDE.md에도 문서화된 선호도가 없다면, 이제 새 worktree가 어디에 위치해야 할지 명시적으로 선택해야 합니다. 이 스킬은 자신(또는 팀)에게 다음과 같이 명확한 선택지를 제시하는 방식을 권장합니다.

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• 옵션 1: .worktrees/ 는 worktree를 프로젝트와 나란히 두되, 기본적으로 숨김 처리되어 있고 리포 안에서 찾기 쉽습니다.
• 옵션 2: ~/.config/superpowers/worktrees/<project-name>/ 는 리포지토리 루트 바깥의 전역 위치에 프로젝트별로 worktree를 모아 두는 방식으로, Git 작업 디렉터리를 눈에 보기에 최대한 간결하게 유지하고 싶을 때 유용합니다.

한 번 위치를 정했다면, 같은 프로젝트에서는 계속 그 위치를 사용하는 것이 좋습니다. 그래야 worktree가 여러 곳으로 분산되지 않습니다.

worktree 생성 전 안전성 검증

using-git-worktrees 스킬은 특히 Git 리포지토리 내부에 위치한 프로젝트 로컬 디렉터리를 사용할 때, 안전성 체크를 매우 중요하게 다룹니다.

프로젝트 로컬 디렉터리가 무시(ignore)되는지 확인하기

.worktrees나 worktrees 같은 프로젝트 로컬 디렉터리를 사용할 경우, 그 안에 worktree를 만들기 전에 해당 디렉터리가 Git에서 무시되는지를 반드시 확인해야 합니다. 이 스킬에서는 이를 반드시 지켜야 하는(MUST) 조건으로 강조합니다.

최소한 다음을 수행해야 합니다.

• .worktrees 또는 worktrees가 .gitignore, .git/info/exclude, 전역 ignore 파일 등 적절한 ignore 파일에 포함되어 있는지 확인하고,
• git check-ignore를 사용해, 현재 Git 설정에서 실제로 해당 디렉터리가 무시되고 있는지 검증합니다.

일반적인 패턴은 디렉터리 경로에 대해 git check-ignore를 실행해, 로컬/전역/시스템 ignore 설정을 모두 고려한 상태에서 Git이 해당 디렉터리를 무시하는지 확인하는 것입니다.

만약 디렉터리가 무시되지 않는다면:

• 적절한 ignore 파일에 디렉터리를 추가하고, 리포지토리에 포함되어야 하는 규칙이라면 커밋한 뒤,
• 그 위치에 worktree를 만들기 전에 다시 체크를 수행합니다.

이 과정을 통해 worktree 인프라용 디렉터리가 실수로 stage되거나 커밋되는 위험을 크게 줄일 수 있습니다.

글로벌 위치를 안전하게 사용하는 방법

~/.config/superpowers/worktrees/와 같은 글로벌 디렉터리 옵션을 선택한 경우, 해당 디렉터리는 리포지토리 밖에 존재하므로 Git에서 추적되지 않습니다. 이때는 ignore 설정이 치명적이진 않지만, 다음 사항은 여전히 확인하는 것이 좋습니다.

• 여러 머신에서 경로가 일관되게 유지되거나, 팀원을 위해 문서화되어 있는지
• 여러 개의 전체 worktree를 저장할 수 있을 만큼 디스크 공간이 충분한지

이러한 검증 단계를 꾸준히 적용하면, Git 히스토리를 소스 코드 변경에만 집중시키고, 도구 관련 산출물은 밖으로 분리해 둘 수 있습니다.

내 워크플로에 맞게 스킬 적용하기

using-git-worktrees는 의도적으로 가볍고, 개별 리포지토리 중심으로 설계되어 있습니다. 이를 더 넓은 워크플로에 통합하고 싶다면 다음을 고려해 보세요.

• 최종적으로 선택한 worktree 디렉터리를 프로젝트 기여 가이드나 온보딩 문서에 명시합니다.
• 팀에서 Git worktree를 어떻게 사용하는지 CLAUDE.md에 짧은 섹션을 추가해 문서화할 수 있습니다.
• 디렉터리 선택과 안전성 검증 단계를 하나의 셸 스크립트로 감싸, 한 번의 명령으로 설정되도록 만들되, 원래 규칙을 기준으로 유지·관리합니다.

이 스킬은 그대로 따라 쓸 수 있는 "참고 구현(reference implementation)"을 제공하는 것을 목표로 하며, 환경에 맞게 신중하게 변형해 사용하는 것도 염두에 두고 설계되어 있습니다.

자주 묻는 질문(FAQ)

using-git-worktrees를 일반적인 Git checkout과 비교했을 때 가장 큰 장점은 무엇인가요?

using-git-worktrees는 동일한 Git 히스토리를 공유하는 추가 작업 디렉터리(worktree)를 만들어, 여러 브랜치를 병렬로 쉽게 작업할 수 있게 해 줍니다. 하나의 디렉터리에서 반복적으로 checkout과 stash를 오가며 작업하는 대신, 각 기능이나 수정 작업을 자체적으로 분리된 작업 공간에 두고, 일관된 디렉터리 선택 및 안전성 검증 프로세스의 도움을 받을 수 있습니다.

using-git-worktrees 스킬은 어떻게 설치하나요?

다음 명령을 사용해 obra/superpowers 리포지토리에서 스킬을 설치합니다.

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

설치가 끝나면 로컬 체크아웃에서 skills/using-git-worktrees/SKILL.md 파일을 열어, 자세한 워크플로를 단계별로 따라가면 됩니다.

이 스킬을 쓰려면 기존 Git 워크플로를 크게 바꿔야 하나요?

전체 워크플로를 갈아엎을 필요는 없습니다. using-git-worktrees는 주로 분리된 작업 공간을 어떻게 시작하고 관리할지에 초점을 맞추고 있습니다. 커밋, rebase, push 등은 평소처럼 진행하면 되고, 이 스킬은 어디에, 어떤 방식으로 worktree를 만들지 표준화하고, 안전한 위치에만 생성하도록 도와주는 역할을 합니다.

어떤 Git 리포지토리에서도 using-git-worktrees를 사용할 수 있나요?

일반적으로 Git worktree 기능을 지원하는 리포지토리라면 어디서든 사용할 수 있습니다. 스킬은 표준 Git 명령과 셸 유틸리티에만 의존합니다. 최선의 결과를 얻으려면 리포지토리 루트에서 디렉터리 체크를 수행하고, 프로젝트 로컬 worktree 디렉터리에 대해서는 ignore 설정 권장 사항을 따르세요.

이미 다른 worktree 관례가 있는 프로젝트에는 어떻게 적용하나요?

이미 .worktrees, worktrees, 또는 CLAUDE.md에 문서화된 관례를 사용하고 있다면, using-git-worktrees는 디렉터리 선택 규칙을 통해 자연스럽게 그 선호도를 따라가게 됩니다. 전혀 다른 규칙을 쓰는 프로젝트라면, 이 스킬의 핵심 원칙(분명한 디렉터리 선택과 안전성 검증)은 그대로 활용하되, 실제 디렉터리 레이아웃은 기존 방식에 맞게 조정해 적용할 수 있습니다.

using-git-worktrees는 규모가 크거나 장기 운영되는 프로젝트에도 적합한가요?

네. 여러 개의 장기 브랜치가 공존하는 대규모 프로젝트에서 특히 유용합니다. 구조화된 디렉터리 선택 규칙과 ignore 설정에 대한 강조 덕분에, 많은 worktree를 장기간 유지하더라도 리포지토리가 정돈된 상태를 유지하는 데 도움이 됩니다.

언제 using-git-worktrees 사용을 피하는 것이 좋을까요?

한 번에 하나의 브랜치에서만 작업하는 편이고, 병렬 작업이 거의 없다면 이 스킬의 이점을 크게 느끼지 못할 수 있습니다. 또한 팀이 이미 worktree를 관리하는 전용 도구를 사용하고 있고, 그 도구가 자체 디렉터리 관례를 강하게 강제하고 있다면, 이 스킬에서 제공하는 추가 구조가 현재 습관을 바꿀 만큼 큰 가치를 주지 않을 수 있습니다.

이 스킬의 원본 정의는 어디에서 확인할 수 있나요?

using-git-worktrees의 권위 있는 정의는 GitHub의 obra/superpowers 리포지토리 내 skills/using-git-worktrees 디렉터리에 있는 SKILL.md 파일에 있습니다. 가장 정확하고 최신의 동작 설명이 필요하다면, 해당 파일을 참조하세요.