git-worktree-manager

git-worktree-manager skill 개요

git-worktree-manager가 하는 일

git-worktree-manager는 여러 로컬 Git worktree를 브랜치, 포트, 환경 설정, 정리 과정의 충돌 없이 운영하기 위한 엔지니어링 skill입니다. 실행 가이드와 Python 보조 스크립트를 함께 제공해, 준비된 worktree를 만들고, 결정적인 방식으로 포트를 할당하며, 로컬 환경 파일을 복사하고, 필요하면 의존성을 설치하며, 오래된 worktree를 삭제하기 전에 검토할 수 있게 합니다.

일반적인 git worktree 명령만으로는 부족하고, 각 브랜치가 별도의 실행 가능한 앱처럼 동작해야 할 때 이 skill을 사용하면 좋습니다.

병렬 Git 워크플로에 가장 잘 맞는 경우

가장 잘 맞는 사용자는 기능 개발, 핫픽스, PR 리뷰, 마이그레이션 테스트, 멀티 에이전트 구현처럼 두 개 이상의 브랜치를 동시에 열어 두는 개발자, 테크 리드, 코딩 에이전트 운영자입니다. git-worktree-manager for Git Workflows는 각 에이전트나 터미널 세션이 하나의 checkout을 공유하는 대신, 자기 브랜치와 격리된 런타임을 하나씩 가져야 할 때 특히 유용합니다.

브랜치를 가끔 전환하는 정도이거나, 로컬 서비스를 실행하지 않거나, 이미 성숙한 사내 worktree 래퍼가 있다면 이 skill의 가치는 상대적으로 낮습니다.

설치 전 확인할 핵심 차별점

실질적인 가치는 단순히 “worktree를 만든다”는 데 있지 않습니다. 이 skill은 다음과 같은 반복 가능한 운영 규칙을 더해 줍니다.

• 결정적인 worktree 이름 지정과 브랜치 생성
• 앱, 데이터베이스, Redis 포트가 겹치지 않도록 할당
• .env, .env.local, .env.development, .envrc 동기화
• 일반적인 lockfile을 기준으로 의존성 설치 여부 감지
• 오래되었거나 dirty 상태이거나 병합된 브랜치에 대한 정리 전 점검
• worktree별 서비스 격리를 위한 Docker Compose 패턴

그래서 git-worktree-manager skill은 Git worktree에 관한 일반적인 프롬프트보다 운영 관점에서 더 실용적입니다.

git-worktree-manager skill 사용 방법

git-worktree-manager 설치 옵션

Claude 스타일의 skills 설정을 사용한다면, 사용 가능한 skill manager로 저장소에서 설치하세요.

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

수동으로 설치한다면 다음 경로의 skill 디렉터리를 복사합니다.

engineering/skills/git-worktree-manager

이를 ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager 또는 호환되는 다른 에이전트 skill 디렉터리에 넣으면 됩니다. 설치 후에는 SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py, 그리고 references/ 아래의 두 파일이 있는지 확인하세요.

먼저 읽어야 할 파일

빠르게 도입하려면 다음 순서로 읽는 것이 좋습니다.

1. 명령 형태와 도구 목록은 README.md에서 확인합니다.
2. 의도된 워크플로와 사용 시점 가이드는 SKILL.md를 봅니다.
3. 서비스 포트를 변경하기 전에는 references/port-allocation-strategy.md를 읽습니다.
4. 앱이 Compose를 사용한다면 references/docker-compose-patterns.md를 확인합니다.
5. 프로덕션 저장소에서 자동화를 신뢰하기 전에 scripts/worktree_manager.py와 scripts/worktree_cleanup.py를 검토합니다.

이 과정이 중요한 이유는 스크립트가 실제 checkout을 다루고, env 파일을 복사하며, 의존성을 설치할 수도 있기 때문입니다. 큰 monorepo나 민감한 로컬 설정이 있는 repo에서 실행하기 전에는 기본값을 반드시 확인하세요.

실전 git-worktree-manager 사용 예

일반적인 생성 및 준비 흐름은 다음과 같습니다.

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

정리 전 검토 흐름은 다음과 같습니다.

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

두 도구 모두 --input <json-file> 또는 stdin을 통한 JSON 입력을 지원하므로 자동화에 유용합니다. 먼저 에이전트에게 명령 계획을 만들게 한 뒤, repo 경로, 브랜치 이름, base branch, 의존성 설치 동작, 정리 정책을 확인한 후에만 스크립트를 실행하세요.

더 좋은 결과를 위한 프롬프트 패턴

약한 프롬프트:

Set up a worktree for my feature.

더 나은 프롬프트:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

이렇게 요청하면 skill이 브랜치 전략을 선택하고, 포트 충돌을 피하며, .env* 파일을 안전하게 다루고, 계획과 실행을 분리하는 데 필요한 정보를 충분히 갖게 됩니다.

