배경

본고는 2026년 6월 30일에 개최된 「코딩 에이전트 하네스 엔지니어링 LT 대회!!」에서의 발표를 배경으로 하고 있다.

슬라이드상에서는 생략하고 구두로 설명한 내용을 문서로 보충함으로써, 이벤트에 참가하지 않은 사람도 동일 수준 이상의 정보를 얻을 수 있는 경로를 확보하는 것이 본고의 목적이다.

발표에 사용한 슬라이드는 다음과 같다.

AI 에이전트의 복수 실행·병렬 작업

코딩 에이전트를 사용한 개발이 상당히 친숙해졌다.

에이전트의 등장 이후 「복수의 AI 에이전트를 기동하여, 복수의 태스크를 병행하여 진행하고 싶다」라는 발상의 등장은 꽤 빨랐던 것 같다.

실제로 AI 에이전트를 몇 개나 동시에 돌리고 있는지, 어떻게 복수의 태스크를 병렬화하고 있는지에 대한 화제는 자주 눈에 띈다.

그곳에는 「복수의 AI를 병렬로 돌리면 돌릴수록, AI를 잘 다루고 있다」라는 발상이 있는 것 같다.

하지만 실제로 해보면, 단순히 에이전트의 수를 늘리면 되는 문제가 아니라는 것을 알 수 있다.

복수의 에이전트를 동일한 프로젝트 상에서 구동하려면, 각각의 작업 공간을 분리할 필요가 있다.

게다가 작업 공간을 분리하더라도, 복수의 에이전트가 동일한 파일을 편집하여 컨플릭트 (Conflict)가 발생하는 문제도 남는다.

전자는 git worktree로 대응할 수 있다. 다만, 커맨드 사용법이 약간 번거롭다.

후자에 관해서는 git worktree 단독으로는 특별한 지원이 없으며, 별도의 대응이 필요하다.

그 부분을 간편하고 안전하게 다루기 위해, 최근 git-kura라는 Git 서브 커맨드를 만들고 있다.

이 기사에서는 AI 에이전트에 의한 병행 개발에서 git worktree가 왜 편리한지, 그 위에 무엇이 부족한지, 그리고 git-kura로 무엇을 해결하려고 하는지를 정리한다.

git worktree와 AI 에이전트

복수의 AI 에이전트에게 동일한 프로젝트에서 병행 작업을 시키고 싶을 때, 우선 문제가 되는 것은 작업 장소이다.

1개의 디렉토리 상에서 복수의 에이전트를 동시에 구동하면, 어떤 에이전트가 어떤 파일을 변경했는지, 어떤 차분(diff)이 어떤 태스크에 대응하는지가 금방 뒤섞인다.

그래서 최근 주목받고 있는 것이 git worktree이다.

git worktree는 동일한 repository에 복수의 working tree를 연결하기 위한 메커니즘이다. 예를 들어, 리포지토리 본체가 /path/main에 있다고 가정하면, 다음과 같은 커맨드를 실행할 수 있다.

git worktree add /path/other/test-next next

이 경우, /path/other/test-next라는 별도의 디렉토리에 next branch에 대응하는 worktree가 만들어진다.

포인트는 리포지토리 본체가 /path/main에 있는 반면, 추가된 worktree는 /path/other/test-next라는 별도의 경로에 존재한다는 것이다.

즉, 작업 공간 자체가 분리된다.

AI 에이전트 A에게는 worktree A를, AI 에이전트 B에게는 worktree B를 사용하게 한다. 그렇게 하면 양측은 서로 독립된 작업 영역에서 서로 간섭하지 않고 작업을 진행할 수 있다.

git worktree 자체는 AI 에이전트 이전부터 있던 Git의 메커니즘이지만, 복수 에이전트에 의한 병행 작업과 궁합이 좋았기 때문에 다시금 주목받고 있는 것이라고 생각한다.

git branch와 git worktree를 책상으로 생각하기

git branch와 git worktree의 차이에 대해, 책상과 서류의 비유로 생각해 본다.

책상 위에 작업용 서류가 산더미처럼 쌓여 있고, 보관함에는 그 외에도 다양한 작업용 자료가 산더미처럼 쌓여 있다. 작업할 수 있는 것은 책상 위에 있는 서류뿐이라고 가정하자.

git branch 운용의 경우, 준비된 책상은 1개이다. 복수의 branch는 존재하지만, 그것은 여기서 말하는 「보관함에 산더미처럼 쌓여 있는」 상태에 있다.

실제로 작업할 수 있는 것은 현재 그 책상 위에 전개되어 있는 branch뿐이다.

