eoash git worktree 격리 스킬
여러 Claude/Codex 세션을 동시에 돌릴 때 메인 체크아웃을 공유하면 서로의 uncommitted 변경·.next 빌드캐시를 조용히 덮어쓴다. 세션마다 격리된 worktree를 주면 소스·빌드·상태가 물리적으로 분리되어 충돌이 원천 차단된다.
왜: 2026-06-10 두 Claude 세션이 메인 체크아웃에서 동시 작업 → 한쪽 edit가 다른 쪽을 덮어쓸 뻔함. worktree 격리로 재발 차단.
스크립트 (설치 경로)
# Claude Code
~/.claude/skills/worktree/scripts/wt-new.sh <branch> [base=main]
~/.claude/skills/worktree/scripts/wt-ls.sh [--mine|--prune]
~/.claude/skills/worktree/scripts/wt-done.sh <branch> [--force]
# Codex
~/.codex/skills/worktree/scripts/wt-new.sh <branch> [base=main]
레포에 커밋된 동일 도구가 scripts/tools/wt-*.sh에도 있다(eoash 한정). 스크립트는 git rev-parse --show-toplevel로 repo root를 찾으므로 CWD가 어느 git 레포든 그 레포 기준으로 동작한다.
표준 워크플로우
# 1) 세션용 worktree 생성 (origin/main 에서 새 브랜치 분기 + node_modules 심링크)
~/.claude/skills/worktree/scripts/wt-new.sh fix/foo
# 2) 그 디렉토리에서 새 세션 시작 → 메인·타 세션과 충돌 0
cd ~/Documents/<repo>-worktrees/fix-foo && claude
# 3) 작업 → 커밋 → 푸시 → PR (worktree 안에서)
git add <파일> && git commit -m "..." && git push -u origin fix/foo && gh pr create
# 4) PR 머지 후 정리
~/.claude/skills/worktree/scripts/wt-done.sh fix/foo
동작 요약
- wt-new: 레포 바깥 sibling
<repo>-worktrees/<slug>에 worktree 생성,origin/<base>에서 분기(기존 브랜치면 체크아웃). 루트+각 워크스페이스node_modules·.env를 메인 체크아웃에서 심링크(npm install/cp 불필요). - wt-ls: 전체 worktree 현황 —
clean/DIRTY(미커밋)/↑N(미푸시)/PRUNABLE(디렉토리 사라짐).--mine은 이 스킬이 만든 것만,--prune은 좀비 정리. - wt-done: 미커밋·미푸시 가드 통과 시에만 제거(
--force로 강제). 브랜치 ref·커밋은 보존(작업 디렉토리만 삭제).
🚨 가드레일 / 함정 (반드시 지킬 것)
- worktree에서
npm install금지 — node_modules가 심링크라 메인 체크아웃을 오염시킴. - 배포는 git push 경로만,
vercel --prodCLI 금지 — 심링크 node_modules는 CLI 업로드 시ENOTDIR,.vercelignore !.git은 fsmonitor 소켓으로 깨짐. 원격 git-integration 빌드는 클린 체크아웃이라 무관. - clean한 worktree는 제거해도 커밋 손실 0 —
git worktree remove는 작업 디렉토리만 지우고 브랜치 ref·커밋은.git에 남음. 진짜 위험은 **DIRTY(미커밋)**뿐. - 심링크 node_modules는
git status에?? node_modules로 뜸 — gitignorenode_modules/(디렉토리 패턴)가 심링크를 안 가림. 절대git add하지 말 것. wt-ls/wt-done은 경로 기반 필터로 이 노이즈를 제외함. - npm workspaces 자기참조 — 루트
node_modules/<ws>는 메인 소스를 가리킴. 앱을 직접 빌드(cd <app> && next build)하면 CWD·@/*에서 잡혀 안전. 워크스페이스를 패키지명으로 import하면 메인 소스를 읽을 수 있음.
상세 함정 카탈로그·설계 결정: 레포 docs/git-worktree-parallel.md 참조.