AI 에이전트 여러 개 동시에 돌리기, 충돌 없이 일 나누는 법

AI 코딩 에이전트 하나는 잘 쓰는데, 두 개를 동시에 돌리자마자 파일이 꼬이고 커밋이 뒤섞인 경험이 있나요? 이 글은 에이전트 여러 개에게 한 저장소의 일을 나눠 맡길 때 무엇을 정해 두어야 하는지, 순서대로 정리해요.

혹시 이런 고민 있으신가요?

• 에이전트 두 개를 동시에 돌렸더니 같은 파일을 서로 고쳐서 한쪽 작업이 사라졌어요.
• 에이전트가 "다 했어요" 라고 하는데, 정말 끝났는지 어떻게 믿어야 할지 모르겠어요.
• 에이전트마다 알아서 푸시해서 어떤 변경이 어디에 올라갔는지 추적이 안 돼요.

이 글을 읽으면

• 일을 에이전트에게 쪼개 주는 기준과, 쪼개지 말아야 할 때를 구분할 수 있어요.
• 같은 파일을 두 에이전트가 만지지 않도록 소유자를 정하고 실행 순서를 세울 수 있어요.
• 커밋, 푸시, 완료 판정의 주인을 정해서 "누가 뭘 했는지" 가 남는 구조를 만들 수 있어요.

1단계. 먼저 쪼갤지 말지 정하기

에이전트를 여러 개 쓰는 것이 항상 빠른 것은 아니에요. 일을 나누면 나누는 일 자체, 결과를 모으는 일, 서로 겹치지 않게 조율하는 일이 새로 생겨요. 일이 작으면 이 비용이 일 자체보다 커요.

저희는 기준을 단순하게 두었어요. 한 번에 처리할 묶음이 파일 세 개 미만을 건드리거나 한 영역 안에서 끝나면 에이전트 하나가 혼자 처음부터 끝까지 해요. 여러 영역에 걸치고 서로 기다리지 않아도 되는 부분이 있을 때만 리더 하나와 작업자 여럿으로 나눠요. 기본값은 혼자 하는 쪽이에요.

이 판단은 일을 맡기는 쪽이 한 번만 해요. 리더나 작업자가 "이건 혼자 해도 되겠는데" 하고 다시 판단하게 두면, 같은 일을 두 번 다르게 판단하는 일이 생겨요.

2단계. 역할을 직무로 나누고 리더는 손대지 않게 하기

나누기로 했다면 에이전트를 직무로 나눠요. 사람 팀에서 프런트엔드, 서버, 인공지능, 인프라 담당을 나누는 것과 같아요. 저희는 네 종류의 작업자를 두었어요.

여기에서 두 가지 규칙이 중요해요.

첫째, 한 항목이 두 영역에 걸쳐 있으면 항목을 둘로 쪼개요. 어느 한쪽에도 맞지 않는 항목은 범위를 잘못 잡은 것이니 주인을 추측하지 말고 맡기는 쪽에 돌려보내요. 주인이 없는 일은 아무도 검증하지 않아요.

둘째, 리더는 구현하지 않아요. 리더의 일은 항목을 나눠 주고, 순서를 세우고, 마지막에 검사하는 것이에요. 리더가 직접 코드를 고치기 시작하면 작업자와 같은 파일을 만지게 되고, 심판이 선수로 뛰는 꼴이 돼서 마지막 검사의 의미가 없어져요. 리더가 "이 정도는 내가 하는 게 빠르겠는데" 하는 순간은 일이 작아서 1단계에서 혼자 하는 쪽으로 갔어야 한다는 신호예요.

작업자에게 규칙을 알려 줄 때도 요령이 있어요. 규칙 본문을 붙여 넣지 말고 규칙 문서의 위치만 알려 줘요. 본문을 붙이면 문서를 고쳐도 이미 전달된 복사본은 옛날 그대로여서, 에이전트마다 알고 있는 규칙이 달라져요.

3단계. 영역이 아니라 파일에 소유자를 붙이기

충돌의 대부분은 여기서 막혀요. "화면은 화면 담당" 처럼 영역으로 나누면 부족해요. 화면 담당 둘이 같은 공용 설정 파일을 고치면 충돌하니까요. 저희 규칙은 이래요. 두 작업자가 같은 파일을 쥐지 않는다. 영역이 아니라 파일을 배정한다.

작업자에게 일을 맡길 때 넘기는 메시지에는 이 네 가지를 꼭 담아요.

작업 파일: 작업 목록 문서의 위치맡은 항목: 항목 하나건드려도 되는 파일: 목록으로 나열완료 기준: 작업 목록 문서에 적힌 검증 방법 그대로, 숫자나 명령으로 측정 가능하게

그리고 "목록에 없는 파일은 건드리지 않는다" 를 작업자의 기본 규칙으로 둬요. 목록 밖의 파일을 고쳐야만 일이 끝난다면 작업자가 고치는 대신 리더에게 알리게 해요. 그러면 리더가 파일 소유를 다시 배정할 수 있어요.

