Claude Code Skills 실전: 브랜치 정리를 자동화한 cleanup-branch 스킬

브랜치를 정리할 때마다 뭔가 빠뜨립니다

Git Worktree로 병렬 개발을 하면, 피처 브랜치가 자주 생기고 사라집니다. main에 병합한 뒤 정리해야 할 것은 네 가지입니다.

1. 워크트리 해제 (git worktree remove)
2. 워크트리 디렉토리 삭제
3. 로컬 브랜치 삭제 (git branch -d)
4. 리모트 브랜치 삭제 (git push origin --delete)

한두 번이면 괜찮지만, 반복하다 보면 빠뜨리는 단계가 생깁니다. 워크트리 디렉토리는 삭제했는데 로컬 브랜치가 남아있거나, 로컬은 정리했는데 리모트에 찌꺼기가 남아있는 경우가 있었습니다. git worktree list를 실행하면 이미 삭제된 디렉토리를 참조하는 워크트리가 보이기도 했습니다.

각 단계가 어렵지는 않습니다. 문제는 순서와 조건을 매번 기억해야 한다는 것입니다. 병합되지 않은 브랜치를 실수로 삭제하면 작업이 날아가고, 현재 체크아웃된 브랜치를 삭제하려고 하면 에러가 나고, 리모트에 없는 브랜치를 삭제하려고 하면 또 에러가 납니다.

그래서 이 전체 과정을 Claude Code 커스텀 스킬로 만들었습니다.

cleanup-branch 스킬 전문

실제 사용 중인 .claude/skills/cleanup-branch/SKILL.md 전문입니다.

---
name: cleanup-branch
description: Delete a merged branch completely - worktree, local branch, remote branch, and worktree directory.
user_invocable: true
---

# Branch Cleanup - 병합 완료된 브랜치 정리

## Overview

main에 병합 완료된 브랜치를 완전히 정리한다:
워크트리 해제, 디렉토리 삭제, 로컬/리모트 브랜치 삭제.

## 사용법

/cleanup-branch chore/remove-admin-ai-usage
/cleanup-branch feature/some-feature

## 실행 절차

### Step 1: 사전 확인

  # 현재 브랜치 확인 (삭제 대상 브랜치에 있으면 안 됨)
  git branch --show-current

  # 대상 브랜치가 main에 병합되었는지 확인
  git branch --merged main | grep "<브랜치명>"

  # 워크트리 목록에서 대상 확인
  git worktree list

안전 검사:
- 현재 체크아웃된 브랜치가 삭제 대상이면
  → git checkout main 먼저 실행
- git branch --merged main에 대상 브랜치가 없으면
  → 병합되지 않은 브랜치. 사용자에게 경고하고 확인받기
- 워크트리 디렉토리에 커밋되지 않은 변경사항이 있는지 확인

### Step 2: 워크트리 제거

워크트리가 존재하는 경우에만 실행한다.

  # 워크트리 경로 확인
  WORKTREE_PATH=$(git worktree list --porcelain \
    | grep -B2 "branch refs/heads/<브랜치명>" \
    | grep "^worktree " | sed 's/^worktree //')

  # 워크트리 해제
  git worktree remove "$WORKTREE_PATH"

  # 디렉토리가 남아있으면 삭제
  [ -d "$WORKTREE_PATH" ] && rm -rf "$WORKTREE_PATH"

  # 워크트리 참조 정리
  git worktree prune

### Step 3: 로컬 브랜치 삭제

  git branch -d <브랜치명>

-d는 병합된 브랜치만 삭제한다.
병합되지 않은 경우 사용자 확인 후 -D를 사용한다.

### Step 4: 리모트 브랜치 삭제

리모트에 존재하는 경우에만 실행한다.

  # 리모트 브랜치 존재 여부 확인
  git branch -r | grep "origin/<브랜치명>"

  # 존재하면 삭제
  git push origin --delete <브랜치명>

### Step 5: 결과 확인

  # 로컬 브랜치 목록에서 제거 확인
  git branch | grep "<브랜치명>"

  # 워크트리 목록에서 제거 확인
  git worktree list

  # 디렉토리 삭제 확인
  ls -d <워크트리경로> 2>/dev/null || echo "디렉토리 삭제 완료"

### Step 6: 결과 요약

| 항목              | 상태            |
|-------------------|-----------------|
| 워크트리 해제     | ✅ / ⏭️ 없음   |
| 디렉토리 삭제     | ✅ / ⏭️ 없음   |
| 로컬 브랜치 삭제  | ✅              |
| 리모트 브랜치 삭제| ✅ / ⏭️ 없음   |

## 주의사항

- main/master 브랜치는 절대 삭제하지 않는다
- 병합되지 않은 브랜치는 반드시 사용자 확인을 받는다
- 워크트리 Docker 컨테이너가 실행 중일 수 있으므로,
  필요 시 docker compose -p <프로젝트명> down -v를 먼저 안내한다

설계 의도

이 스킬을 만들면서 몇 가지 의도적으로 결정한 부분이 있습니다.

사전 확인이 핵심입니다

Step 1의 안전 검사가 이 스킬에서 가장 중요한 부분입니다. 삭제 자체는 간단하지만, 삭제해도 되는지 확인하는 것이 어렵습니다.

