git worktree를 활용하여 Codex, Claude Code 등과 함께 작업을 병렬화하기

Source: Dev.to

문제

전통적인 Git 저장소에서는 다음과 같은 구조를 가집니다:

• 작업 디렉터리 안의 소스 코드, 예: /Users/qlerebours/Projects/traveledmap.
• 체크아웃된 브랜치, 예: feat/my-main-feature.
• 프로젝트 히스토리를 담고 있는 .git 폴더.

브랜치를 전환하면 현재 디렉터리의 파일이 바뀌어 Codex, Claude Code 등과 같은 도구를 여러 기능에 동시에 적용하기가 어렵습니다. 프로젝트를 두 번째 폴더에 복제하는 방법은 (잠재적으로 큰) .git 폴더가 중복되기 때문에 이상적이지 않습니다.

git worktree

git worktree는 동일한 Git 저장소에 여러 작업 디렉터리를 연결하면서 단일 .git 디렉터리를 유지하도록 해줍니다.

# Add a new worktree for a parallel task
git worktree add ../traveledmap-fix-wording fix/add-form-validations

명령을 실행하면 폴더 구조는 다음과 같이 됩니다:

/Users/qlerebours/Projects/traveledmap/                     (branch feat/my-main-feature)
/Users/qlerebours/Projects/traveledmap-fix-add-form-validations/  (branch fix/add-form-validations)

• 단일 .git 폴더는 /Users/qlerebours/Projects/traveledmap/에 존재합니다.
• 각 워크트리는 자체 브랜치를 사용합니다.
• 커밋은 모든 워크트리에서 즉시 보입니다.

이 설정을 통해 코드 어시스턴트가 두 기능을 병렬로 작업할 수 있습니다.

AI 개발 어시스턴트와 git worktree 사용

1. Start a new conversation in Codex (or Claude Code) and choose Worktree and from develop as the base for the new branch.
   → Codex(또는 Claude Code)에서 새 대화를 시작하고 Worktree와 from develop를 새 브랜치의 기반으로 선택합니다.

2. When you send the prompt, Codex announces that it’s creating the worktree. You can verify it with:

   git worktree list

3. The worktree will appear under a path similar to /Users/qlerebours/.codex/worktrees//traveledmap.
   → 워크트리는 /Users/qlerebours/.codex/worktrees//traveledmap와 유사한 경로에 나타납니다.

변경 사항 테스트

로컬에 풀링하지 않고 변경 사항을 테스트하려면:

1. Enter the worktree folder.
   → 워크트리 폴더에 들어갑니다.

2. Since the worktree starts from the develop branch, set up the environment:

   cp .env.example .env
   pnpm i

3. Run the project:

   pnpm run dev

4. If new changes are needed, Codex will add them to the existing worktree so you can test again.
   → 추가 변경이 필요하면 Codex가 기존 워크트리에 적용하므로 다시 테스트할 수 있습니다.

변경 사항 제어하기

로컬에서 작업을 계속할 수 있는 여러 옵션이 있습니다:

• Open the worktree folder in your preferred code editor and make the desired changes.
  → 워크트리 폴더를 선호하는 코드 편집기에서 열고 원하는 변경을 수행합니다.
• Use the “Hand off to local” button in the Codex conversation; this commits the changes to the repository.
  → Codex 대화에서 “Hand off to local” 버튼을 사용하면 변경 사항이 저장소에 커밋됩니다.
• Use the “Create a branch” button, which creates a new branch and pushes it, allowing you to open a PR directly.
  → “Create a branch” 버튼을 사용하면 새 브랜치를 만들고 푸시하여 바로 PR을 열 수 있습니다.

추가 자료

The full documentation for this workflow is available in the Codex docs.

Understanding git worktree opens the door to efficient collaboration with AI development assistants. If you have questions, feel free to reach out by email or on LinkedIn.