Skip to content
LiveNew tools this week
Submit
AIMarketly
context-worktree logo

Context Worktree 스킬

context-worktree

새 작업 요청 시 기존 작업과의 맥락 유사성을 판단하고, 비유사한 경우 자동으로 git worktree를 생성하여 새 브랜치에서 작업합니다. 작업 시작, 새 기능 구현, 다른 이슈 작업 시 자동 활성화됩니다.

majiayu000/claude-skill-registry0installs662starsSecurity

SKILL.md

Full skill instructions

Context Worktree 스킬

Overview

새로운 작업 요청이 기존 작업과 맥락상 유사한지 판단하고, 비유사한 경우 git worktree를 통해 독립된 브랜치에서 작업하도록 자동 분리하는 스킬입니다.

핵심 기능:

  • 맥락 유사성 판단: 파일 경로, 커밋 히스토리, LLM 의미 분석을 통한 종합 판단
  • 자동 worktree 생성: 비유사 판단 시 자동으로 새 worktree 및 브랜치 생성
  • 작업 컨텍스트 분리: 독립적인 작업을 별도 공간에서 진행하여 충돌 방지
  • Git repo 검증: Git 저장소가 아닌 경우 자동 스킵

중요: Git 저장소가 아닌 디렉토리에서는 이 스킬이 적용되지 않습니다.

When to Use

이 스킬은 다음 상황에서 자동으로 활성화됩니다:

명시적 요청:

  • "새로운 기능 만들어줘"
  • "다른 이슈 작업해줘"
  • "이 버그 수정해줘" (현재 작업과 무관한 버그)
  • "worktree로 분리해줘"

자동 활성화:

  • 사용자가 구현 요청을 할 때
  • 기존 작업 브랜치에서 새로운 작업 시작 시
  • 긴급 핫픽스가 필요할 때

스킵 조건:

  • 현재 디렉토리가 Git 저장소가 아닌 경우
  • 이미 해당 작업을 위한 worktree가 존재하는 경우

Prerequisites

도구 요구사항

# Git 버전 확인 (worktree는 Git 2.5+ 필요)
git --version

스크립트 설치

# 스크립트 경로를 PATH에 추가하거나 직접 실행
chmod +x /​path/​to/​agent-skills/​development/​context-worktree/​scripts/​context-worktree.sh

# 또는 alias 설정
alias cw='/​path/​to/​agent-skills/​development/​context-worktree/​scripts/​context-worktree.sh'

환경 조건

# Git 저장소인지 확인
git rev-parse --is-inside-work-tree

Workflow

전체 흐름도 (스크립트 사용)

┌─────────────────────────────────────────────────────────────┐
│ 1. 컨텍스트 수집 (1회 스크립트 호출)                          │
│    └─ context-worktree.sh collect                           │
│       → 구조화된 컨텍스트 정보 반환                          │
├─────────────────────────────────────────────────────────────┤
│ 2. LLM 유사성 판단                                           │
│    └─ 수집된 정보 + 새 요청 비교                             │
├─────────────────────────────────────────────────────────────┤
│ 3. 분기 결정                                                 │
│    ├─ 유사 → 현재 브랜치에서 작업 계속                       │
│    └─ 비유사 → Step 4로                                      │
├─────────────────────────────────────────────────────────────┤
│ 4. Worktree 생성 (1회 스크립트 호출)                          │
│    └─ context-worktree.sh create -b <branch> -d <desc>      │
└─────────────────────────────────────────────────────────────┘

토큰 절약: 6+ 도구 호출 → 1~2회 호출

Step 1: 컨텍스트 수집 (스크립트)

# 한 번의 호출로 모든 컨텍스트 수집
context-worktree.sh collect

출력 예시:

## Context Summary

| 항목 | 값 |
|------|-----|
| Repository | my-app |
| Current Branch | feature/​user-auth |
| Default Branch | main |
| Has Uncommitted | false |
| Active Worktrees | 1 |

