using-git-worktrees

using-git-worktrees 스킬 개요

using-git-worktrees 스킬이 하는 일

using-git-worktrees 스킬은 현재 checkout을 재사용하는 대신, 새로운 작업을 위한 별도의 Git worktree를 만들도록 에이전트를 돕습니다. 핵심은 단순히 git worktree add를 실행하는 데 있지 않습니다. 적절한 디렉터리를 고르고, 로컬 worktree 폴더가 안전하게 ignore되는지 확인하고, 메인 작업 공간이 오염되지 않게 하는 것이 이 스킬의 실제 역할입니다.

누가 설치하면 좋은가

이 스킬은 다음과 같은 작업을 자주 하는 사람에게 특히 잘 맞습니다.

• 현재 변경 사항은 그대로 둔 채 새 기능 작업을 시작한다
• 여러 브랜치를 병렬로 리뷰하거나 구현한다
• 브랜치 전환 실수를 줄인 더 안전한 AI 기반 코딩 워크플로를 원한다
• 프로젝트마다 일관된 방식으로 격리된 작업 공간을 만들고 싶다

평소 어시스턴트에게 “이건 별도 브랜치에서 시작해줘” 또는 “현재 트리는 건드리지 말고 작업해줘”라고 자주 요청한다면, using-git-worktrees는 매우 적합한 선택입니다.

해결하려는 작업

사용자가 원하는 결과는 하나입니다. 설정 실수를 최소화하면서 격리된 작업 공간에서 바로 구현을 시작하는 것. using-git-worktrees 스킬이 유용한 이유는 생성 전에 판단 단계를 넣어주기 때문입니다.

• 기존 프로젝트 worktree 디렉터리가 있으면 우선 사용
• CLAUDE.md에 저장소 선호 설정이 문서화되어 있으면 그 규칙을 따름
• 안전한 기본값이 없으면 사용자에게 물어봄
• 프로젝트 로컬 worktree를 만들기 전에 ignore 동작을 검증

즉, 곧바로 셸 명령으로 뛰어드는 일반 프롬프트보다 더 신뢰할 수 있습니다.

일반 프롬프트와 다른 점

일반 프롬프트도 Git worktree 개념 자체는 알고 있을 수 있지만, 저장소별 설정 디테일은 놓치기 쉽습니다. 이 스킬은 특히 디렉터리 배치와 .gitignore 처리와 관련해, 에이전트가 따라야 할 순서와 안전 점검을 명확히 제공합니다. using-git-worktrees for Git Workflows의 진짜 차별점은 Git 이론을 더 설명하는 데 있지 않고, 설정 과정의 추측을 줄여준다는 데 있습니다.

이 스킬이 잘 맞지 않는 경우

다음에 해당한다면 using-git-worktrees는 굳이 쓰지 않아도 됩니다.

• 항상 하나의 브랜치와 하나의 디렉터리에서만 작업한다
• 환경상 추가 작업 디렉터리를 둘 수 없다
• 격리 실행이 아니라 단순한 빠른 브랜치 전환만 필요하다
• 팀에 이미 이 판단 로직을 완전히 대체하는 고정 wrapper script가 있다

이런 경우에는 일반 셸 명령이나 기존 내부 워크플로가 더 빠를 수 있습니다.

using-git-worktrees 스킬 사용 방법

using-git-worktrees 설치 맥락

obra/superpowers 스킬 컬렉션에서 설치합니다.

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

설치 후에는 현재 checkout을 재사용하면 안 되는 작업을 시작하기 직전에 이 스킬을 쓰면 됩니다.

사용자는 실제로 어떻게 호출하나

이 저장소는 에이전트가 작업 시작 시 스킬 사용 사실을 명시하도록 분명하게 안내합니다. 실제로는 요청 문장에서 “격리가 필요하다”는 점이 드러나야 합니다. 예를 들면:

• “Use using-git-worktrees and set up an isolated workspace for this feature.”
• “Before implementing, create a worktree for branch feature/auth-refresh.”
• “Use the using-git-worktrees skill so my current changes stay untouched.”

이렇게 해야 에이전트가 임의로 처리하지 않고, 스킬 절차를 따를 가능성이 높아집니다.

이 스킬에 필요한 입력값

결과를 좋게 만들려면 다음 정보를 주는 것이 좋습니다.

• 대상 브랜치 이름
• 새 브랜치인지, 기존 브랜치인지
• 프로젝트 로컬 저장을 선호하는지, 글로벌 worktree 저장을 선호하는지
• “반드시 프로젝트 루트 아래여야 함” 같은 저장소별 제약