공유되는 자원에는 한 주인만 두는 것도 좋아요. 저희는 데이터베이스 구조는 서버 담당이, 공용 화면 부품은 화면 담당이, 작업 공간 전체 설정은 인프라 담당이 유일한 소유자예요. 다른 작업자에게 그 파일의 변경이 필요하면 직접 고치지 않고 소유자에게 요청이 가게 해요.

4단계. 어떤 일은 병렬로 하지 말고 순서를 박아 두기

병렬로 돌릴 수 있는 일과 없는 일을 미리 구분해야 해요. 파일이 겹치지 않아도 앞 단계의 결과가 있어야 시작할 수 있는 일이 있어요. 이런 일은 작업 목록에 순서를 어떻게 적어 놓았든 항상 순차로 돌려요.

저희가 "무조건 앞뒤" 로 박아 둔 것은 네 가지예요.

1. 데이터베이스 구조를 먼저 바꾸고, 새 칼럼을 읽는 코드는 그 뒤에 해요.
2. 서버의 호출 규격을 먼저 확정하고, 그 규격에서 호출 코드를 다시 만든 뒤에, 그 코드를 쓰는 화면을 만들어요.
3. 로그인 클라이언트 설정을 먼저 만들고, 로그인이 필요한 화면은 그 뒤에 만들어요.
4. 인공지능 처리 쪽 호출 지점을 먼저 만들고, 서버가 그곳을 부르는 코드는 그 뒤에 만들어요.

앞 단계의 결과가 필요한 일은 순서를 지키고, 나머지만 병렬로 돌려요

그림처럼 순서가 있는 줄 하나에 인프라 설정처럼 서로 의존하지 않는 일이 옆에서 병렬로 도는 구조가 가장 흔해요. 기준은 "이 일이 끝나기 전에 저 일을 시작하면 저 일이 틀린 가정 위에서 만들어지는가" 예요. 그렇다면 순서를 박고, 아니라면 병렬로 풀어요.

자기 프로젝트에 적용할 때는 이렇게 하세요. 지난 몇 번의 작업에서 "앞 일이 덜 끝났는데 뒷일을 시작해서 다시 한" 경우를 떠올려 보세요. 그 쌍이 곧 박아 둘 순서예요.

5단계. 커밋은 작업자가, 푸시는 한 곳에서만 하기

여럿이 같은 브랜치에 푸시하면 서로의 작업을 덮거나 되돌리기 어려운 상태가 생겨요. 그래서 저희는 역할을 이렇게 고정했어요.

• 작업자는 커밋하고 푸시하지 않아요.
• 푸시는 작업을 시킨 세션이 한 번에 해요. 자기가 맡긴 일이 모두 끝난 뒤에요.
• 커밋은 하위 작업 하나에 하나예요. 여러 하위 작업을 한 커밋에 묶지 않아요. 중간 커밋이 깨졌을 때 범인을 찾을 지점이 사라지기 때문이에요.
• 푸시 전에 변경한 영역에 대해 타입 검사, 린트, 서식 검사를 통과해야 해요.
• 기본 브랜치에는 직접 커밋하지 않고, 합치기는 풀 리퀘스트를 거쳐요.

여기서 한 번 겪은 실수가 있어요. 같은 작업 디렉터리에서 에이전트 둘을 동시에 돌렸어요. 둘이 건드린 파일은 겹치지 않았기 때문에 안전하다고 판단했어요. 그런데 한쪽이 먼저 끝나 자기 결과 문서를 올리려고 파일 경로를 지정해 추가한 다음 바로 커밋했는데, 그 순간 다른 쪽 에이전트가 이미 자기 변경을 스테이징해 둔 상태였어요.

git add 내파일들git commit -m "내 커밋"   # 경로를 주지 않았으니 스테이징 영역 전체가 들어가요

git add 경로 는 그 경로만 스테이징 영역에 더할 뿐, 이미 올라 있는 다른 경로를 지우지 않아요. 그리고 경로 없이 git commit 을 하면 그 순간 스테이징 영역 전체가 커밋돼요. 결과적으로 내 커밋에 상대 에이전트의 코드 변경이 함께 실렸고, 상대가 곧이어 한 커밋에는 정리 작업의 이동 기록만 남았어요. 잃은 코드는 없었어요. 다만 커밋 메시지와 실제 내용이 어긋났어요.

원인은 "파일이 겹치지 않는다" 와 "스테이징 영역이 겹치지 않는다" 가 다른 말이라는 점이에요. 스테이징 영역은 작업 디렉터리 하나에 하나뿐이에요. 저희는 히스토리를 다시 쓰지 않기로 했어요. 고치는 비용이 어긋난 메시지의 혼란보다 컸기 때문이에요. 대신 규칙을 이렇게 적어 두었어요.

6단계. 완료는 말이 아니라 실행 결과로 판정하기

에이전트는 "끝났어요" 라고 쉽게 말해요. 그래서 완료의 정의를 사람이 확인할 수 있는 형태로 옮겨 둬야 해요.

