여기서 worktree가 유용한 이유는 "브랜치 두 개를 동시에 체크아웃할 수 있다"는 점이 아닙니다.

멀티 에이전트 작업 때문입니다.

같은 폴더에서 세션 두 개를 돌리면 실패 양상은 뻔합니다.

• 에이전트들이 같은 파일을 건드리고
• diff가 뒤엉키고
• 어떤 변경이 어떤 작업 것인지 흐름을 놓칩니다

간단한 규칙 하나로 대부분 해결됩니다.

작업마다 worktree 하나

그러면 이런 일을 서로 방해하지 않고 병렬로 할 수 있습니다.

• Claude Code 세션 하나는 리팩터링
• Codex 세션 하나는 테스트
• OpenCode 세션 하나는 문서

이 가이드는 그 워크플로를 다룹니다.

간단한 정의: worktree란 무엇이고 에이전트에 왜 도움이 되나

Git 공식 문서는 worktree를 같은 저장소에 연결된 여러 작업 트리를 관리해 한 번에 둘 이상의 브랜치를 체크아웃할 수 있게 하는 방법으로 설명합니다. (출처: https://git-scm.com/docs/git-worktree)

멀티 에이전트 작업에서 중요한 점은 더 단순합니다.

• 각 worktree는 격리된 폴더이고
• 각 에이전트는 자기 폴더를 가집니다

그래서 "이 파일을 누가 바꿨지?"는 추리가 아니라 디렉터리를 보면 답이 나오는 질문이 됩니다.

흔한 방법과 무너지는 지점

• 브랜치 하나, 폴더 하나, 에이전트를 순서대로: 안전하지만 느립니다.
• 폴더 하나에 에이전트 여러 개: 빠르지만 지저분합니다.
• 작업 사이마다 stash와 복원: 할 만하지만 자주 하면 실수하기 쉽습니다.

빠르면서 안전하다고 느껴진 첫 방법이 worktree였습니다.

잘 통하는 워크플로

이 워크플로는 Happier를 제어 지점으로 씁니다. Happier는 Claude Code, Codex 등 여러 에이전트를 크로스 디바이스로 실행하고 오케스트레이션할 수 있는 오픈 소스 앱입니다.

한곳에서 두 가지를 제공합니다.

• 세션: 기기를 오가며 Claude Code, Codex, OpenCode 세션을 시작하고 모니터링합니다
• 세션별 파일과 Git: 각 세션은 폴더 하나에 연결되므로 Files와 Git 탭에는 그 폴더만 표시됩니다

트레이드오프: 컴퓨터는 여전히 온라인이어야 합니다.

Happier가 처음이라면 (무엇이고 어디서 받는지)

Happier는 신뢰하는 컴퓨터에서 세션을 실행하고 휴대폰에서 관리할 수 있게 해 주는 오픈 소스 컴패니언 앱(모바일, 웹, 데스크톱)입니다.

설정하기:

• GitHub: https://github.com/happier-dev/happier
• 설치 및 다운로드: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

패턴: 작업마다 worktree 하나

단순한 형태:

1. 작업 A용 worktree를 만든다
2. 작업 B용 worktree를 만든다
3. 각각에서 세션을 하나씩 실행한다
4. worktree마다 따로 리뷰하고 커밋한다

이 가이드에서 하나만 가져간다면 이것입니다.

단계별 안내

1) 정말 병렬로 하고 싶은 작업 고르기

병렬화는 도구입니다.

병렬에 좋은 작업:

• 테스트와 문서
• 리팩터링과 작은 UI 수정
• 버그 수정과 마이그레이션 계획 작성

병렬에 나쁜 작업:

• 두 에이전트가 같은 핵심 파일 묶음을 편집하는 경우

2) worktree 만들기

순수 Git이라면 git worktree add ...로 연결된 worktree를 만듭니다. (출처: https://git-scm.com/docs/git-worktree)

실제로 중요한 것은 결과입니다.

• 각자 자기 브랜치를 체크아웃한 폴더 두 개

3) worktree 폴더마다 세션 하나 시작하기

Happier에서 새 Claude Code, Codex, OpenCode 세션을 시작하고 작업 디렉터리로 worktree 폴더를 고르세요. 두 번째 worktree도 똑같이 합니다.

세션이 자기 폴더에 묶여 있으므로 각 세션의 Git 탭은 변경이 섞이지 않는 worktree별 diff, 커밋, 푸시 화면이 됩니다.

깔끔하게 유지하는 습관:

• 세션 이름을 worktree나 작업 이름으로 짓기
• 세션 범위를 한정하기("이 worktree의 파일만 건드릴 것")