다른 branch에서 작업하고 싶다면, git switch 등으로 책상 위의 서류를 교체하게 된다.

이것의 반복을 통해, 한 곳에서 여러 종류의 작업을 가능하게 하는 것이 git branch의 효능이라고 할 수 있을 것이다.

반면, git worktree는 책상 그 자체를 늘리는 이미지다.

worktree A라는 책상에는 branch A의 서류가 놓여 있다.

worktree B라는 책상에는 branch B의 서류가 놓여 있다.

작업을 바꾸고 싶을 때는 책상 위의 서류를 교체하는 것이 아니라, 작업자가 다른 책상으로 이동한다.

이 차이는 여러 AI 에이전트 (Agent)를 구동할 때 큰 의미를 갖는다.

책상이 하나뿐이라면 여러 에이전트를 동시에 작업하게 하는 것은 어렵다. 하지만 책상이 여러 개 있다면 각각의 책상에 서로 다른 에이전트를 배치할 수 있다.

git worktree는 여러 에이전트에게 각각 별도의 책상을 제공하기 위한 메커니즘으로 사용할 수 있다.

작업 컨플릭트 (Conflict) 문제

하지만 git worktree가 만능은 아니다.

worktree는 작업 공간을 나누어 주지만, 작업 대상의 충돌까지는 막아주지 않는다. 머지 컨플릭트 (Merge Conflict) 문제가 그대로 나타나게 된다.

예를 들어, 에이전트 A가 어떤 worktree에서 src/main.rs를 변경하고, 에이전트 B도 다른 worktree에서 src/main.rs를 변경했다고 가정하자.

작업 디렉토리 (Working Directory)는 분리되어 있으므로, 그 변경은 서로 간섭 없이 완료된다.

하지만 최종적으로 변경 사항을 통합할 때, 동일한 파일에 대한 변경이 충돌할 가능성은 있다.

사실 이것은 최근에 발생한 문제가 아니다. 기존의 팀 개발에서도 종종 일어나던 문제이다. 여러 개발자가 동일한 파일을 변경하고 있다면, 머지 (Merge) 시에 컨플릭트 (Conflict)가 발생한다.

그래서 컨플릭트의 원인이 된 PR (Pull Request)의 작성자를 찾아 변경 의도를 확인하고, 때로는 함께 디프 (Diff)를 살펴보며 최종적으로 어떤 형태가 되어야 하는지 서로 확인하는 등의 과정을 거쳤을지도 모른다.

여담은 이쯤 해두자.

AI 에이전트 시대에는 이 문제가 로컬 환경에서도 일어나기 쉬워졌다는 뜻이다.

사람이 여러 AI 에이전트를 로컬에서 동시에 구동하면, 한 명의 개발자 환경에서 여러 명이 개발하는 것과 같은 경합이 발생하기 때문이다.

지금까지는 팀 개발상의 문제였던 것이, Multi Agent 개발에서는 로컬 개발 환경의 문제로도 나타나게 된다.

해결보다 예방

머지 컨플릭트 (Merge Conflict)가 발생한 후에 AI에게 해결을 요청할 수도 있다.

단순한 컨플릭트라면 그것으로 끝내도 좋고, 기계적으로 해결할 수 있는 컨플릭트라면 AI에게 맡겨도 좋다고 생각한다.

하지만 복잡한 컨플릭트에서는 불안함이 남는다.

코드상의 충돌로 보일지라도, 실제로는 설계 판단이나 사양 변경이 얽혀 있는 경우가 있다.

디프 (Diff)만으로는 언뜻 알아보기 어려운 곳에 '남겨두어야 할 것', '지워야 할 것', '남겨져서는 안 되는 것', '지워져서는 안 되는 것'이 숨어 있을 수도 있다는 점이 컨플릭트 (Conflict)의 무서운 점이다.

그러한 것들을 AI가 멋대로 '그럴싸하게' 해결해 버리는 것은 위험하다.

애초에 컨플릭트가 일어나지 않도록 사람이 사전에 완벽한 태스크 분할 (Task Partitioning)을 수행한다는 발상도 있을 것이다.

또한 이를 위해 변경 사항을 국소화하기 쉬운 설계 혹은 파일 구성으로 만들어 두는 발상도 있을 것이다.

하지만 이는 구현 및 운용까지의 비용이 높고, 게다가 확실하지도 않다.

태스크를 나누었다고 생각해도, 영역을 분할해 두었다고 생각해도, 막상 구현해 보면 같은 파일을 건드려야 하는 상황은 흔히 발생한다.

