| 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를 만들면 환경변수·시크릿·레지스트리 토큰이 통째로 사라진 채 세션이 시작된다. 이 스킬은 그 갭을 닫는다 — 병렬 에이전트가 같은 환경으로 바로 일할 수 있게.
동작
-
SessionStart 훅이 자동 실행한다 (hooks/worktree-setup.sh). 설치만 하면 끝. opt-in 불필요.
-
메인 레포를 감지한다: CONDUCTOR_ROOT_PATH → git worktree list 첫 항목 순서.
-
메인 레포에서 다음 항목을 worktree 루트로 심볼릭 링크한다 (존재하면 skip, 멱등):
| 기본 대상 | 타입 | 용도 |
|---|
.env | 파일 | 기본 환경변수 |
.env.local | 파일 | 로컬 오버라이드 |
.env.development | 파일 | 개발 환경 |
.secret | 디렉토리 | 시크릿 디렉토리 (SWK 컨벤션) |
.npmrc | 파일 | 프라이빗 레지스트리 토큰 |
.env.production은 기본 대상에서 제외한다. 운영 시크릿을 worktree에 노출하는 사고를 막기 위해 — 필요 시 worktree-sync.json에 명시.
-
이미 존재하는 파일·심링크는 절대 덮어쓰지 않는다. 재실행도 안전.
-
깨진 심링크 감지: 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 상황을 의심하고 이 스킬의 동작을 확인한다
런타임 감지 체크리스트
사용자가 환경 문제를 보고할 때 확인할 것:
git worktree list — 현재 메인 레포인지 worktree인지 확인ls -la .env .secret/ .npmrc — 심링크가 걸려있는지, 링크 대상이 존재하는지readlink -f .env (Linux) / readlink .env (macOS) — 링크 대상 경로 확인- 메인 레포의 파일이 존재하는지 (
.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 워크스페이스 환경에서 자동 제공되는 메인 레포 경로