4) 한곳에서 세션 모니터링하기

여러 세션이 돌기 시작하면 모든 대화 기록을 읽는 것이 목표가 아닙니다.

목표는:

• 어떤 세션이 활성인지 보고
• 승인을 처리하고
• 후속 메시지를 하나 보내는 것

그리고 무언가 끝나면:

• 그 세션의 Git 탭을 열고
• diff를 리뷰하고
• 커밋하고 푸시합니다(Git 쓰기 작업은 실험 기능이며 기본적으로 꺼져 있습니다. Git 문서 참고)

5) worktree별로 리뷰하고 커밋하기

안전 규칙:

• 여러 worktree에 걸친 변경을 한 커밋에 넣지 않기

그렇게 하면 격리의 이점을 잃습니다.

터미널 (선택)

내장 터미널을 쓸 수 있으면 세션에 Terminal 탭이 표시됩니다. 기능 매트릭스에 따르면 실험 기능입니다.

grep이나 간단한 status 확인 같은 일회성 명령에 쓰고, 주된 워크플로로 삼지는 마세요.

자주 묻는 질문

worktree 없이 브랜치만 쓰면 안 되나요?

한 폴더에서 브랜치를 바꾸면 stash나 WIP 커밋에 기대게 되기 때문입니다.

worktree는 작업을 그 자리에 둔 채로 유지하게 해 줍니다.

worktree마다 에이전트가 하나씩 필요한가요?

항상 그렇지는 않습니다.

하지만 에이전트를 병렬로 돌린다면 worktree마다 에이전트 하나가 충돌을 막는 쉬운 방법입니다.

흔한 큰 실수는?

worktree를 만들어 놓고 여전히 같은 폴더에서 에이전트 여러 개를 돌리는 것입니다.

격리는 실제로 써야 효과가 있습니다.

worktree와 세션 이름은 어떻게 짓나요?

휴대폰 화면에서 바로 이해되는 이름으로 하세요.

• worktree: hotfix-<ticket> / docs-<topic> / tests-<area>
• 세션: worktree 이름에 에이전트를 덧붙이기(예: "hotfix-123 (Codex)")

병렬 세션은 몇 개부터 "너무 많은" 건가요?

개수 자체가 아니라 여전히 안전하게 리뷰할 수 있느냐의 문제입니다.

무난한 기본값은 병렬 세션 2~3개입니다.

• 하나는 주요 변경
• 하나는 부차적인 작업(테스트나 문서)
• 선택적으로 하나는 리뷰나 확인

에이전트가 엉뚱한 worktree를 건드리지 않게 하려면?

두 가지 습관이 크게 도움이 됩니다.

1. 첫 메시지에 worktree 이름을 넣기: "<worktree-name>에서만 작업하세요."
2. 처음 몇 단계 뒤에 중간 요약을 요청하기.

키보드 앞에 없을 때일수록 분명하게 말해 둘 가치가 있습니다.

여러 세션이 돌 때 "휴대폰 확인 루프"는?

간단한 루프:

1. Happier를 연다
2. 어떤 세션이 활성인지 확인한다
3. 승인을 처리한다
4. 짧은 후속 메시지를 하나 보낸다(또는 "멈추고 요약해 줘")
5. 세션이 끝나면 그 worktree의 diff를 리뷰하고 커밋한다

목표는 휴대폰으로 깊은 코딩을 하려 하지 않으면서 통제권을 유지하는 것입니다.

각 에이전트의 작업을 안전하게 리뷰하려면?

각 worktree를 독립된 리뷰와 커밋 단위로 다루세요.

• Source control → Changed files → ↓ Review
• 범위가 좁은 메시지로 커밋하기
• 확신이 들 때만 푸시하기

두 에이전트가 같은 파일을 건드려야 한다면?

그때는 병렬화의 도움이 줄어듭니다.

선택지:

• 작업을 순서대로 하기(에이전트 A 다음 에이전트 B)
• 코드베이스의 다른 부분을 건드리도록 작업 나누기
• 한 에이전트가 변경하고 다른 에이전트가 리뷰하기

휴대폰에서만 유용한가요?

아니요. 하지만 휴대폰에서 특히 유용합니다.

worktree는 파일 시스템을 깔끔하게 유지합니다.

Happier를 쓰면 모바일, 데스크톱, 웹 어디서든 같은 곳에서 세션을 모니터링하고 리뷰와 커밋을 할 수 있습니다.

관련 가이드

• 휴대폰에서 컴퓨터의 Git worktree 관리하기
• 휴대폰을 원격 Git 클라이언트로 쓰기
• 휴대폰에서 컴퓨터의 파일 편집하기