최소한 유용한 입력:

• 브랜치/작업 이름
• worktree 생성 권한

더 좋은 입력:

• 브랜치 이름
• 원하는 디렉터리 정책
• 현재 checkout에 uncommitted 작업이 있는지
• 설정 후 무엇을 할지, 예를 들어 “그다음 바로 구현 시작”

내장된 디렉터리 선택 로직

using-git-worktrees skill의 가장 큰 가치는 디렉터리 선택 워크플로에 있습니다. 우선순위는 다음과 같습니다.

1. .worktrees가 이미 있으면 사용
2. 없으면 worktrees가 있는지 확인하고 있으면 사용
3. 둘 다 없으면 CLAUDE.md에서 문서화된 선호 규칙 확인
4. 그래도 없으면 사용자에게 다음 중 선택 요청
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

이 부분이 중요한 이유는, 세션마다 새 위치를 제멋대로 만들기 시작하면 worktree가 금방 관리 부담으로 번지기 때문입니다.

프로젝트 로컬 생성 전에 하는 안전 점검

도입 시 꼭 알아둘 점이 있습니다. worktree를 저장소 내부에 둘 경우, 이 스킬은 해당 디렉터리가 ignore되는지 검증한 뒤에만 생성합니다. 덕분에 worktree 폴더가 실수로 추적되거나 git status 출력이 지저분해지는 상황을 막을 수 있습니다.

이는 즉흥적인 사용 방식보다 분명한 장점입니다. 팀에서 프로젝트 로컬 worktree를 기대한다면, 이 워크플로에 의존하기 전에 .worktrees/ 또는 worktrees/가 Git에서 ignore되도록 미리 설정해 두는 편이 좋습니다.

using-git-worktrees 사용을 위한 강한 프롬프트 패턴

약한 프롬프트:

• “Start working on OAuth cleanup.”

더 강한 프롬프트:

• “Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.”

왜 더 좋은가:

• 스킬 이름을 명시함
• 대상 브랜치를 지정함
• 디렉터리 선호를 알려줌
• 설정 후 다음 동작까지 지시함

생성 후 추천 워크플로

using-git-worktrees usage를 실무적으로 쓰려면 다음 순서가 좋습니다.

1. 에이전트에게 스킬 사용을 요청
2. worktree 위치와 브랜치 이름을 확인
3. 에이전트가 새 작업 공간으로 옮겨 작업하게 함
4. 그다음에야 수정, 테스트, 구현 계획을 시작

현재 checkout에 이미 uncommitted 변경 사항이 있는 경우, 이 순서가 특히 유용합니다.

저장소에서 먼저 읽어야 할 파일

실질적으로 의미 있는 소스 파일은 하나뿐입니다. 바로 SKILL.md입니다.

여기서 확인할 내용:

• 정확한 디렉터리 우선순위
• 선호 규칙이 없을 때 사용자에게 어떻게 물어보는지
• ignore 검증 요구사항
• 에이전트가 스킬 사용을 먼저 알리도록 하는 활성화 문구

이 스킬은 매우 가볍기 때문에, 실제 도입 판단의 핵심은 이 로직이 팀의 Git 워크플로와 맞는지 여부입니다.

의존하기 전에 알아둘 실무 제약

이 스킬은 의도적으로 범위가 좁습니다. 다음 기능은 제공하지 않는 것으로 보입니다.

• wrapper scripts
• 자동화 헬퍼
• 브랜치 이름 규칙 강제
• 오래된 worktree 정리 루틴
• 플랫폼별 fallback

즉, using-git-worktrees install이 제공하는 것은 판단 가이드이지, 완전한 worktree 관리 시스템이 아닙니다. 라이프사이클 자동화까지 필요하다면 자체 셸 도구와 함께 써야 합니다.

using-git-worktrees 스킬 FAQ

using-git-worktrees는 초보자에게도 좋은가

그렇습니다. 기본적인 브랜치 개념은 이해하고 있고, “현재 작업 공간은 건드리지 않는” 더 안전한 워크플로를 원하는 초보자에게는 도움이 됩니다. 다만 이것은 Git 튜토리얼이 아니라 구조화된 설정 스킬입니다. 완전 초보자라면 worktree가 무엇인지, clone과 왜 다른지부터 추가 설명이 필요할 수 있습니다.

일반 프롬프트보다 어떤 문제를 더 잘 해결하나