### Recent Commits (last 5)
feat(auth): JWT 토큰 생성 로직 추가
feat(auth): 로그인 API 엔드포인트 구현

### Changed Directories
`src/​auth,src/​middleware`

### Recent Scopes
`auth`

수집 정보:

항목용도
브랜치명현재 작업 맥락 파악 (feature/, fix/, hotfix/ 등)
최근 커밋scope, type 분석
Changed Directories작업 영역 파악
Recent ScopesConventional commit scope 패턴
Has Uncommitted진행 중 작업 확인

Step 2: LLM 맥락 유사성 판단

2.1 파일 경로 패턴 분석
유사 판단 기준:
- 같은 최상위 디렉토리 (src/​auth/​* ↔ src/​auth/​*)
- 같은 모듈/기능 영역
- 관련 테스트 파일 (src/​auth/​* ↔ tests/​auth/​*)

비유사 판단 기준:
- 완전히 다른 디렉토리 (src/​auth/​* ↔ src/​payment/​*)
- 인프라 vs 애플리케이션 (infra/​* ↔ src/​*)
- 프론트엔드 vs 백엔드 (frontend/​* ↔ backend/​*)
2.2 커밋 히스토리 scope/​type 분석
유사 판단:
- 같은 scope: feat(auth) ↔ fix(auth)
- 관련 type: feat(auth) ↔ test(auth)

비유사 판단:
- 다른 scope: feat(auth) ↔ feat(payment)
- hotfix vs feature: hotfix/​* ↔ feature/​*
2.3 LLM 의미적 유사성 판단

다음 요소를 종합하여 LLM이 판단:

## 현재 작업 컨텍스트
- 브랜치: feature/​user-authentication
- 최근 커밋:
  - feat(auth): JWT 토큰 생성 로직 추가
  - feat(auth): 로그인 API 엔드포인트 구현
- 변경 파일: src/​auth/​*, src/​middleware/​auth.ts

## 새 요청
"결제 시스템에 카드 결제 기능을 추가해줘"

## 판단
비유사 - 결제 시스템은 인증 시스템과 독립적인 기능 영역
2.4 종합 유사성 점수
유사성 점수 = (파일 경로 점수 × 0.3) + (커밋 히스토리 점수 × 0.3) + (LLM 판단 점수 × 0.4)

- 0.7 이상: 유사 → 현재 브랜치 유지
- 0.7 미만: 비유사 → 새 worktree 생성

Step 3: Worktree 생성 (스크립트)

비유사로 판단된 경우 스크립트로 worktree 생성:

# 새 worktree 생성
context-worktree.sh create -b feat/​payment-card -d "카드 결제 기능 구현"

# 핫픽스 (main 기반)
context-worktree.sh create -b hotfix/​login-bug -d "로그인 버그 수정" -base main

출력 예시:

## Worktree Created

| 항목 | 값 |
|------|-----|
| Branch | feat/​payment-card |
| Path | /​home/​user/​projects/​my-app-worktrees/​feat-payment-card |
| Base | main |

### Next Steps
cd /​home/​user/​projects/​my-app-worktrees/​feat-payment-card

**Description**: 카드 결제 기능 구현
브랜치명 생성 규칙
패턴: <type>/<short-description>

예시:
- feat/​payment-card-integration
- fix/​login-timeout-issue
- hotfix/​security-patch
- refactor/​database-connection
Worktree 경로 규칙
기본 경로: ../<repo-name>-worktrees/<branch-name>

예시:
- 현재: /​home/​user/​projects/​my-app
- worktree: /​home/​user/​projects/​my-app-worktrees/​feat-payment-card

Step 4: 작업 환경 안내

worktree 생성 후 사용자에게 안내:

## 새 Worktree 생성됨

새 작업은 기존 작업과 맥락이 다르므로 별도 worktree를 생성했습니다.

