Claude Code worktree skills 로딩: 격리 세션에서도 팀 절차 유지하기 | DAKER 커뮤니티

Claude Code worktree skills 로딩: 격리 세션에서도 팀 절차 유지하기

Claude Code worktree skills 로딩이란, 별도 git worktree 세션에서도 프로젝트의 .claude/skills와 custom agents를 찾아 같은 팀 절차를 쓰는 흐름입니다. 2026년 6월 22일 기준 공식 changelog 2.1.183은 git worktree에서 project-level agents와 skills가 발견되지 않던 문제를 수정했다고 설명합니다.

_이미지: 클로드 코드 worktree 격리 세션에서 main repository의 skills와 agents를 발견해 검증하는 흐름._

Claude Code worktree에서 왜 skills 로딩을 먼저 확인해야 할까?

한 줄 요약: worktree는 파일을 격리하지만, 팀 절차까지 빠지면 같은 자동화가 다른 규칙으로 실행됩니다.

worktree는 병렬 작업을 안전하게 나누는 좋은 표면입니다. 하지만 팀이 .claude/skills에 리뷰 절차, 실행 레시피, 배포 전 점검을 넣어 두었다면 worktree 세션에서도 그 절차가 보여야 합니다. 로딩이 빠지면 같은 Claude Code 작업이라도 main checkout과 worktree가 서로 다른 기준으로 움직입니다.

DAKER의 worktree로 병렬 세션 안전하게 굴리기는 격리 자체를 다뤘고, Output Style로 답변 형식과 톤 고정하기는 세션별 응답 기준을 고정하는 방법을 다뤘습니다. 오늘은 두 주제를 합쳐 “격리 세션에서도 절차가 유지되는가”를 확인합니다.

changelog 2.1.183에서 무엇이 바뀌었나?

공식 changelog 2.1.183은 git worktree에서 custom agents와 skills가 발견되지 않던 문제를 수정했다고 설명합니다. project-level .claude/agents/와 .claude/skills/가 main repository에서 포함되는 것이 핵심입니다.

실무적으로는 아래 세 가지 확인이 필요합니다.

확인 항목	봐야 할 것	실패하면 생기는 문제
`.claude/skills`	slash command 또는 skills 목록에 보이는가	리뷰·실행 절차 누락
`.claude/agents`	custom agent가 위임 후보로 보이는가	병렬 조사/검증 역할 누락
`.worktreeinclude`	`.env` 등 gitignored 파일이 복사되는가	테스트와 로컬 실행 실패
test command	worktree 안에서 독립 실행되는가	main checkout에 의존

단계별 사용법: worktree 세션을 어떻게 점검하나?

main repository에 .claude/skills/<name>/SKILL.md와 필요한 custom agent를 둡니다.
worktree가 필요한 작업은 --worktree 또는 세션 중 worktree 이동으로 시작합니다.
worktree 안에서 /context, slash-command autocomplete, agent 목록을 확인합니다.
.env, local config가 필요하면 .worktreeinclude에 gitignored 파일 패턴을 적습니다.
팀 공통 실행 명령을 worktree 안에서 한 번 실행합니다.
결과를 main checkout에 합류하기 전 diff, 테스트, 남은 리스크로 보고합니다.

_이미지: 클로드 코드 worktree 시작 전 skills, agents, .worktreeinclude, 테스트 명령을 확인하는 팀 체크리스트._

짧은 예시: 팀에 남길 worktree 지시문

이 작업은 Claude Code worktree에서 진행해줘.

시작 후 확인:
- project .claude/skills가 보이는지 확인한다.
- custom agents가 로드되는지 확인한다.
- .worktreeinclude로 필요한 .env 예시 파일이 들어왔는지 본다.
- 테스트 명령을 worktree 안에서 실행한다.

완료 보고:
- 어떤 skill/agent를 사용했는지
- 어떤 테스트를 실행했는지
- main checkout으로 합류하기 전 남은 위험

이 지시문의 목적은 Claude에게 “격리해서 해줘”만 말하는 것이 아닙니다. 격리된 환경에서도 팀의 절차와 검증 기준을 유지하라는 계약을 넣는 것입니다.

팀 적용 체크리스트: worktree와 skills를 같이 쓰려면?

.claude/skills에는 반복 가능한 실행·검증 절차만 둔다.
.claude/agents에는 독립 조사, 코드 리뷰, 테스트 보강처럼 역할이 분명한 agent만 둔다.
.worktreeinclude에는 필요한 gitignored 파일만 최소로 복사한다.
secrets 원본을 무조건 복사하지 말고 example 또는 local-only 파일을 구분한다.
worktree에서 통과한 테스트와 main checkout에서 필요한 추가 QA를 나눈다.
worktree 정리는 변경 여부, untracked 파일, branch 상태를 확인한 뒤 한다.

공식 출처: 2026년 6월 22일 확인

공식 Claude Code changelog 2.1.183, worktrees, skills 문서를 기준으로 확인했습니다. 공개 본문에는 DAKER 내부 링크만 남겼습니다.

FAQ: Claude Code worktree skills 로딩

worktree는 main repository와 무엇을 공유하나요?

git history와 remote는 공유하지만 working directory는 별도입니다. 그래서 파일 변경은 격리되지만, 필요한 설정과 local files가 자동으로 모두 따라오는 것은 아닙니다.

`.claude/skills`와 `.claude/commands`는 어떻게 다르나요?

공식 문서 기준 custom commands는 skills로 통합되었습니다. 기존 .claude/commands는 계속 동작하지만, 새 절차는 supporting files를 둘 수 있는 .claude/skills/<name>/SKILL.md 형식이 더 적합합니다.

worktree에서 `.env`가 없으면 어떻게 하나요?

.worktreeinclude에 gitignored 파일 패턴을 넣어 복사할 수 있습니다. 다만 실제 비밀값을 무조건 복사하지 말고, 팀 정책에 맞게 example 파일과 local-only 파일을 구분하세요.

custom agent가 안 보이면 무엇부터 확인하나요?

Claude Code 버전, 시작 위치, project-level .claude/agents 위치, workspace trust 상태를 먼저 봅니다. 그다음 main checkout과 worktree에서 같은 agent가 보이는지 비교하세요.

다음 병렬 작업을 시작할 때는 “worktree에서 시작”과 함께 “skills와 agents 로딩 확인”을 첫 단계로 넣어 보세요.