# 03-worktree

> (선택) Git worktree로 격리된 작업 환경을 만드는 스킬. 현재 작업을 방해받지 않고 새 기능을 개발할 때 유용합니다.

- Author: Dave Goobong Jeong
- Repository: team-attention/cc-workflow-101-public
- Version: 20260126170331
- Stars: 4
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/team-attention/cc-workflow-101-public
- Web: https://mule.run/skillshub/@@team-attention/cc-workflow-101-public~03-worktree:20260126170331

---

---
name: 03-worktree
description: (선택) Git worktree로 격리된 작업 환경을 만드는 스킬. 현재 작업을 방해받지 않고 새 기능을 개발할 때 유용합니다.
---

# Git Worktree로 격리된 환경 만들기

> **선택 스킬**: 간단한 작업은 이 스킬을 건너뛰어도 됩니다.

## 개요

Git worktree는 **같은 저장소에서 여러 브랜치를 동시에** 열 수 있게 해줍니다.

**언제 사용하나요?**
- 현재 작업 중인데 급한 버그 수정이 필요할 때
- 큰 기능을 개발하면서 메인 브랜치를 깨끗하게 유지하고 싶을 때
- 여러 기능을 병렬로 개발할 때

**시작할 때 알림**: "worktree 스킬을 사용하여 격리된 작업 환경을 만들겠습니다."

```
┌──────────────────────────────────────────────────────────────────────┐
│                      Worktree 워크플로우                              │
└──────────────────────────────────────────────────────────────────────┘

  ┌─────────────────┐
  │ 1. 위치 확인    │
  └────────┬────────┘
           │
           ▼
     ┌───────────────────────┐
     │ .worktrees 존재하는가? │
     └───────────┬───────────┘
                 │
       ┌─────────┴─────────┐
       │                   │
       ▼                   ▼
  ┌─────────┐        ┌─────────┐
  │   YES   │        │   NO    │
  │ 그대로  │        │ 위치    │
  │ 사용    │        │ 묻기    │
  └────┬────┘        └────┬────┘
       │                  │
       └────────┬─────────┘
                │
                ▼
  ┌─────────────────┐
  │ 2. .gitignore   │  worktree 경로 추가
  │    확인/추가    │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ 3. 브랜치 생성  │  feature/xxx
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ 4. Worktree     │  git worktree add
  │    생성         │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ 5. 환경 복사    │  .env, node_modules 등
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ ➡ 작업 시작    │
  └─────────────────┘

  ═══════════════════════════════════════════════════════════════════
  프로젝트 구조:

  my-project/           ← 원본 (main 브랜치)
  ├── .worktrees/
  │   └── login/        ← worktree (feature/login 브랜치)
  └── src/
  ═══════════════════════════════════════════════════════════════════
```

## 절차

### 1단계: 위치 확인

기존 worktree 디렉토리가 있는지 확인합니다:

```bash
# 우선순위: .worktrees > worktrees
ls -d .worktrees 2>/dev/null || ls -d worktrees 2>/dev/null
```

**있다면**: 그 디렉토리 사용
**없다면**: 사용자에게 위치 묻기

```
worktree 디렉토리가 없습니다. 어디에 만들까요?

1. .worktrees/ (프로젝트 내부, 숨김)
2. ~/worktrees/{프로젝트명}/ (홈 디렉토리)
```

### 2단계: .gitignore 확인

프로젝트 내부에 만들 경우, **반드시** .gitignore에 추가되어 있어야 합니다:

```bash
# .gitignore에 있는지 확인
git check-ignore -q .worktrees
```

**없다면**: .gitignore에 추가하고 커밋

```bash
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: add .worktrees to gitignore"
```

### 3단계: Worktree 생성

```bash
# 새 브랜치와 함께 worktree 생성
git worktree add .worktrees/feature-name -b feature/feature-name

# worktree로 이동
cd .worktrees/feature-name
```

### 4단계: 환경 설정

프로젝트 타입에 맞게 의존성 설치:

```bash
# Node.js
npm install

# Python
uv sync  # 또는 pip install -r requirements.txt

# Go
go mod download
```

### 5단계: 테스트 확인

깨끗한 상태에서 시작하는지 확인:

```bash
# 테스트 실행
npm test  # 또는 pytest, go test ./...
```

**테스트 실패 시**: 원인 파악 후 진행 여부 결정

### 6단계: 완료 보고

```
Worktree 준비 완료:
- 위치: /path/to/.worktrees/feature-name
- 브랜치: feature/feature-name
- 테스트: 통과 (N개)

이제 plan 스킬로 구현 계획을 세우세요.
```

## 자주 하는 실수

| 실수 | 해결 |
|------|------|
| .gitignore 빠뜨림 | worktree 내용이 git에 추적됨 → 반드시 확인 |
| 테스트 안 돌림 | 기존 문제와 새 문제 구분 불가 → 항상 확인 |
| 의존성 설치 안 함 | 빌드/테스트 실패 → 항상 설치 |

## Worktree 관리 명령어

```bash
# worktree 목록 보기
git worktree list

# worktree 삭제
git worktree remove .worktrees/feature-name

# 강제 삭제 (변경사항 있을 때)
git worktree remove --force .worktrees/feature-name
```

## 다음 단계

Worktree가 준비되면 계획 작성으로 이동:

```
Skill("04-plan")
```

> **반드시** 다음 스킬을 호출하여 워크플로우를 이어가세요.