모든 글
뉴스 해석2026-09-219 min read

에이전트 열 개를 막는 건 아키텍처가 아니라 3000번 포트다

worktree 관리 도구의 기능 목록에서 읽히는 것들. 격리되는 건 파일뿐이고 전역 자원은 하나다. 그리고 격리가 잘 될수록 충돌은 머지 시점으로 미뤄진다.

에이전트를 열 개 띄우지 못하는 이유는 대개 아키텍처가 아니다. 3000번 포트 하나다.

git worktree 관리 도구의 기능 목록을 읽다가 이 문장에서 멈췄다 — worktree마다 해시로 다른 개발 서버 포트를 배정한다는 항목. 사소해 보이는데, 병렬 작업을 실제로 해본 사람은 그게 왜 거기 있는지 안다.

출처: github.com/max-sixty/worktrunk

확인된 것

저장소와 GitHub API에서 직접 확인한 것만 적는다.

  • Rust로 작성된 git worktree 관리 CLI. 2025-10-17 생성, 마지막 푸시 2026-09-21. 별 8,224, 포크 284, 열린 이슈 43.

  • 전제를 README가 직접 밝힌다.

    AI agents like Claude Code and Codex can handle longer tasks without supervision, such that it's possible to manage 5-10+ in parallel.

  • 해결하려는 마찰도 구체적이다. worktree 하나 만드는 데 브랜치 이름을 세 번 친다 — git worktree add -b feat ../repo.feat 다음에 cd ../repo.feat. 이걸 wt switch -c -x claude feat 한 줄로 줄인다. 정리는 wt remove.

  • 빌드 캐시 공유 기능이 있다. 설명은 이렇다.

    ten worktrees get target/, node_modules/, etc without building or copying them (on APFS, btrfs, and XFS)

  • hash_port 템플릿 필터가 worktree마다 고유한 개발 서버 포트를 만든다.

  • 그 밖에: 생성·머지 전후 훅, LLM 커밋 메시지 생성, 브랜치별 LLM 요약이 붙는 wt list --full, wt switch pr:123, 스쿼시·리베이스·머지·정리를 한 명령으로 묶은 머지 워크플로.

  • 라이선스는 MIT OR Apache-2.0 이중이다. GitHub API는 NOASSERTION으로 표시하는데, 이건 이중 라이선스를 분류하지 못해서다.

판단

1. 병렬화를 막는 것은 전역 자원이다

hash_port가 기능 목록에 있다는 사실이 이 도구가 실제 사용에서 나왔다는 증거다. 에이전트 두 개를 동시에 돌려본 사람은 두 번째가 EADDRINUSE로 죽는 걸 본다.

그리고 포트는 시작일 뿐이다. 로컬 DB 이름, 캐시 디렉터리, .env의 고정 경로, 로그 파일, 로컬에 띄운 큐나 스토리지 에뮬레이터, 개발용 웹훅 터널 주소. worktree가 격리해주는 건 파일이고, 그 밖의 전역 자원은 그대로 하나다.

→ 병렬 에이전트를 시도하기 전에 할 일은 도구 설치가 아니다. 내 프로젝트가 붙잡는 전역 자원 목록을 먼저 적어라. 포트, 디렉터리, DB, 외부 계정. 그 목록이 짧으면 병렬이 되고 길면 도구를 깔아도 안 된다.

2. 진짜 비용은 RAM이 아니라 디스크와 빌드 시간이다

어제는 세션 메모리 이야기를 썼는데, worktree 방식의 병렬에서는 다른 자리에서 비용이 나온다. worktree 열 개면 node_modules와 target도 열 벌이다. 용량도 용량이지만 각각을 처음부터 빌드하는 시간이 더 아프다.

Worktrunk는 이걸 APFS·btrfs·XFS의 copy-on-write로 푼다. 복사도 빌드도 없이 공유하고, 각 worktree가 수정하는 부분만 갈라진다.

