---
name: git-worktree-isolation
description: "Git Worktree 격리 워크플로우: 멀티봇 충돌 방지를 위한 프로젝트별 독립 작업 환경 관리"
triggers:
  - "git worktree"
  - "worktree"
  - "격리 워크플로우"
  - "multi-bot isolation"
  - "멀티봇"
usage: "/git-worktree-isolation"
---

# git-worktree-isolation 스킬

이 스킬은 여러 봇/팀이 동일 프로젝트에서 동시 작업할 때 Git Worktree를 통해 격리된 작업 환경을 관리한다.

**이 스킬이 다루는 것**: Worktree 생성 → 격리된 작업 → 커밋 → PR/리뷰 → Merge/Discard
**이 스킬이 다루지 않는 것**: Lv.1 작업, Git repo가 아닌 프로젝트, 단일 팀 프로젝트 (worktree 불필요)

**이 스킬을 켜는 조건**:
- Lv.2 이상 작업
- 프로젝트가 Git repo (`.git` 디렉토리 존재)
- 같은 프로젝트에 2팀 이상 동시 투입

**이 스킬을 끄는 조건**: Worktree merge 또는 discard 완료

---

## 트리거 시스템

### 진입 조건 (Activation)

이 스킬은 아래 모든 조건을 만족할 때 자동으로 활성화된다:

1. **작업 난이도**: Lv.2 이상
2. **Git Repository 확인**: 프로젝트 경로에 `.git` 디렉토리 존재
3. **멀티봇 상황**: 동일 프로젝트에 2팀 이상 동시 투입 필요

단일 팀만 작업하는 프로젝트의 경우 Worktree가 불필요하므로 main 브랜치에서 직접 작업해도 무관.

### 진출 조건 (Deactivation)

이 스킬 실행은 아래 중 하나 완료 시 종료된다:

1. **Merge 완료**: Worktree 브랜치를 메인 브랜치에 병합하고 Worktree 삭제
2. **Discard 완료**: Worktree 브랜치를 버리고 Worktree 삭제
3. **Keep (리뷰 대기)**: Worktree 유지 상태로 리뷰 대기

---

## 워크플로우 단계별 설명

### STEP 1: Worktree 생성

새로운 작업을 시작할 때 Worktree를 생성하여 격리된 작업 환경을 설정한다.

**실행 명령어:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py create <프로젝트경로> <작업ID> <팀ID>
```

**예시:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py create /home/jay/projects/myapp task-330.1 dev2
```

**매개변수:**
- `<프로젝트경로>`: `/home/jay/projects/<프로젝트명>/` 형태
- `<작업ID>`: `task-330.1` 형태의 고유 작업 식별자
- `<팀ID>`: `dev1`, `dev2` 등 팀 또는 담당자 식별자

**생성 결과:**
- 새로운 Worktree 디렉토리 생성: `<프로젝트경로>/.worktrees/<작업ID>-<팀ID>/`
- 신규 브랜치 생성: `task/<작업ID>-<팀ID>`
- 격리된 작업 환경 준비 완료

---

### STEP 2: 작업 수행

Worktree 내에서 독립적으로 코드 수정 및 테스트를 진행한다.

**작업 원칙:**
- 각 팀은 자신의 Worktree에서만 작업
- 메인 브랜치 직접 수정 금지
- 작업 완료 후 Worktree 내에서 커밋 생성

**작업 경로:**
```
/home/jay/projects/<프로젝트명>/.worktrees/<작업ID>-<팀ID>/
```

---

### STEP 3: 상태 확인

언제든 Worktree 상태를 확인할 수 있다.

**Worktree 목록 확인:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py list /home/jay/projects/myapp
```

**개별 Worktree 상태 확인:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py status /home/jay/projects/myapp task-330.1
```

**출력 정보:**
- Worktree 경로
- 현재 브랜치명
- 커밋 히스토리
- 수정된 파일 목록
- 스테이징 상태

---

### STEP 4: 커밋 및 푸시

작업 완료 후 Worktree 내에서 커밋을 생성하고 푸시한다.

**커밋 생성:**
```bash
git add .
git commit -m "작업 설명: task-330.1"
```

**푸시:**
```bash
git push origin task/<작업ID>-<팀ID>
```

