AI를 여러 개 사용해 개발하면 PR 충돌이 발생합니다. 그 정리 작업을 PR 전에 끝낼 도구를 만들었습니다

AI를 나란히 쓰면, PR이 "This branch has conflicts"로 멈춥니다

Claude Code나 Codex 같은 AI를 여러 개 배치하여 하나의 리포지토리에서 동시에 작업하게 하면, PR을 올릴 때 GitHub에서 "This branch has conflicts"라는 메시지를 받는 경우가 늘어납니다.

그럴 때마다 다음의 과정이 반복됩니다.

• main 브랜치를 가져오기 (pull)
• AI가 충돌한 파일을 통째로 읽고, 표시(<<<<<<<)를 수정하기 - push하고 CI를 다시 실행하기

시간과 토큰을 모두 소모합니다. 그런데 충돌 내용 자체를 살펴보니, 실제로 의견이 크게 다르지 않은 것들이 의외로 많다는 것을 깨달았습니다.

• 두 개의 AI가 같은 파일 끝에 각각 다른 함수를 추가한 경우
• 같은 JSON 리스트에 각각 다른 항목을 추가한 경우

둘 다 "양쪽을 남기면 해결되는" 경우입니다. 그럼에도 Git은 같은 위치에 대한 변경이므로 충돌로 멈춥니다.

계기: Anthropic의 Scion 기사

Anthropic이 2026-10-13에 공개한 "Redesigning source control at Anthropic"이라는 글에서는, AI가 주역인 개발을 위한 소스 관리 방식에 대한 아이디어를 소개했습니다. 예를 들어, 병합(merge)이나 충돌 처리 방식을 개발자가 아닌 도구 측에서 담당한다는 것입니다.

이것을 읽고, 자신의 환경에서도 같은 방법이 통할지 직접 작게 시도해 보았습니다.

시도해 보니 다음의 사실들을 알게 되었습니다.

• 몇 명의 AI가 하루에 10개 이상의 PR 규모로 작업하더라도,
  Git 자체가 막히는 일은 없었습니다. Git을 대체할 정도까지는 아니었습니다. - 효과적이었던 것은,
  Git 위에서도 그대로 사용할 수 있는 부분이었습니다. 예를 들어 "충돌을 미리 예측하기", "기계가 결정할 수 있는 것은 도구가 수정하기", "남은 것만 짧게 AI에게 전달하기" 등이 그것입니다.

그래서 그 부분만을 추출하여, PR을 올리기 전에 사용하는 도구로 만들었습니다. 이것이 바로 tiara입니다.

tiara가 하는 일

명령어는 세 가지입니다.

tiara check # GitHub에서 충돌 여부를 미리 예측합니다 (아무것도 변경하지 않음)
tiara sync # main을 가져와서, 기계로 수정 가능한 것은 수정하고. 나머지는 AI에게 전달합니다.
tiara verify --commit # AI가 수정한 후를 확인하고 커밋합니다

• check: git merge-tree
  을 사용합니다. GitHub가 PR 병합을 시도할 때와 같은 방식이므로, 예측과 실제가 어긋나지 않습니다. 로컬 파일은 아무것도 변경하지 않습니다. --prs를 붙이면, 다른 열려 있는 PR이 먼저 들어왔을 때 충돌하는지도 확인할 수 있습니다. -
  sync: 일반적인 git merge로 main 브랜치를 가져와서, 정해진 형태의 충돌만 수정합니다. 판단하기 모호한 것은 추측하지 않고 그대로 AI에게 전달합니다. -
  verify: 충돌 표시를 빼먹었거나, 깨진 JSON/YAML이 없는지 확인한 후에 커밋합니다. --cmd를 붙이면 테스트 명령어까지 실행합니다.

tiara 자체는 AI를 호출하지 않습니다. API 키도 필요 없고, 어디에도 아무것도 보내지 않습니다. 수정하는 것은 그 자리에서 작동하고 있는 Claude Code나 Codex입니다.