그렇지만 컨플릭트가 발생한 뒤에 열심히 해결하는 것이 아니라, 컨플릭트를 애초에 일으키지 않는다는 발상에는 가능성이 있다고 생각한다.

여기서 중요한 것은 '컨플릭트를 일으키지 않는 분할을 하는 것'이 아니라, '컨플릭트가 발생할 것 같은 순간을 검출할 수 있는 것'이 아닌가 싶다.

특히 동일 파일 편집에 기인하는 파일 레벨 컨플릭트 (File-level Conflict)는 비교적 기계적으로 검출할 수 있다.

모든 충돌을 기계적으로 막을 수는 없다. 서로 다른 파일을 변경하고 있더라도 의미론적으로는 충돌하고 있는 경우가 있다.

예를 들어, 어떤 에이전트가 API를 변경했는데, 다른 에이전트가 구형 API를 전제로 하는 코드를 작성하고 있는 경우다.

이러한 의미론적 충돌은 테스트나 리뷰, 설계 판단을 통해 다룰 필요가 있다.

반면, '동일한 파일을 여러 에이전트가 서로 다른 worktree에서 동시에 편집하려고 하는' 상태는 보다 기계적으로 검출할 수 있다.

이 파일 레벨 컨플릭트 (File-level Conflict)를 머지 (Merge) 시점이 아니라 편집 전에 막고 싶다.

그를 위해 만들고 있는 것이 git-kura이다.

git-kura란 무엇인가

git-kura

는 여러 worktree에서의 병렬 작업을 안전하게 진행하기 위한 Git 서브커맨드(subcommand)이다.

git-kura는 AI 오케스트레이터(AI orchestrator)가 아니다. 따라서 AI 에이전트(AI agent)를 기동하거나 태스크(task)를 자동으로 분배하는 것을 목적으로 하지 않는다.

git-kura가 다루는 것은 조금 더 낮은 레이어(layer)이다. 구체적으로는 다음이 git-kura가 주로 다루는 레이어이다.

• worktree를 결정론적(deterministic)으로 관리한다
• 어떤 worktree가 어느 경로(path)에 있는지 명령어로 가져올 수 있게 한다
• repository 공통의 스토어 파일(store file)을 사용하여, 어떤 worktree가 어떤 파일을 클레임(claim)하고 있는지 관리한다
• 이미 클레임(claim)된 파일을 다른 worktree가 클레임(claim)하려고 하면 거부한다
• pre-commit hook을 통해, seal 상태에 반하는 커밋(commit)을 차단한다

요컨대, AI 에이전트에게 "아마 이 worktree에서 작업하고 있을 것이다"라고 추측하게 만들지 않기 위한 도구이다.

인간의 주의나 프롬프트(prompt)의 선의에 의존하는 것이 아니라, 명령어의 성공 여부로 판단하게 한다.

seal claim의 메커니즘

git-kura에서는 파일을 편집하기 전에 seal claim을 한다.

예를 들어, worktree A가 file1.txt를 편집하고 싶을 경우, 다음과 같이 클레임(claim)한다.

git kura seal claim file1.txt

클레임(claim)이 성공하면, repository 공통의 스토어 파일(store file)에 "worktree A가 file1.txt를 클레임(claim)하고 있다"라는 정보가 기록된다.

이 상태에서 worktree B가 동일한 file1.txt를 클레임(claim)하려고 하면, git-kura는 거부한다.

git kura seal claim file1.txt
# file1.txt sealed by a
# exit non-zero

명령어가 실패하므로, AI 에이전트는 그대로 작업을 계속할 수 없다.

AI에게 "다른 worktree와 충돌하지 않도록 주의해줘"라고 부탁하는 것이 아니라, 충돌할 것 같은 파일을 건드리려는 시점에 명령어가 실패하는 장치를 만들어 두는 것이다.

머지(merge) 시점에 처음으로 컨플릭트(conflict)가 발견되는 것이 아니라, 편집 전에 멈추게 하는 것이 git-kura의 목표이다.

실제로 차단된 사례

git-kura의 개발 자체에서도 git-kura를 사용하고 있다.

실제로 어떤 이슈(Issue) 작업을 진행하려 했을 때, 다른 이슈용 worktree가 이미 필요한 파일을 클레임(claim)하고 있었기 때문에 AI 에이전트가 작업을 중단한 적이 있다. 다음은 그때의 로그이다.

구체적으로는 Issue 43의 작업을 진행하기 위해 필요한 파일이 이미 Issue 31의 작업에서 클레임(claim)되어 있었다.

AI 에이전트는 해당 파일을 마음대로 언클레임(unclaim)하거나, seal을 무시하고 편집하지 않고, "이 작업은 진행할 수 없습니다. 어떻게 할까요?"라며 인간에게 판단을 구했다.