**커밋 메시지 규약:**
- 형식: `[task-ID] 변경사항 설명`
- 예: `[task-330.1] API 응답 속도 최적화 구현`

---

### STEP 5: 코드 리뷰 및 PR

커밋 완료 후 Pull Request를 생성하여 리뷰를 받는다.

**PR 생성 기준:**
- 변경 사항이 의도대로 구현되었는지 확인
- 테스트 커버리지 검증
- 코드 스타일 준수 확인

**PR 설명:**
- 작업 ID 명시
- 변경 사항 요약
- 테스트 결과 첨부

---

### STEP 6: Merge 또는 Discard

리뷰 완료 후 최종 결정을 진행한다.

**Merge (승인된 경우):**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action merge
```

동작:
- Worktree 브랜치를 메인 브랜치에 병합
- Worktree 디렉토리 삭제
- 작업 완료 마킹

**Discard (거부된 경우):**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action discard
```

동작:
- Worktree 브랜치 버림
- Worktree 디렉토리 삭제
- 작업 취소 마킹

**Keep (리뷰 대기):**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action keep
```

동작:
- Worktree 유지
- 추가 수정 대기 상태 마킹
- 추후 merge/discard 진행 가능

---

## 멀티봇 충돌 방지 규칙

이 섹션은 여러 봇/팀이 동시 작업할 때 반드시 준수해야 할 규칙이다.

### 규칙 1: 팀별 격리 원칙

```
각 팀은 자신의 Worktree에서만 작업한다.
다른 팀의 Worktree에 접근하지 않는다.
```

**위반 사항:**
- 다른 팀의 Worktree 내 파일 수정
- 다른 팀의 브랜치 직접 푸시
- 메인 브랜치 우회하여 동료 Worktree로 merge

### 규칙 2: 메인 브랜치 직접 수정 금지

```
모든 작업은 Worktree를 통해서만 진행된다.
메인 브랜치에 직접 푸시 금지.
```

**올바른 워크플로우:**
1. Worktree 생성
2. Worktree에서 작업
3. Worktree 브랜치에 커밋 및 푸시
4. PR 생성 및 리뷰
5. Merge 승인 후 메인 브랜치 업데이트

**금지된 워크플로우:**
```bash
# 절대 금지
git checkout main
git push origin main
```

### 규칙 3: 충돌 발생 시 보고

Merge 중 충돌이 발생하면 즉시 아누(anu)에게 보고한다.

**충돌 보고 프로세스:**

1. **충돌 감지**: Merge 시도 중 충돌 발생
2. **Merge 중단**: 자동 merge 중지, 수동 개입 필요
3. **아누에게 보고**:
   - 충돌 파일 목록
   - 충돌 내용 설명
   - 해결 방안 제안
4. **수동 해결**: 아누의 지시에 따라 수동 해결
5. **재시도**: 충돌 해결 후 merge 재시도

**충돌 해결 명령어:**
```bash
# 충돌 파일 확인
git status

# 충돌 수동 해결 후
git add <해결된 파일>
git commit -m "[task-ID] Merge conflict resolved"
```

### 규칙 4: 1프로젝트 1팀 원칙

```
기본 원칙: 1개 프로젝트에는 1개 팀만 할당.
예외: 같은 프로젝트에 2팀 이상 투입 필요시에만 Worktree 활성화.
```

**상황별 처리:**

| 상황 | 처리 방식 | Worktree 필요 |
|------|---------|--------------|
| 단일 팀 작업 | Main 브랜치 직접 작업 | 불필요 |
| 2팀 이상 동시 작업 | 각각 Worktree 사용 | 필수 |
| 순차 작업 (팀 A → 팀 B) | Main 브랜치 작업 가능 | 불필요 |

**팀 할당 확인:**
- 프로젝트당 활성 팀 수 모니터링
- 새 팀 투입 시 즉시 Worktree 생성
- 팀 완료 시 Worktree merge 및 정리

---

## worktree_manager.py 명령어 레퍼런스

스크립트 위치: `/home/jay/workspace/scripts/worktree_manager.py`

### create: Worktree 생성

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py create <프로젝트경로> <작업ID> <팀ID>
```