→ 여기서 따라 나오는 전제 조건이 하나 있다. 파일시스템이 지원해야 한다. ext4로 포맷된 리눅스 서버에서는 이 기능이 붙지 않는다. 병렬 에이전트를 진지하게 할 생각이면 도구를 고르기 전에 df -T를 한 번 쳐보는 게 순서다.

3. worktree는 파일 충돌을 막지, 논리 충돌은 못 막는다

각자 디렉터리를 가지면 같은 파일을 동시에 저장해서 덮어쓰는 사고는 사라진다. 그건 확실한 이득이다.

그런데 같은 타입 정의를 서로 다르게 바꾸는 열 개 브랜치는 각자 잘 돌고 테스트도 통과한 뒤 머지할 때 터진다. 어제 "같은 파일을 건드리는 열 개 세션은 열 배 충돌"이라고 썼는데, 정확히 말하면 충돌이 사라지는 게 아니라 작업 중에서 머지 시점으로 미뤄진다. 그리고 미뤄진 충돌은 더 비싸다 — 열 개가 이미 완성된 뒤에 발견되기 때문이다.

→ 그래서 병렬 작업을 나눌 때 기준은 파일이 아니라 인터페이스 경계여야 한다. 같은 타입, 같은 API 스키마, 같은 DB 마이그레이션을 건드릴 작업 둘은 병렬로 돌리지 말고 순서대로 돌린다. 격리 도구가 좋아질수록 이 규칙이 더 중요해진다. 격리가 잘 될수록 충돌을 늦게 발견하기 때문이다.

4. LLM 커밋 메시지는 내가 끄고 쓸 기능이다

도구에 있는 기능이고 편리할 것이다. 그런데 이번 주 내내 같은 결론에 도달했다 — 에이전트를 늘리면 늘어나는 건 코드가 아니라 읽어야 할 diff다.

커밋 메시지는 사람이 그 diff를 읽었다는 거의 유일한 증거다. 자동 생성하면 읽지 않은 변경이 읽은 것처럼 기록된다. 몇 달 뒤 git log를 뒤질 때, 그 메시지가 저자의 의도인지 diff의 재서술인지 구분할 방법이 없어진다.

브랜치 목록에 붙는 요약(wt list --full)은 다르다. 그건 훑어보기용이고 저장소에 남지 않는다. 남는 기록과 지나가는 보조를 구분하는 게 맞다고 본다. 이건 도구의 주장이 아니라 내 판단이다.

모르는 것

  • 직접 써보지 않았다. 저장소 README와 API 메타데이터를 읽은 결과다.
  • CoW 공유가 어떤 경우에 깨지는지 모른다. 빌드 도구가 파일을 제자리에서 수정하는 방식이면 갈라지는 양이 커질 텐데, 실제 증가폭에 대한 수치가 없다.
  • 저자가 말하는 "5-10+ 병렬"이 어떤 작업 유형에서 성립하는지 명시돼 있지 않다. 서로 독립적인 버그 수정 열 개와, 한 기능을 쪼갠 열 개는 완전히 다른 얘기다.
  • 머지 워크플로가 충돌을 만났을 때 어떻게 처리하는지 확인하지 못했다.
  • 별 8,224에 열린 이슈 43이면 비율은 건강해 보이지만, 내가 이슈 내용을 읽어본 건 아니다.

덧. 어제 라이선스 이야기를 쓰면서 "GitHub이 NOASSERTION으로 표시하면 LICENSE를 직접 열어보라"고 했다. 이 저장소가 바로 그 표시인데, 열어보니 MIT과 Apache-2.0 이중 라이선스라 분류가 안 된 것뿐이었다. 규칙은 경보가 아니라 확인 절차다. 확인해서 아무 문제 없는 쪽이 대부분이고, 그래도 확인은 해야 한다.

댓글

불러오는 중...

모든 글로 돌아가기