일반 프롬프트는 종종 가장 까다로운 부분을 건너뜁니다. worktree를 어디에 둘지, 프로젝트 로컬 디렉터리가 안전하게 ignore되는지 같은 부분입니다. 스킬에 담긴 using-git-worktrees guide는 이런 설정 실수를 줄이고, 에이전트 동작을 더 일관되게 만듭니다.

이걸 쓰려면 프로젝트 로컬 worktree가 꼭 필요한가

아니요. 로컬 디렉터리가 없고 저장소에 선호 규칙도 문서화되어 있지 않다면, 이 스킬은 글로벌 위치로 유도할 수 있습니다. 그래서 저장소 안에 추가 폴더를 만들고 싶지 않은 경우에도 사용할 수 있습니다.

기존 브랜치에도 using-git-worktrees를 쓸 수 있나

네. 기존 브랜치를 별도의 작업 공간에 checkout할 때도 이 워크플로는 유효합니다. 핵심 가치는 새 브랜치 생성 자체보다 격리에 있습니다.

언제 using-git-worktrees를 쓰지 말아야 하나

다음 상황에서는 쓰지 않는 편이 낫습니다.

• 현재 브랜치에서 아주 작은 수정만 하면 된다
• 팀에서 관리되지 않는 worktree 위치를 금지한다
• 위치와 ignore 규칙을 처리하는 결정론적 내부 도구가 이미 있다
• 저장소에 이 스킬이 알지 못하는 특수한 Git 제약이 있다

이것이 Git 지식을 대체하나

아니요. using-git-worktrees skill은 호출 방식과 설정 규율을 개선해 주지만, 브랜치 이름 결정, rebase, 정리, merge 전략 같은 기본 Git 판단은 여전히 사용자가 할 수 있어야 합니다.

using-git-worktrees 스킬 개선 방법

브랜치와 디렉터리 의도를 명확히 전달하라

가장 큰 품질 향상 포인트는 에이전트에게 브랜치 대상과 원하는 디렉터리 정책을 함께 알려주는 것입니다. 예:

“Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.”

이렇게 하면 가장 흔한 모호성을 제거할 수 있습니다.

CLAUDE.md에 선호 규칙을 문서화하라

이 스킬은 CLAUDE.md를 확인하므로, 앞으로의 결과 품질을 높이고 싶다면 다음을 문서화해 두는 것이 좋습니다.

• 선호하는 worktree 디렉터리
• 프로젝트 로컬 worktree 허용 여부
• 브랜치 또는 폴더 이름 규칙

이렇게 하면 매번 사용자에게 다시 확인받던 내용이 저장소 수준 정책으로 바뀝니다.

로컬 디렉터리용 ignore 규칙을 미리 설정하라

팀에서 프로젝트 내부의 .worktrees/ 또는 worktrees/를 쓰고 싶다면, ignore 규칙을 사전에 추가해 두세요. 그러면 using-git-worktrees for Git Workflows 경로가 훨씬 매끄러워집니다. 작업 도중 안전 검증 때문에 멈춰서 논의하지 않아도 되기 때문입니다.

자주 생기는 실패 패턴을 주의하라

대표적인 실패 패턴은 비교적 예측 가능합니다.

• 에이전트가 승인되지 않은 위치에 worktree를 만든다
• 로컬 worktree 폴더가 ignore되지 않는다
• 모호한 기능 요청 때문에 브랜치 이름을 잘못 추론한다
• 격리가 끝나기 전에 원래 checkout에서 구현을 시작한다

이 문제 대부분은 스킬 자체보다 불완전한 프롬프트에서 비롯됩니다.

코딩 시작 전 확인을 요청하라

간단하지만 효과적인 개선 프롬프트:

• “Use using-git-worktrees, then report the final path and branch before making edits.”

이렇게 하면 초기에 실수를 잡아낼 수 있고, 특히 중첩 폴더가 많거나 정책이 특이한 저장소에서 유용합니다.

첫 실행 후 패턴을 다듬어라

첫 결과가 완전히 나쁘진 않지만 이상적이지도 않다면, 전부 다시 쓰기보다 작업 패턴을 다듬는 편이 낫습니다.

• 선호하는 디렉터리 위치를 고정
• CLAUDE.md에 메모 추가
• 프롬프트에서 브랜치 이름 규칙 표준화
• 수정 전에 반드시 확인하도록 명시

이렇게 하면 시간이 갈수록 using-git-worktrees usage가 더 예측 가능해지고, 반복되는 설정 마찰도 줄어듭니다.