**예시:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py create /home/jay/projects/myapp task-330.1 dev2
```

**생성 결과:**
- Worktree 디렉토리: `/home/jay/projects/myapp/.worktrees/task-330.1-dev2/`
- 브랜치: `task/task-330.1-dev2`
- 즉시 작업 가능한 격리 환경

---

### list: Worktree 목록

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py list <프로젝트경로>
```

**예시:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py list /home/jay/projects/myapp
```

**출력:**
```
Active Worktrees:
- task-330.1 (dev2)
- task-331.2 (dev1)
- task-332.3 (qa1)
```

---

### status: Worktree 상태 확인

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py status <프로젝트경로> <작업ID>
```

**예시:**
```bash
python3 /home/jay/workspace/scripts/worktree_manager.py status /home/jay/projects/myapp task-330.1
```

**출력 정보:**
- Worktree 경로
- 현재 브랜치
- 최근 커밋
- 변경 상태
- 스테이징 상태

---

### finish: Worktree 완료 (Merge/Discard/Keep)

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish <프로젝트경로> <작업ID> <팀ID> --action <merge|discard|keep>
```

#### 옵션 1: Merge (작업 승인 시)

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action merge
```

동작:
- Worktree 브랜치 → Main 브랜치 병합
- Merge 커밋 생성
- Worktree 디렉토리 삭제
- 작업 완료 마킹

#### 옵션 2: Discard (작업 거부 시)

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action discard
```

동작:
- Worktree 브랜치 버림
- Worktree 디렉토리 삭제
- 모든 변경사항 폐기
- 작업 취소 마킹

#### 옵션 3: Keep (리뷰 대기 시)

```bash
python3 /home/jay/workspace/scripts/worktree_manager.py finish /home/jay/projects/myapp task-330.1 dev2 --action keep
```

동작:
- Worktree 유지
- 리뷰 대기 상태 마킹
- 추가 수정 가능
- 나중에 merge/discard 진행

---

## 적용 조건 체크리스트

Worktree 격리 워크플로우 활성화 전 다음을 확인한다:

### 1. 프로젝트 경로 확인
```bash
ls -la /home/jay/projects/<프로젝트명>/
```
- 디렉토리 존재 확인
- 쓰기 권한 확인

### 2. Git Repository 확인
```bash
ls -la /home/jay/projects/<프로젝트명>/.git
```
- `.git` 디렉토리 존재
- Git repo 초기화 확인
- Main 브랜치 존재 확인

### 3. 작업 난이도 확인
- Lv.2 이상인가? (Lv.1 작업은 Worktree 불필요)

### 4. 멀티봇 여부 확인
- 2팀 이상 동시 투입인가?
- 순차 작업인가? (순차는 Worktree 불필요)

### 5. 스크립트 경로 확인
```bash
ls -la /home/jay/workspace/scripts/worktree_manager.py
```
- 스크립트 파일 존재
- 실행 권한 확인

---

## 문제 해결 (Troubleshooting)

### Worktree 생성 실패

**증상:** `Error: Failed to create worktree`

**원인 및 해결:**
1. Git repo가 아님 → `.git` 디렉토리 확인
2. 동일 작업ID 이미 존재 → `list` 명령어로 확인 후 다른 ID 사용
3. 디스크 공간 부족 → 디스크 용량 확인

### Merge 충돌 발생

**증상:** `CONFLICT (content): Merge conflict in <파일명>`

**해결 절차:**
1. 충돌 감지 → 즉시 작업 중단
2. 아누에게 보고 → 충돌 내용 설명
3. 수동 해결 → 규칙 3 참고
4. 재시도 → `finish --action merge`

### Worktree 명령어 오류

**증상:** `python3: No module named worktree_manager`

**원인 및 해결:**
1. 스크립트 경로 확인 → 절대경로 사용
2. Python 버전 확인 → Python 3.6+ 필요
3. 권한 확인 → `chmod +x worktree_manager.py`

---

## 참조 및 관련 문서

- Git Worktree 공식 문서: `git worktree --help`
- Worktree Manager 스크립트: `/home/jay/workspace/scripts/worktree_manager.py`
- 프로젝트 경로: `/home/jay/projects/`
- 팀 관리 가이드: `memory/specs/team-management.md` (참고용)