git branch --merged main으로 병합 여부를 먼저 확인하도록 한 이유는, 실수로 작업 중인 브랜치를 날리는 것을 방지하기 위해서입니다. 이 검사를 통과하지 못하면 Claude가 사용자에게 경고하고, 명시적 확인을 받은 후에만 -D 옵션으로 강제 삭제를 진행합니다.

현재 체크아웃된 브랜치인지 확인하는 것도 빠뜨리기 쉬운 부분입니다. 삭제 대상 브랜치에서 git branch -d를 실행하면 에러가 나는데, 스킬이 이를 미리 감지하고 git checkout main으로 전환합니다.

조건부 실행으로 불필요한 에러를 방지합니다

워크트리가 없는 브랜치도 있고, 리모트에 push하지 않은 브랜치도 있습니다. 스킬의 각 Step은 "존재하는 경우에만 실행"이라는 조건을 달아두어, 해당 리소스가 없을 때 에러 대신 스킵합니다. 결과 요약 테이블에서 ⏭️로 표시되는 부분입니다.

결과를 구조화된 테이블로 보고합니다

삭제 작업은 "했는지 안 했는지"가 명확해야 합니다. Claude에게 자유 형식으로 보고하라고 하면 매번 다른 포맷으로 답하는데, 테이블 형식을 지정하면 한눈에 파악할 수 있습니다.

실제 실행 결과

chore/remove-admin-ai-usage 브랜치를 main에 rebase + fast-forward merge한 뒤, /cleanup-branch를 실행한 결과입니다.

$ /cleanup-branch chore/remove-admin-ai-usage

Step 1: 사전 확인
  현재 브랜치: main ✓
  병합 여부: git branch --merged main에 포함 ✓
  워크트리: my_blog-chore-remove-admin-ai-usage 발견

Step 2: 워크트리 제거
  git worktree remove 시도
  → untracked 파일 존재 (.env 등 gitignored 파일)
  → 이미 병합된 브랜치이므로 --force로 제거

Step 3: 로컬 브랜치 삭제
  Deleted branch chore/remove-admin-ai-usage (was 8f49d2c)

Step 4: 리모트 브랜치
  git branch -r에서 미발견 → 스킵

Step 5: 결과 확인
  git branch | grep → 없음 ✓
  git worktree list → 없음 ✓
  ls -d → "디렉토리 삭제 완료" ✓

최종 결과 요약입니다.

항목	상태
워크트리 해제	완료
디렉토리 삭제	완료
로컬 브랜치 삭제	완료
리모트 브랜치 삭제	없음 (스킵)

한 줄의 커맨드로 네 가지 정리 작업이 안전하게 완료되었습니다. 워크트리에 untracked 파일(.env 등)이 있어서 일반 git worktree remove가 실패했지만, 병합 완료된 브랜치임을 확인한 뒤 --force로 처리했습니다. 이런 판단을 매번 직접 하지 않아도 되는 것이 스킬의 가치입니다.

스킬을 만들 때 생각해볼 점

이 스킬을 만들면서, 그리고 이전에 Git Worktree 스킬을 만들면서 느낀 점을 정리했습니다.

실패 경험을 반영합니다

이 스킬의 Step 2에서 --force 옵션을 언급한 것은, 실제로 .env 파일 때문에 워크트리 제거가 실패한 경험에서 나왔습니다. 스킬은 개인적인 실수 기록의 진화형이라는 생각이 들었습니다. 한 번 실패할 때마다 한 줄씩 추가하면, 같은 실수를 반복하지 않게 됩니다.

안전 장치를 명시합니다

"병합되지 않은 브랜치는 반드시 사용자 확인을 받는다"라는 한 줄이, 작업 내용을 날리는 사고를 방지합니다. Claude에게 "알아서 해"라고 하면 효율적이지만, 삭제 같은 비가역적 작업에서는 안전 장치가 있어야 합니다. 이 균형을 스킬에서 정의할 수 있습니다.

Docker 컨테이너도 함께 고려합니다

워크트리에서 Docker DB를 띄웠다면, 디렉토리만 삭제해서는 고아 컨테이너가 남을 수 있습니다. 주의사항에 docker compose -p <프로젝트명> down -v를 먼저 안내하도록 기술한 것은, 이런 경우를 한 번 겪은 뒤에 추가한 것입니다.

돌이켜 생각해보면

브랜치 정리라는 단순한 작업이 스킬로 만들 가치가 있을까 처음에는 의문이었습니다. 네 줄의 명령어를 기억하면 될 일이니까요. 하지만 실제로 만들어보니, 가치는 명령어 자체가 아니라 조건 분기와 안전 검사에 있었습니다. "워크트리가 있는가?", "리모트에 push했는가?", "정말 병합된 브랜치인가?"를 매번 확인하는 것은 네 줄보다 훨씬 많은 인지 부담입니다.

반복 작업이 귀찮다고 느끼는 순간이 온다면, 그것이 스킬을 만들 타이밍이라고 생각합니다. 특히 삭제나 정리처럼 빠뜨리면 찌꺼기가 남는 작업은 스킬로 만들기에 적합합니다.