القائمة
git worktree에서 메인 레포의 환경 설정이 필요할 때. — MUST TRIGGER: 새 worktree 진입 직후, 사용자가 '환경변수 안 읽힘·시크릿 못 찾음'을 보고할 때, EnterWorktree 도구 호출 직후.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
세션 간 맥락을 연결해야 할 때. — MUST TRIGGER: 세션 시작 시 NOVA-STATE.md 읽기, 커밋 후 상태 갱신, 스프린트 전환 시.
Nova 자체를 진화시킬 때 사용한다. — MUST TRIGGER: /nova:evolve 호출, 외부 기술 동향을 Nova에 반영해야 할 때, Nova 메타-개선(규칙/스킬/훅 구조 변경) 작업.
단일 Evaluator의 편향이 우려되는 중요 판단일 때 여러 관점으로 재검토한다. — MUST TRIGGER: 아키텍처 결정, 릴리스 게이트 의심 케이스, 사용자가 /nova:ask 또는 다관점 평가를 요청할 때.
새 Nova 스킬을 작성하거나 기존 스킬 description을 수정할 때. — MUST TRIGGER: skills/ 하위 신규 SKILL.md 생성, 기존 SKILL description 리팩터, 사용자가 'Nova 스킬 추가/수정' 요청 시.
Nova 방법론을 실제 프로젝트에서 검증해 개선 포인트를 찾을 때. — MUST TRIGGER: 신규 Nova 기능 검증, 사용자가 실전 피드백을 요청할 때, 워크트리 격리 환경에서 방법론을 리허설할 때.
자연어 요청을 받아 전체 개발 사이클을 자동 처리해야 할 때. — MUST TRIGGER: /nova:auto 호출, 사용자가 '전체 알아서 해줘' 유형의 요청을 할 때, 다중 에이전트 편성이 필요한 복합 작업.
| 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 |
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종 대신 이 목록만 사용한다 (교체 방식)./nova:worktree-setup 호출 시 즉시 재시도사용자가 환경 문제를 보고할 때 확인할 것:
git worktree list — 현재 메인 레포인지 worktree인지 확인ls -la .env .secret/ .npmrc — 심링크가 걸려있는지, 링크 대상이 존재하는지readlink -f .env (Linux) / readlink .env (macOS) — 링크 대상 경로 확인.env 자체가 메인에도 없으면 링크 대상이 없음)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에서 사용자가headvsfresh를 명시 선택할 수 있는 설정이 도입됐다. 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 결정 영역.
junction 지원 — 1차는 macOS/Linux만allow — 별도 스킬로 분리 예정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 워크스페이스 환경에서 자동 제공되는 메인 레포 경로