| 항목 | 값 |
|------|-----|
| 브랜치 | feat/​payment-card-integration |
| 경로 | /​home/​user/​projects/​my-app-worktrees/​feat-payment-card-integration |
| 기반 브랜치 | main |

### 다음 단계

해당 worktree에서 작업을 계속하려면:
\`\`\`bash
cd /​home/​user/​projects/​my-app-worktrees/​feat-payment-card-integration
\`\`\`

또는 현재 세션에서 작업하려면 경로를 변경합니다.

Examples

예시 1: 유사한 작업 (분리 불필요)

현재 상태:
- 브랜치: feature/​user-authentication
- 최근 커밋: feat(auth): JWT 토큰 생성 로직
- 변경 파일: src/​auth/​jwt.ts, src/​auth/​login.ts

사용자: 로그아웃 기능도 추가해줘

Claude: 맥락 유사성을 판단합니다...

## 유사성 분석 결과

| 기준 | 점수 | 이유 |
|------|------|------|
| 파일 경로 | 1.0 | 같은 src/​auth/ 영역 |
| 커밋 히스토리 | 1.0 | 동일 scope (auth) |
| LLM 판단 | 0.9 | 인증 기능의 일부 |
| **종합** | **0.96** | |

→ 유사: 현재 브랜치(feature/​user-authentication)에서 작업 계속

[로그아웃 기능 구현 시작...]

예시 2: 비유사한 작업 (worktree 생성)

현재 상태:
- 브랜치: feature/​user-authentication
- 최근 커밋: feat(auth): JWT 토큰 생성 로직
- 변경 파일: src/​auth/​jwt.ts

사용자: 결제 시스템에 카드 결제 기능 추가해줘

Claude: 맥락 유사성을 판단합니다...

## 유사성 분석 결과

| 기준 | 점수 | 이유 |
|------|------|------|
| 파일 경로 | 0.1 | src/​payment/ ≠ src/​auth/ |
| 커밋 히스토리 | 0.1 | 다른 scope (payment ≠ auth) |
| LLM 판단 | 0.2 | 독립적인 기능 영역 |
| **종합** | **0.14** | |

→ 비유사: 새 worktree 생성

## 새 Worktree 생성됨

| 항목 | 값 |
|------|-----|
| 브랜치 | feat/​payment-card-integration |
| 경로 | ../​my-app-worktrees/​feat-payment-card-integration |
| 기반 브랜치 | main |

worktree로 이동하여 작업을 시작합니다...

[결제 기능 구현 시작...]

예시 3: 긴급 핫픽스

현재 상태:
- 브랜치: feature/​dashboard-redesign
- 변경 파일: src/​components/​Dashboard.tsx (uncommitted)

사용자: 프로덕션에서 로그인이 안 되는 긴급 버그가 있어. 빨리 수정해줘!

Claude: 긴급 핫픽스 요청을 감지했습니다. 맥락 유사성을 판단합니다...

## 유사성 분석 결과

| 기준 | 점수 | 이유 |
|------|------|------|
| 파일 경로 | 0.0 | Dashboard ≠ Auth |
| 커밋 히스토리 | 0.0 | 다른 scope |
| LLM 판단 | 0.1 | 긴급 핫픽스는 별도 처리 필요 |
| **종합** | **0.04** | |

→ 비유사: 새 worktree 생성 (hotfix)

## 새 Worktree 생성됨

| 항목 | 값 |
|------|-----|
| 브랜치 | hotfix/​login-critical-bug |
| 경로 | ../​my-app-worktrees/​hotfix-login-critical-bug |
| 기반 브랜치 | main |

**주의**: 현재 브랜치에 uncommitted 변경사항이 있습니다.
핫픽스 완료 후 원래 브랜치로 돌아가서 작업을 계속하세요.

[핫픽스 작업 시작...]

예시 4: Git 저장소가 아닌 경우

사용자: 새로운 API 엔드포인트 만들어줘

Claude: Git 저장소 확인 중...

⚠️ 현재 디렉토리는 Git 저장소가 아닙니다.
context-worktree 스킬을 스킵하고 일반 작업을 진행합니다.

[API 엔드포인트 구현 시작...]

Configuration

Worktree 경로 커스터마이징

기본 경로 패턴을 변경하려면:

# 환경 변수로 설정
export WORKTREE_BASE_PATH="/​custom/​path/​worktrees"

유사성 임계값 조정

# ~/​.agents/​config/​context-worktree.yaml (선택적)
similarity:
  threshold: 0.7  # 0.0 ~ 1.0, 높을수록 엄격
  weights:
    file_path: 0.3
    commit_history: 0.3
    llm_judgment: 0.4

브랜치 네이밍 규칙

branch_naming:
  prefix_map:
    feature: "feat"
    bugfix: "fix"
    hotfix: "hotfix"
    refactor: "refactor"
  separator: "/"
  word_separator: "-"

Best Practices

DO:

  • 새로운 독립적 작업 시작 전 맥락 확인
  • uncommitted 변경사항이 있으면 먼저 stash 또는 commit
  • worktree 작업 완료 후 정리 (git worktree remove)
  • 브랜치명에 작업 내용을 명확히 표현
  • 긴급 핫픽스는 항상 main/​master 기반으로 생성

DON'T:

  • 같은 브랜치를 여러 worktree에서 체크아웃
  • worktree 내부에서 다시 worktree 생성
  • 완료된 worktree를 정리하지 않고 방치
  • uncommitted 변경사항을 무시하고 다른 작업 시작
  • 기반 브랜치를 잘못 선택하여 충돌 유발

Troubleshooting

Worktree 생성 실패

# 이미 해당 브랜치가 다른 worktree에서 체크아웃된 경우
git worktree list

# 해결: 기존 worktree 제거 또는 다른 브랜치명 사용
git worktree remove /​path/​to/​existing/​worktree

Worktree 정리

# 사용하지 않는 worktree 확인
git worktree list

# worktree 제거
git worktree remove /​path/​to/​worktree

# 또는 강제 제거
git worktree remove --force /​path/​to/​worktree

# 정리 (삭제된 worktree 참조 제거)
git worktree prune

브랜치 충돌

# 같은 이름의 브랜치가 이미 존재하는 경우
# 해결: 다른 브랜치명 사용 또는 기존 브랜치 삭제

git branch -d existing-branch  # 머지된 경우
git branch -D existing-branch  # 강제 삭제

uncommitted 변경사항 처리

# 변경사항 임시 저장
git stash push -m "WIP: 현재 작업"

# 다른 작업 완료 후 복원
git stash pop

Integration

이 스킬은 다음 스킬과 연동됩니다:

스킬연동 방식
git-commit-prworktree에서 작업 완료 후 커밋/​PR 생성 시
context-manager새 worktree에서 컨텍스트 재로드

Script Commands

스크립트 명령어 요약

# 컨텍스트 수집 (구조화된 출력)
context-worktree.sh collect

# worktree 생성
context-worktree.sh create -b <branch> [-d <description>] [-base <branch>]

# worktree 목록
context-worktree.sh list

# 정리 (stale 참조 제거)
context-worktree.sh clean

# 도움말
context-worktree.sh help

Git Worktree 네이티브 명령어 참고

# worktree 목록 확인
git worktree list

# worktree 추가 (새 브랜치)
git worktree add -b <branch> <path> <base-branch>

# worktree 추가 (기존 브랜치)
git worktree add <path> <existing-branch>

# worktree 제거
git worktree remove <path>

# worktree 이동
git worktree move <old-path> <new-path>

# 정리 (prune)
git worktree prune

Resources

파일설명
scripts/​context-worktree.sh메인 자동화 스크립트 (컨텍스트 수집, worktree 생성)