• 항목을 체크하는 시점은 그 항목의 검증을 실제로 돌린 뒤예요. 돌리지 않은 검증은 체크하지 않아요.
• 하위 작업이 실패하면 작업 목록에 번호를 붙인 수정 하위 작업을 추가하고, 고치고, 체크해요. 그래서 문서에 틀린 과정도 남아요.
• 상위 항목은 하위 항목이 전부 체크되었을 때만 체크해요.
• 리더는 마지막 작업자가 끝난 뒤 푸시 단위의 검사를 직접 돌려요. 작업자 각자의 초록불을 모아도 푸시 전체의 초록불은 아니에요. 따로는 잘 돌던 변경이 합쳐지면 깨지는 일이 흔해서예요.

작업이 끝나면 결과 보고서를 한 장 써요. 하위 작업과 커밋, 바뀐 파일, 검증 결과, 발견한 문제를 적어요. 보고서가 있으면 다음 날 아침 사람이 "어디까지 됐는지" 를 코드부터 열어 보지 않고도 알 수 있어요.

사람이 없는 시간에 돌릴 때는 끝까지 가게 하는 장치와 멈추는 조건도 같이 정해야 해요. 열린 항목이 남아 있는 동안은 종료를 막는 훅을 두고, 이런 경우에만 멈추게 했어요.

• 앞선 묶음이 끝나지 않아서 선행 조건이 막혔을 때
• 새 브랜치를 어떻게 이름 붙일지 근거가 없을 때
• 에이전트가 같은 자리에서 두 번 실패했을 때

판단이 필요한 항목에서는 멈추지 않게 했어요. 결정이 필요한 항목은 방어할 수 있는 쪽을 고르고, 무엇을 왜 골랐고 어떻게 되돌리는지를 짧은 기록으로 남겨 두고 계속 가요. 단, 돈을 쓰거나 데이터를 지우는 결정은 사람에게 돌려요. 멈춰서 기다리는 에이전트는 새벽에 아무 일도 하지 않아서, 기록을 남기고 가는 편이 훨씬 나아요.

7단계. 한 번에 한 기능만 돌리기

마지막으로, 맡기는 범위를 좁혀야 해요. 작업 목록이 여러 기능에 걸쳐 쌓여 있을 때 "전부 돌려" 하면 관련 없는 두 기능의 커밋이 한 브랜치에, 결국 한 풀 리퀘스트에 섞여요. 검토하는 사람이 뭘 봐야 하는지 알 수 없고, 한쪽을 되돌리면 다른 쪽도 같이 되돌려지기 쉬워요.

그래서 저희는 인자 없이 실행해도 지금 체크아웃된 브랜치가 속한 기능의 작업만 돌리게 했어요. 다른 기능의 작업 파일이 남아 있어도 그 기능의 브랜치에서 따로 돌려요. 이 결정에는 "큰 작업은 이슈 하나에서 브랜치를 시작한다" 는 규칙이 바탕에 있어요.

자주 묻는 질문

Q1. 작업자는 몇 명까지 한 번에 돌리는 게 좋나요?

숫자보다 파일이 겹치는지를 보세요. 파일이 겹치지 않고 서로 기다릴 필요가 없는 일이 둘이면 둘, 다섯이면 다섯이에요. 다만 마지막 검사와 결과 모으기는 한 곳에서 하므로, 리더가 한 번에 읽고 판단할 수 있는 양을 넘기면 병렬의 이득이 사라져요.

Q2. 작업자가 막혀서 범위 밖 파일을 고쳐야 한다고 하면요?

고치게 두지 말고 리더에게 돌려보내요. 리더가 그 파일의 소유자를 바꾸거나, 항목을 둘로 나눠요. 처음 몇 번은 이런 요청이 자주 올 수 있어요. 그건 작업을 나눈 방식이 현실과 어긋났다는 신호이니 작업 목록을 쓰는 방식을 고쳐요.

Q3. 에이전트가 같은 자리에서 계속 실패하면요?

두 번 실패하면 멈추게 해요. 세 번째 시도는 보통 다른 가설이 아니라 같은 시도의 반복이에요. 멈춘 자리와 에러를 보고서에 남겨 두면 사람이 이어받기 쉬워요.

정리

• 일이 작으면 에이전트 하나가 혼자 하고, 여러 영역에 걸칠 때만 리더와 작업자로 나눠요.
• 리더는 구현하지 않고, 파일 단위로 소유자를 정해서 두 작업자가 같은 파일을 쥐지 않게 해요.
• 앞 단계의 결과가 필요한 일은 순서를 박아 두고, 나머지만 병렬로 돌려요.
• 작업자는 커밋만 하고 푸시는 한 곳에서 해요. 같은 디렉터리에서 동시에 돌릴 때는 스테이징 영역이 하나뿐이라는 점을 기억해요.
• 완료는 말이 아니라 검증을 실제로 돌린 결과로 판정하고, 맡기는 범위는 한 번에 한 기능으로 좁혀요.

에이전트를 늘리는 일은 사람 팀을 키우는 일과 닮았어요. 사람이 늘수록 코드보다 약속이 중요해지는 것처럼, 에이전트도 약속부터 정해 주세요.