git-worktree-manager skill FAQ

git-worktree-manager는 AI 에이전트 전용인가요?

아닙니다. 이 skill은 멀티 에이전트 작업에 최적화되어 있지만, 스크립트와 규칙은 사람 개발자에게도 유용합니다. 핵심 이점은 반복 가능성입니다. 임시로 남은 shell history에 의존하는 대신, 모든 worktree가 예측 가능한 브랜치, 디렉터리, 포트, 복사된 env 파일, 정리 검토 절차를 갖게 됩니다.

일반 git worktree와 무엇이 다른가요?

일반 git worktree add는 또 하나의 checkout을 만들어 줍니다. 하지만 로컬 앱 충돌까지 해결하지는 않습니다. git-worktree-manager는 그 주변 워크플로를 추가합니다. 포트 블록, .worktree-ports.json, 환경 파일 복사, 선택적 의존성 설치, Docker Compose 격리 조언, 오래되었거나 병합된 브랜치에 대한 정리 점검이 포함됩니다.

초보자도 안전하게 사용할 수 있나요?

네, 무작정 명령을 실행하는 도구가 아니라 안내형 워크플로로 다룬다면 안전하게 사용할 수 있습니다. 초보자는 먼저 목록 조회나 검토 작업을 실행하고, --format text를 사용하며, 자동 삭제를 피하고, 실행 전에 생성된 명령을 확인하는 것이 좋습니다. 정리 스크립트는 dirty worktree를 확인하지만, 어떤 브랜치를 삭제해도 안전한지는 여전히 사용자가 이해하고 있어야 합니다.

이 skill을 쓰지 않는 편이 나은 경우는 언제인가요?

저장소의 환경 설정 방식이 특이하거나, 절대 복사하면 안 되는 secrets가 있거나, 의존성 설치 방식이 표준적이지 않거나, 서비스 포트를 사내 플랫폼이 관리한다면 그대로 사용하지 마세요. 이런 경우에는 git-worktree-manager guide를 출발점으로 삼고, 도입 전에 스크립트나 프롬프트를 직접 맞게 조정해야 합니다.

git-worktree-manager skill 개선 방법

git-worktree-manager에 더 강한 repo 맥락 제공하기

입력이 좋아질수록 worktree 계획도 더 안전해집니다. 다음 정보를 포함하세요.

• 절대 repo 경로
• 대상 브랜치와 base branch
• 원하는 worktree 디렉터리 이름
• package manager 또는 lockfile에 대한 기대 사항
• 포트가 필요한 서비스
• .env* 파일 복사 허용 여부
• 의존성 설치 허용 여부
• 정리 기준 일수와 병합 확인용 base branch

이렇게 하면 추측이 줄어들고, 에이전트가 앱에 맞지 않는 기본값을 가정하는 일을 막을 수 있습니다.

포트와 Docker Compose 규칙 조정하기

참조 전략은 앱 3000, Postgres 5432, Redis 6379 같은 기본 base port를 사용하고, worktree마다 10씩 간격을 둡니다. 스택에 서비스가 더 많다면 더 큰 연속 포트 블록을 예약하세요. 로컬 인프라를 worktree 밖에서 실행한다면 전체 충돌을 피하도록 base port를 다른 범위로 옮기는 것이 좋습니다.

Docker Compose에서는 worktree별 override, .env 기반 포트, 그리고 다음과 같은 고유한 project name을 선호하세요.

docker compose -p myapp_wt_auth up -d

이렇게 하면 브랜치 간 container, network, volume, database 충돌을 피할 수 있습니다.

흔한 실패 유형 주의하기

가장 흔한 문제는 secrets가 복사되는 것, 기본 데이터베이스 포트를 재사용하는 것, 호환되지 않는 마이그레이션 사이에서 Docker volume을 공유하는 것, 잘못된 런타임에서 의존성을 설치하는 것, 아직 커밋되지 않은 작업이 남아 있는 worktree를 삭제하는 것입니다. 매번 실행 후 에이전트에게 dirty 상태, 복사된 env 파일, 선택된 포트, 설치 동작을 보고하게 하세요.

정리 작업은 검토 전용 출력부터 시작하세요. worktree가 오래되었고, clean 상태이며, 예상한 base branch에 병합되었다는 점을 확인한 뒤에만 삭제를 활성화하세요.

첫 출력 이후 반복 개선하기

첫 계획이나 명령이 나온 뒤에는 처음부터 다시 요청하지 말고, 초점을 좁혀 수정 요청을 하세요.

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

이렇게 하면 skill이 저장소의 실제 제약을 계속 기준으로 삼으면서도 안전성과 재현성을 높일 수 있습니다.