Claude Code 서브에이전트 기능을 소개하는 공식 발표 이미지
이미지: claude.com/blog (How and when to use subagents in Claude Code)

서브에이전트 두세 개를 동시에 돌려서 각각 다른 파일을 리팩터링시킬 때, 가끔 둘이 같은 파일을 건드리는 경우가 있습니다. 한쪽이 Edit을 거는 사이 다른 쪽도 같은 파일을 읽고 수정하면, 둘 중 하나의 변경이 그냥 덮어써지거나 머지 충돌처럼 꼬입니다. 서브에이전트가 "어떤 파일을 건드릴지"는 매번 제가 미리 정확히 나눠줄 수 있는 게 아니라서, 매번 겹치지 않게 지시문을 쓰는 것도 피곤한 일이었습니다.

어떤 작업이었나

Claude Code 서브에이전트가 각자 독립된 git worktree에서 돌게 만드는 isolation: worktree 옵션이 있다는 걸 문서에서 보고, 실제로 어떻게 동작하는지 직접 띄워서 확인해봤습니다.

AI를 어떻게 활용했나

Agent 호출에 isolation: "worktree"를 붙이면 됩니다.

Agent({
  description: "워크트리 격리 동작 확인",
  isolation: "worktree",
  prompt: "pwd, git branch --show-current, git worktree list를 실행하고 결과를 그대로 보고해줘.",
})

받은 결과는 이렇습니다.

$ pwd
/home/user/twothumb/.claude/worktrees/agent-ac6607af76d4f1802

$ git branch --show-current
worktree-agent-ac6607af76d4f1802

$ git worktree list
/home/user/twothumb                                            8358bba [main]
/home/user/twothumb/.claude/worktrees/agent-ac6607af76d4f1802  8358bba [worktree-agent-ac6607af76d4f1802] locked

서브에이전트가 메인 체크아웃이 아니라 .claude/worktrees/agent-<id>/라는 별도 디렉토리에서, worktree-agent-<id>라는 전용 브랜치를 체크아웃한 채로 시작한다는 걸 확인했습니다. 작업이 끝나기 전까지는 locked 상태라서 다른 정리 작업이 이 워크트리를 건드리지 못합니다.

이 서브에이전트는 아무 파일도 고치지 않고 끝났는데, 작업 종료 후 바로 git worktree list를 다시 찍어보니 해당 워크트리와 브랜치가 모두 사라져 있었습니다. 변경사항이 없는 워크트리는 자동으로 치워진다는 문서 설명 그대로였습니다.

그다음은 격리가 실제로 "강제"되는지가 궁금해서, 서브에이전트에게 자기 워크트리가 아니라 메인 체크아웃의 package.json을 직접 고쳐보라고 시켰습니다. 돌아온 에러는 이랬습니다.

This agent is isolated in the worktree /home/user/twothumb/.claude/worktrees/agent-a3c38ae3ff21cf069.
Edit the worktree copy of this file instead of the shared-checkout path.

Edit 자체가 거부됩니다. 서브에이전트가 "메인 체크아웃 경로를 수정해줘"라고 요청하더라도 Claude Code가 그 요청을 승인 여부와 무관하게 아예 막는 구조입니다.

결과와 얻은 팁

  • 두 서브에이전트가 같은 파일을 동시에 건드릴 위험이 있는 작업(여러 파일에 걸친 리팩터링, 대규모 네이밍 변경 등)은 커스텀 서브에이전트 frontmatter에 isolation: worktree를 박아두면 아예 겹칠 일이 없어집니다. 파일 단위로 작업을 미리 쪼개줄 필요가 사라집니다.
  • 격리된 서브에이전트가 메인 체크아웃을 직접 손대려는 시도는 Edit/Write뿐 아니라 git -C로 메인 저장소를 가리키는 명령, 메인 체크아웃 안에서 실행되는 Bash 명령까지 전부 막힙니다. cp처럼 git을 거치지 않는 셸 명령은 이 체크에 안 걸린다고 문서에 나와 있어서, 완전히 빈틈없는 샌드박스는 아니라는 점은 감안해야 합니다.
  • 변경 없이 끝난 워크트리는 바로 정리되지만, 뭔가 고친 워크트리는 디스크에 남아 있다가 주기적인 정리 스윕에서 처리됩니다. 서브에이전트가 작업 중간에 실패해서 결과를 못 받았다면, git worktree list로 남은 워크트리를 확인해보는 게 좋습니다.
  • 서브에이전트가 작업을 시작할 때 읽는 CLAUDE.md나 프로젝트 설정은 메인 체크아웃 기준으로 불러온 걸 그대로 쓰고, 워크트리 자체의 루트에 있는 설정은 보지 않습니다. 워크트리 안에 별도 설정 파일을 따로 넣어둬도 서브에이전트는 모른다는 뜻입니다.