worktree-setup

name	worktree-setup
description	git worktree에서 메인 레포의 환경 설정이 필요할 때. — MUST TRIGGER: 새 worktree 진입 직후, 사용자가 '환경변수 안 읽힘·시크릿 못 찾음'을 보고할 때, EnterWorktree 도구 호출 직후.
description_en	Use when the main repo's environment setup is needed inside a git worktree. — MUST TRIGGER: right after entering a new worktree, when the user reports 'env vars not read' or 'secrets not found', or right after the EnterWorktree tool is called.
user-invocable	false

Nova Worktree Setup

git worktree는 기본적으로 gitignored 파일(.env, .secret/, .npmrc 등)을 새 작업 디렉토리로 복사하지 않는다. 그래서 worktree를 만들면 환경변수·시크릿·레지스트리 토큰이 통째로 사라진 채 세션이 시작된다. 이 스킬은 그 갭을 닫는다 — 병렬 에이전트가 같은 환경으로 바로 일할 수 있게.

동작

1. SessionStart 훅이 자동 실행한다 (hooks/worktree-setup.sh). 설치만 하면 끝. opt-in 불필요.

2. 메인 레포를 감지한다: CONDUCTOR_ROOT_PATH → git worktree list 첫 항목 순서.

3. 메인 레포에서 다음 항목을 worktree 루트로 심볼릭 링크한다 (존재하면 skip, 멱등):

   기본 대상	타입	용도
   .env	파일	기본 환경변수
   .env.local	파일	로컬 오버라이드
   .env.development	파일	개발 환경
   .secret	디렉토리	시크릿 디렉토리 (SWK 컨벤션)
   .npmrc	파일	프라이빗 레지스트리 토큰

   .env.production은 기본 대상에서 제외한다. 운영 시크릿을 worktree에 노출하는 사고를 막기 위해 — 필요 시 worktree-sync.json에 명시.

4. 이미 존재하는 파일·심링크는 절대 덮어쓰지 않는다. 재실행도 안전.

5. 깨진 심링크 감지: worktree에 이미 심링크가 있지만 대상이 사라진 경우(예: 메인 레포에서 .env 삭제 후 worktree 심링크만 남음), 자동 교체는 하지 않고 stderr에 경고를 출력한다. 사용자가 readlink로 대상을 확인하고 수동 대응한다.

프로젝트별 오버라이드

프로젝트 루트에 .claude/worktree-sync.json을 두면 기본 대상을 교체한다:

{
  "links": [".env", ".env.local", "config/secrets.json", ".npmrc", ".envrc"]
}

• 절대 경로(/...)는 무시된다.
• 경로 세그먼트 ..(상위 디렉토리 이동)이 포함되면 무시된다. 단 파일명 안의 .. 문자열(예: .env..backup)은 허용된다.
• 경로는 메인 레포 루트 기준의 상대 경로다.
• links가 있으면 기본 5종 대신 이 목록만 사용한다 (교체 방식).

트리거 조건

• 자동: SessionStart 훅이 매번 실행 (멱등)
• 수동: 사용자가 /nova:worktree-setup 호출 시 즉시 재시도
• 장애: 사용자가 "env 못 찾음", "시크릿 안 읽힘", ".env가 비었다"를 보고하면 worktree 상황을 의심하고 이 스킬의 동작을 확인한다

런타임 감지 체크리스트

사용자가 환경 문제를 보고할 때 확인할 것:

1. git worktree list — 현재 메인 레포인지 worktree인지 확인
2. ls -la .env .secret/ .npmrc — 심링크가 걸려있는지, 링크 대상이 존재하는지
3. readlink -f .env (Linux) / readlink .env (macOS) — 링크 대상 경로 확인
4. 메인 레포의 파일이 존재하는지 (.env 자체가 메인에도 없으면 링크 대상이 없음)

분기 ref 선택 (worktree.baseRef, CC v2.1.133+)

Claude Code v2.1.133부터 --worktree/EnterWorktree/agent-isolation 워크트리가 어느 ref에서 분기할지 settings.json worktree.baseRef로 명시 선택할 수 있다.

타임라인: v2.1.128에서 EnterWorktree가 origin/<default> 대신 로컬 HEAD에서 분기하도록 동작이 수정됐고(unpushed 커밋 누락 차단), v2.1.133에서 사용자가 head vs fresh를 명시 선택할 수 있는 설정이 도입됐다. v2.1.128~v2.1.132 구간에는 본 설정 자체가 없다.

값 (v2.1.133+)	동작	Nova 권장 사용처
head	로컬 HEAD에서 분기 — unpushed 커밋 포함	기본 권장 (Nova의 incremental 작업 흐름과 일치, v2.1.128 이후 사실상 기본 동작과 동일).
fresh	origin/<default>에서 분기 — 깨끗한 원격 기준	release-track 검증, hot-fix 분기, "메인이 깨끗한 상태에서 시작하고 싶다"는 의도가 명확할 때.

설정 예시 (~/.claude/settings.json 또는 프로젝트 .claude/settings.json):

{
  "worktree": {
    "baseRef": "head"
  }
}

이 스킬(worktree-setup)은 셋업 담당이고, 분기 ref는 Claude Code 자체 설정이다. baseRef는 본 스킬이 자동 변경하지 않는다 — 사용자/팀의 settings.json 결정 영역.

범위 밖

• Windows junction 지원 — 1차는 macOS/Linux만
• direnv 자동 allow — 별도 스킬로 분리 예정
• worktree 생성 자체 (git worktree add) — 이 스킬은 셋업만 담당, 생성은 사용자·Claude의 EnterWorktree 도구가 수행

사용자 가이드

사용자가 "어떻게 쓰는지" 질문하면 먼저 docs/guides/worktree-setup.md 를 안내한다. Quick Start, 오버라이드 예제, 트러블슈팅(깨진 심링크·jq 미설치·Windows 한계), 보안 모델까지 사용자 관점에서 정리되어 있다.

참고

• hooks/worktree-setup.sh — 실제 스크립트
• commands/worktree-setup.md — /nova:worktree-setup 수동 실행
• docs/guides/worktree-setup.md — 사용자 가이드 (Quick Start · 오버라이드 예제 · 트러블슈팅)
• CONDUCTOR_ROOT_PATH — Conductor 워크스페이스 환경에서 자동 제공되는 메인 레포 경로