여기서 중요한 것은 컨플릭트(conflict) 가능성이 검출되었고, 이를 받아 AI가 작업을 멈추고 인간에게 보고했다는 점에 있다.

멀티 에이전트(multi-agent) 개발에서는 모든 것을 AI에게 맡기는 것보다, AI가 진행해서는 안 되는 상황에서 확실히 멈추는 것이 더 중요해지는 경우가 있다.

pre-commit hook은 최후의 보루

하지만 git-kura에도 한계는 있다.

AI 에이전트가 git-kura를 무시하고 파일을 변경하는 것 자체를 막을 수는 없다. 파일 시스템상의 쓰기를 완전히 금지하고 있는 것은 아니기 때문이다.

git-kura에 의한 방어는 어디까지나 협조적인 것이며, 그 프로토콜(protocol)을 따르지 않는 에이전트의 존재를 배제하는 것까지는 할 수 없다.

그래서 git-kura는 최후의 보루로서 pre-commit hook을 제공한다.

git-kura의 seal 상태에 반하는 변경이 커밋(commit)되려 할 경우, pre-commit hook에서 커밋을 차단하는 메커니즘을 마련해 둔다.

이것은 변경 그 자체를 막는 메커니즘은 아니다. 하지만 적어도 "seal을 무시한 변경이 그대로 커밋되는 것"은 방지할 수 있다.

또한, git-kura

에는 다음과 같은 툴셋(toolset)을 repository local에 추가하기 위한 커맨드(command)도 준비되어 있다.

git kura tools install --all

이를 통해 Codex용 Skill, Claude용 Skill, pre-commit hook 설정 등을 한꺼번에 배치할 수 있다.

AI 에이전트(AI agent)에게 git-kura를 사용하도록 하는 지시와, Git 측에서 마지막에 차단하는 메커니즘을 repository 단위로 관리할 수 있도록 하는 것이 목적이다.

해결할 수 있는 것, 해결할 수 없는 것

git-kura의 스코프(scope)는 주로 file-level conflict의 사전 검지이다.

동일한 파일을 여러 worktree가 동시에 편집하려고 하는 경우, 이를 편집 전에 중단함으로써 conflict를 조기에 검지한다.

조기에 검지할 수 있다면, 작업 순서 조정 등을 통해 애초에 conflict가 발생하지 않도록 하는 선택이 가능해진다.

반면, git-kura는 의미론적 충돌(semantic conflict)까지는 방지할 수 없다.

예를 들어, 서로 다른 파일을 편집하고 있더라도 한쪽의 변경이 다른 쪽의 전제 조건을 깨뜨리는 경우가 있다. 이는 파일 단위의 claim만으로는 검출할 수 없다.

또한, claim의 입도(granularity)를 파일 단위로 설정했기 때문에, 동일 파일 내의 독립된 부분을 각각 편집할 수 있는 케이스에서도 한쪽은 중단된다.

이는 보수적인 설계이다. 병렬성(concurrency)을 최대화하기보다, AI 에이전트에 의한 예기치 않은 경합을 조기에 차단하는 것을 우선시하고 있다.

요약

여러 AI 에이전트를 병렬로 구동하면 개발 속도는 올라간다. 하지만 속도가 빨라질수록 작업 상태가 뒤섞였을 때의 피해도 커진다.

git worktree는 작업 공간을 분리하기 위한 유효한 메커니즘이다. branch를 전환하는 것이 아니라, worktree마다 별도의 작업 디렉토리(directory)를 준비할 수 있다.

이는 여러 에이전트를 동시에 구동하는 데 있어 궁합이 좋다.

다만, worktree는 작업 공간을 분리할 뿐, 작업 대상의 충돌까지는 방지하지 않는다.

git-kura는 그 틈새를 메우기 위한 작은 Git 하네스(harness)이다.

worktree를 결정론적(deterministic)으로 관리하고, 파일 단위의 seal claim을 통해 동일 파일 편집에 기인하는 충돌을 편집 전에 차단한다.

나아가 pre-commit hook을 통해 git-kura를 무시한 변경이 그대로 commit되는 것을 방지한다.

Multi-agent 개발에서는 에이전트를 늘리기 전에, 작업 상태를 섞지 않고 충돌시키지 않는 메커니즘이 필요하다고 생각한다.

git worktree는 책상을 늘린다.

git-kura는 어느 책상에서 어떤 서류를 만져도 되는지를 조정한다.

그런 도구로서 git-kura를 키워나가고 싶다.

참고 링크

Discussion