Claude Code × git worktree로 메인 환경을 더럽히지 않고 Issue를 병렬 처리하기

VSCode에서 Claude Code에게 Issue 대응을 맡기고 있다 보면, 다음과 같은 것들을 하고 싶다는 생각이 들었습니다.

• Claude가 하나의 Issue를 작업하는 동안, 로컬 환경에서 다른 Issue도 병렬로 진행하고 싶다
• 메인 VSCode에서는 dev 서버를 실행해 둔 채로 다른 작업을 하고 있으며, 방해받고 싶지 않다
• Claude의 작업이 끝나면, 즉시 로컬 브라우저에서 동작 확인을 하고 싶다. OK라면 그대로 PR을 만들어 주길 바란다
• 클라우드에서 완결되는 AI도 있지만, 익숙한 VSCode를 사용하여 차분(diff) 열람과 검증도 하고 싶다.

해결 접근법으로서, git의 worktree라는 기능과 커스텀 슬래시 명령어(custom slash command)를 사용했습니다.

git worktree를 사용하면, 하나의 리포지토리(repository)로부터 여러 개의 독립된 작업 디렉토리를 만들 수 있습니다 (파일 편집이 서로 충돌하지 않으며, git 히스토리는 공유됨). 이를 Claude Code의 커스텀 슬래시 명령어로 자동화했습니다.

동작 이미지는 다음과 같습니다.

• /issue <GitHub Issue 번호>로 작업해주길 원하는 issue를 지정 (수동) - git worktree 자동 생성 (자동)
• VSCode가 별도의 창으로 실행됨 (자동)
• 신규 VSCode의 터미널이 자동으로 실행되어, /issue-work가 실행되며 작업을 시작함 (자동)

이번에 작성한 /issue와 /issue-work를 커스텀 슬래시 명령어로 Claude Code가 읽어들일 수 있는 형태로 만듭니다.

~/.claude/commands/에 두면, 모든 리포지토리 공통으로 사용할 수 있습니다.

다음 텍스트를 복사하여 사용합니다.

/issue (VSCode 런처)

---
description: Issue 번호로부터 worktree를 생성하고, 새로운 VSCode 창에서 Claude 작업 세션을 자동 기동한다 (런처)
argument-hint: <issue 번호>
...
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "claude-issue-worker",
"type": "shell",
"command": "claude \"/issue-work $ARGUMENTS\"",
"runOptions": { "runOn": "folderOpen" },
"presentation": { "focus": true, "panel": "dedicated" },
"problemMatcher": []
}
]
}

5. code <worktree의 절대 경로>로 새로운 VSCode 창을 연다.
6. 다음을 보고하고 종료한다:

• worktree의 경로와, 새 창에서 /issue-work $ARGUMENTS가 자동 기동되는 것
  ...

## `/issue-work` (작업 담당)

---

description: worktree 내에서 Issue 구현 ~ 동작 확인 대기 ~ PR 생성까지 진행한다 (/issue로부터 자동 기동되는 작업 담당)
argument-hint: <issue 번호>
...

실제 동작 원리입니다. 건너뛰어도 문제없습니다.

`/issue (런처)`: 환경 구축만 담당. 메인 체크아웃(checkout)에는 일절 손대지 말 것을 엄명. 동일한 세션에서 차례차례 Issue를 디스패치(dispatch)할 수 있음.

`/issue-work (작업 담당)`: 새 창 측에서 자동 기동되어, 구현 ~ 확인 대기까지를 담당.

메인 터미널 (디스패처)
─────────────────────────────

1. claude를 기동하여 /issue 17 커맨드를 수락
   ...

- 작업이 끝나면 push와 PR 생성을 자동으로 수행하고 worktree도 삭제하여 완료될 때까지 자동화해도 좋을 것 같습니다. AI가 push하기를 원하지 않았기에, 이번에는 포함하지 않았습니다.
- 여담이지만, Claude가 작업을 완료했을 때 소리가 나도록 설정하면 능률이 오릅니다.