실제로 작동시키면 이렇게 됩니다

두 사람이 같은 app.py 파일 끝에 각각 다른 함수를 추가하고, 같은 JSON 리스트에 각각 다른 항목을 추가한 경우입니다.

$ tiara check
conflicts with origin/main in 2 file(s):
auto app.py (insert-both)
...

app.py에는 두 함수의 내용이 모두 남고, c.json 리스트에도 두 항목이 들어갑니다. 병합 커밋까지 완료되었으므로, 이제 push만 하면 됩니다.

같은 줄을 양쪽에서 각각 다르게 수정한 경우에는, tiara는 수정하지 않고 AI에게 넘겨서 멈춥니다 (발췌).

$ tiara sync
...
## `a2.py` (lines 2-8)
...

AI는 파일 전체가 아니라 이 줄 범위만 읽으면 되고, 양쪽 커밋 설명에서 "각각 무엇을 하려 했는지"도 알 수 있습니다. 양쪽 모두 같은 줄을 수정했을 때는, "조용히 어느 쪽을 선택하지 않고 사람에게 물어보라"는 주의사항도 붙입니다.

수정 규칙과 멈추는 경우

tiara가 직접 수정하는 것은 다음 경우뿐입니다. 이 모든 경우는 추측하지 않고 멈춥니다.

그 외의 경우(같은 줄을 따로따로 수정한 경우, 한쪽이 삭제한 경우, 바이너리 등)는 모두 AI에게 전달합니다.

과거 PR에서 시도해 본 결과

두 개의 앱 리포지토리에서 main과 충돌했던 사람이 수정한 과거 PR 47건(충돌 파일 149개)을 기본 설정으로 재현했습니다.

• tiara가 직접 수정한 것은 14개의 파일 - 이 중 8개는 사람이 수정한 결과와 동일합니다.
• 3개는 추가된 덩어리의 순서만 다릅니다.
• 3개는 사람이 머지할 때 새로운 줄도 작성되어 비교할 수 없습니다.

잘못 섞인 파일은 0개 - 나머지 135개의 파일은 이력을 첨부하여 AI에게 전달했습니다.

솔직히 말해서, 모든 것을 자동으로 수정하는 도구는 아닙니다. 효과는 AI 간의 충돌 방식에 따라 달라집니다. 함수・테스트・리스트 항목을 나란히 추가하는 사용 사례처럼 잘 작동합니다.

Claude Code・Codex와 함께 사용하기

리포지토리에 AI용 지침을 포함하고 있습니다.

• Claude Code:
  integrations/claude-code/skills/tiara
  를 .claude/skills/tiara/에 배치 - Codex:
  integrations/codex/AGENTS.md
  의 내용을 자신의 AGENTS.md에 추가합니다.

이렇게 하면 AI가 PR을 내기 전에 tiara check를 실행하고, 남은 충돌을 이력(history)에 따라 수정하게 됩니다. tiara가 오류가 발생하면 일반적인 git merge로 전환하도록 작성되어 있습니다.

설치 방법

Python 3.10 이상과 git 2.38 이상에서 작동합니다.

pipx install git+https://github.com/aruku417/tiara

완성품이 아닌 '기반'으로서

tiara는 초기 버전(0.1)입니다. 리포지토리 구성, 브랜치 이름, 생성 파일, 테스트 방법은 팀마다 다르므로, 그대로 사용하기보다는 자신의 환경에 맞게 수정하는 전제하에 만들어졌습니다.

가장 쉬운 것은 AI에게 의존하는 것입니다.

tiara의 README를 읽고 이 리포지토리에 맞춰 설정하세요.

코드도 작기 때문에(수정 규칙은 src/tiara/resolve.py에 모여 있습니다), 자신의 팀에서 자주 발생하는 충돌 규칙을 추가하는 것도 자연스러운 사용법이라고 생각합니다.

맺음말

AI를 나란히 개발하면서 PR 충돌로 시간을 보내는 분들에게 시도해 보시길 바랍니다.