Git Worktree
어떤 worktree도 사용자가 위치, 출처, 종료 방법을 모른 채 생성되지 않습니다. 어떤 worktree도 사용자가 요청하지 않고 삭제되지 않습니다.
이 스킬은 worktree를 생성하는 다른 스킬(예: superpowers:using-git-worktrees)보다 세 가지 측면에서 우선합니다: 위치, 이름, 승인. 나머지 흐름은 다른 스킬을 따릅니다.
에이전트별 도구
| 액션 | Claude Code | Codex |
|---|---|---|
| 생성 | git worktree add + EnterWorktree(path: ...)로 세션 이동 | git worktree add + git -C/workdir로 worktree 작업 |
| 격리된 하위 에이전트 | Agent + isolation: "worktree" (.claude/worktrees/에 생성) | 해당 없음 |
| 종료 | ExitWorktree(action: "keep") | 원래 디렉토리로 돌아가기 |
| 보고서 | pwsh -NoProfile -File "<이 스킬 폴더>/scripts/worktrees-report.ps1" | 동일 |
<이 스킬 폴더>는 이 SKILL.md가 있는 디렉토리입니다. 스크립트는 PowerShell 7+ (pwsh)가 필요합니다.
1. 생성 전
- 이미 worktree에 있는지 확인하세요 (
git rev-parse --git-dir이git rev-parse --git-common-dir과 다르고, 서브모듈 내부가 아님). 그렇다면 사용자가 요청하지 않는 한 다른 worktree를 생성하지 마세요. - 관련 저장소에서 보고서를 실행하고 결과를 4단계를 위해 저장하세요:
pwsh -NoProfile -File "<이 스킬 폴더>/scripts/worktrees-report.ps1" -Path "<repo1>;<repo2>" - 아래 표준 규칙에 따라 계획을 세우고 worktree당 하나의 블록으로 제시하세요:
저장소에 서브모듈이 있으면 (Worktree 계획 - 저장소: C:\repos\loja - 기준 브랜치: origin/main @ 3f2a9c1 (git fetch 방금 실행) - 새 브랜치: claude/feat-login-google - 이름: feat-login-google - 절대 경로: C:\repos\loja\.worktrees\feat-login-google - 상대 경로: .worktrees\feat-login-google - 방법: git -C "C:\repos\loja" worktree add "C:\repos\loja\.worktrees\feat-login-google" -b claude/feat-login-google origin/main - 제거: git -C "C:\repos\loja" worktree remove "C:\repos\loja\.worktrees\feat-login-google" git -C "C:\repos\loja" branch -d claude/feat-login-google.gitmodules), 계획에 제거 시--force가 필요하고 그 이유를 알리세요. - 바로 아래에, 해당 저장소에 이미 열려 있는 worktree의 보고서 테이블을 표시하세요 (Worktree, 크기, 브랜치, 잃는 것). 없으면 한 줄로 알리세요.
- 사용자의 명시적인 OK를 기다리세요. 그런 다음에만 생성하세요. Claude Code에서는 플러그인 훅이 명령 실행 시 추가 확인을 요청합니다. Codex에서는
codex/rules/git-worktree.rules규칙이git worktree add에 대해 동일한 작업을 수행합니다.
여러 하위 에이전트를 병렬로 실행하는 경우, 모든 worktree가 포함된 단일 계획을 제시하고 OK를 한 번만 요청하세요.
표준 규칙
- 위치: 두 에이전트 모두
<저장소 루트>/.worktrees/<이름>. 예외는isolation: "worktree"를 사용하는 Claude Code 하위 에이전트로, 항상.claude/worktrees/에 생성합니다. 이 경우 해당 경로를 계획에 명시하세요. - 폴더 무시 확인: 생성 전에
git -C <repo> check-ignore -q .worktrees/x를 실행하세요. 폴더가 무시되지 않았다면,.worktrees/를 저장소의info/exclude파일에 추가하세요 (경로:git -C <repo> rev-parse --git-path info/exclude). 이 파일은 로컬 전용이며 커밋되지 않습니다. 추가했다고 알리세요. - 이름:
<타입>-<짧은-설명>, 케밥 케이스, 최대 40자. 예:feat-login-google,fix-timeout-pagamento. - 새 브랜치:
<에이전트>/<이름>, 즉claude/feat-login-google또는codex/feat-login-google. 저장소에 자체 브랜치 규칙(hook, CONTRIBUTING, 기록)이 있으면 저장소 규칙을 따르고 그 규칙이 무엇인지 말하세요. - 기준: 기본적으로 사용자가 메인 체크아웃에 있는 브랜치입니다. 작업이 해당 브랜치와 독립적이면
origin/<기본 브랜치>를 사용하세요.git fetch를 먼저 실행하고 기준의 짧은 해시를 표시하세요.
2. Worktree 보고서
사용자가 worktree를 나열하거나 정리하도록 요청할 때와 위 1.2단계에서 사용합니다.
pwsh -NoProfile -File "<이 스킬 폴더>/scripts/worktrees-report.ps1" [-Path "<루트 또는 repo>;..."] [-Json] [-SkipSize] [-Depth 6]
-Path없이 실행하면GIT_WORKTREE_ROOTS변수 또는 현재 디렉토리를 사용합니다. 사용자 지침(CLAUDE.md, AGENTS.md)이 저장소 루트 폴더를 정의하면 해당 폴더를 전달하세요.- 스크립트는 읽기 전용입니다. 저장소, 서브모듈, 저장소 폴더 외부의 분리된 worktree를 찾습니다.
- 사용자가 빠른 실행을 원하면
-SkipSize를 사용하세요. 세부 정보(ahead/behind 커밋, 원격 상태, 병합, 마지막 커밋 날짜, 평결 및 제거 명령어)가 필요하면-Json을 사용하세요.
스크립트가 출력하는 표를 정확히 이 네 열과 순서로 표시하세요:
| 열 | 내용 |
|---|---|
| Worktree | 절대 경로 |
| 크기 | 디스크 공간 |
| 브랜치 | Worktree의 브랜치, 또는 (detached @ <hash>) |
| 잃는 것 | 없음, 또는 삭제 시 사라지는 항목 목록: 커밋되지 않은 파일, 거기에만 존재하는 커밋, git이 무시하는 파일(예: .env). 빌드 폴더(node_modules, bin, obj...)는 제외 |
열을 추가하지 마세요. 세부 정보는 결정에 도움이 될 때만 표 아래에 표시하세요.
손실로 간주되는 항목:
- 변경되었거나 새로 추가되었지만 커밋되지 않은 파일.
- 어떤 원격, 현재 브랜치, 기본 브랜치에도 없는 커밋.
- 빌드 폴더가 아닌 무시된 파일.
- 초기화된 서브모듈: 커밋되지 않은 파일과 그 안에만 존재하는 커밋.
- 잠긴 worktree(
git worktree lock)는(잠김...)으로 표시되며 확인 없이 삭제되지 않습니다. - 폴더가 이미 존재하지 않으면 열에
없음 (폴더가 이미 존재하지 않음...)이라고 표시됩니다.git worktree prune으로 해결하세요. - 제한 사항: squash 또는 rebase 병합은 감지되지 않으므로 해당 커밋이 손실로 나타납니다. 사용자가 PR이 이미 병합되었다고 말하면 원격에서 확인하세요.
손실이 없는 worktree를 삭제했을 때 확보되는 공간으로 보고서를 마무리하세요.
제거 명령어
사용자가 삭제를 요청하거나 명령어를 요청하면 -Json의 ComandosRemocao 필드를 사용하세요. 명령어를 정확히, 순서대로, 하나의 블록으로 복사하세요. 명령어를 외워서 작성하지 마세요. 이 필드는 이미 세 가지 함정을 해결합니다:
- 무시된 파일: 손실되는 무시된 파일(예:
.env,.superpowers/)이 있으면 첫 번째 명령어가 이를~/worktree-backup/<repo>/<worktree>에 복사합니다. 복사는 제거 전에 이루어져야 합니다. 제거 후에는 복사할 파일이 없습니다. - 서브모듈: worktree에 초기화된 서브모듈이 있으면
--force와 함께 제거됩니다. git이git worktree remove를 거부하기 때문입니다. 이 명령어를 실행하기 전에 "잃는 것" 열에서 서브모듈이 아무것도 잃지 않거나 사용자가 손실을 수락했는지 확인하세요. - 브랜치: 마지막으로
git branch -d가 브랜치를 삭제합니다. 이미 통합된 경우에만 성공합니다.
직접 실행하는 경우 한 번에 하나의 명령어를 실행하고 첫 번째 오류에서 중지하세요.
3. 작업 완료 시
- worktree의 작업이 이미 통합되었으면(병합 또는 원격 푸시), 준비된 명령어와 함께 제거를 제안하세요.
- 통합되지 않았으면 누락된 사항(커밋, 푸시, PR)을 알리세요.
- Claude Code에서는
ExitWorktree(action: "keep")로 종료하고, OK 후에만 git으로 제거하세요.ExitWorktree(action: "remove")는EnterWorktree가 세션에서 생성한 worktree에만 작동합니다.
변경할 수 없는 규칙
- 사용자가 요청하지 않으면 worktree나 브랜치를 절대 삭제하지 마세요. 한 번에 하나씩 삭제하고 마지막에 보고서를 다시 실행하세요.
- 해당 worktree에 대한 명시적인 확인 없이
git branch -D또는ExitWorktree(discard_changes: true)를 절대 사용하지 마세요.git worktree remove --force는 worktree에 서브모듈이 있고("제거 명령어" 참조) 사용자가 잃는 것을 확인했을 때만 사용하세요. - 계획을 제시하고 OK를 받지 않고 worktree를 절대 생성하지 마세요.