git worktree와 EnterWorktree path로 서브에이전트 작업 디렉토리 분리하기 | Playbook Tip

서브에이전트 두 개를 같은 브랜치에서 동시에 돌리면 파일 충돌이 생겨요. 한 에이전트가 feature/auth를 고치는 동안 다른 에이전트가 같은 파일을 건드리면, 결과물이 섞이거나 작업이 덮어씌워지는 일이 실제로 생기더라고요. git worktree를 쓰면 브랜치마다 별도 디렉토리를 만들 수 있고, v2.1.105부터 추가된 EnterWorktree의 path 파라미터 덕분에 서브에이전트가 이미 만들어진 워크트리로 바로 전환할 수 있어요.

기존에는 EnterWorktree가 새 워크트리를 만드는 용도로만 쓰였는데, path를 넘기면 이미 존재하는 워크트리 경로로 작업 디렉토리를 전환해요. 에이전트마다 워크트리를 미리 만들어두고, 각자 자기 경로로 들어가서 작업하는 구조가 되는 거예요.

준비물

Claude Code v2.1.105 이상
git 2.5 이상 (worktree 지원)
서브에이전트를 쓰는 Claude Code 프로젝트

스텝

1. 워크트리 두 개 미리 만들기

서브에이전트가 들어갈 디렉토리를 먼저 만들어야 해요. 에이전트가 실행되기 전에 워크트리가 존재해야 path로 전환할 수 있거든요.

# 프로젝트 루트에서 실행
git worktree add ../worktrees/agent-auth feature/auth
git worktree add ../worktrees/agent-api feature/api-refactor

이렇게 하면 ../worktrees/agent-auth와 ../worktrees/agent-api 디렉토리가 각각 다른 브랜치를 체크아웃한 상태로 생겨요.

2. 워크트리 목록 확인

제대로 만들어졌는지 확인하는 명령어예요. 경로와 브랜치가 맞게 연결됐는지 여기서 보면 돼요.

git worktree list

출력 예시:

/Users/me/myproject              abc1234 [main]
/Users/me/worktrees/agent-auth   def5678 [feature/auth]
/Users/me/worktrees/agent-api    ghi9012 [feature/api-refactor]

3. 서브에이전트 프롬프트에 path 지정

서브에이전트를 호출할 때 EnterWorktree 툴에 path를 넘겨요. 에이전트가 해당 워크트리 디렉토리에서 작업을 시작하게 돼요.

# 오케스트레이터 프롬프트 예시 (YAML 형태로 구조 표현)
subagents:
  - name: auth-agent
    tool: EnterWorktree
    params:
      path: /Users/me/worktrees/agent-auth
    task: "feature/auth 브랜치에서 JWT 미들웨어 구현"

  - name: api-agent
    tool: EnterWorktree
    params:
      path: /Users/me/worktrees/agent-api
    task: "feature/api-refactor 브랜치에서 라우터 정리"

실제 Claude Code 프롬프트에서는 자연어로 경로를 명시해줘도 돼요.

EnterWorktree path=/Users/me/worktrees/agent-auth 로 전환한 뒤
feature/auth 브랜치에서 JWT 미들웨어를 구현해줘.

4. 각 에이전트 작업 후 커밋

각 워크트리는 독립된 브랜치라서 커밋이 서로 섞이지 않아요.

# agent-auth 워크트리에서
cd ../worktrees/agent-auth
git add -A && git commit -m "feat: JWT middleware 구현"

# agent-api 워크트리에서
cd ../worktrees/agent-api
git add -A && git commit -m "refactor: 라우터 구조 정리"

확인 방법

에이전트가 올바른 워크트리에서 작동했는지는 각 브랜치의 커밋 로그로 확인해요.

git log feature/auth --oneline -5
git log feature/api-refactor --oneline -5

두 브랜치에 각각 다른 커밋이 쌓여 있으면 분리가 잘 된 거예요.

응용

워크트리를 3개 이상으로 늘려도 구조는 똑같아요. 에이전트 수만큼 워크트리를 만들고, 각 에이전트에 path만 다르게 넘기면 돼요. 작업이 끝난 워크트리는 git worktree remove ../worktrees/agent-auth로 정리할 수 있어요.

트러블슈팅

"fatal: '/path/to/worktree' is not a working tree" 에러가 나오면 git worktree list로 경로가 실제로 등록됐는지 확인해요. git worktree add를 먼저 실행하지 않으면 path로 전환이 안 돼요.

브랜치가 이미 체크아웃됐다는 에러는 같은 브랜치를 두 워크트리에 동시에 연결하려 할 때 나와요. 워크트리마다 브랜치를 다르게 써야 해요.

이 설정으로 에이전트 두 개가 완전히 다른 디렉토리에서 작업하게 되니까, 파일 충돌 걱정 없이 병렬 작업을 돌릴 수 있게 돼요.

준비물

스텝