AI 에이전트 여러 개를 같이 쓰다 꼬였다 — 그래서 만든 협업 규칙 4가지 · 숭블리 LAB

AI 에이전트 하나를 쓸 때는 문제가 없었다. 둘, 셋이 되면서 꼬이기 시작했다. 대화형 웹 에이전트, 터미널 에이전트, 에디터 안 에이전트, 그리고 밤에 혼자 도는 자동 파이프라인까지 같은 코드를 번갈아 만진다. 사람 팀이라면 회의하고 PR 리뷰하며 맞추는 걸 에이전트들은 하지 않는다. “A가 고친 걸 B가 몰라서 꼬이는” 사고가 한 달 사이 여러 번 났고, 그때마다 규칙을 한 줄씩 추가했다. 지금은 네 개다. 규칙이 생긴 계기와 그 뒤 효과를 적어 둔다.

규칙 1. 작업 끝 = 커밋 (세션 끝이 아니라)

첫 사고는 사고라기보다 상태였다. 매일 아침 자동 발행되는 운영일지에는 두 레포의 미커밋 변경 수가 찍힌다. 7월 8일부터 11일까지 그 숫자가 668건, 681건, 683건이었다. 에이전트 세션은 며칠씩 켜 두는 게 보통이라 “세션 끝날 때 커밋하지"가 쌓인 결과였다. 한 에이전트가 며칠치를 들고 있으면 다른 에이전트는 그 변경을 모른 채 같은 파일을 만진다.

그래서 커밋 시점을 바꿨다. 세션이 끝날 때가 아니라 하나의 작업이 끝나는 순간이다. 한 세션에서 기능 셋을 만들면 커밋도 세 번. 승인 대기 중인 작업도 브랜치에라도 올려 둔다.

이 규칙에 붙은 두 번째 계기가 8월 2일 메인 흰 화면 사고다. 자동 발행 커밋이 0바이트짜리 index.html을 올려 버렸다. 전체 git add가 다른 에이전트의 미완성 산출물까지 쓸어 담은 것이다. 그 뒤로 “배포 커밋은 자기 작업 파일만 선별 add"가 규칙에 박혔다. 커밋 전 git status와 파일 크기를 본다는 한 줄도 그날 생겼다.

효과는 운영일지 숫자로 보인다. 8월 12일 이후 미커밋 수는 3건, 6건, 7건, 5건처럼 한 자릿수가 이어진다. 8월 11일에 1,472건이라는 이상치가 한 번 찍히긴 했다. 규칙이 지켜지는지는 다음 날 아침 공개 일지에 드러난다. 감시는 사람이 아니라 숫자가 한다.

규칙 2. WORKLOG — 만지기 전에 읽고, 만진 뒤에 남긴다

커밋 메시지만으로는 “왜"가 안 남는다. 에이전트 B가 A의 의도를 모르면 멀쩡한 코드를 버그로 오해하고 되돌린다. 그래서 각 프로젝트 루트에 WORKLOG.md를 두고 인수인계 장부로 쓴다. 작업 시작 전에 최근 열 줄과 최근 커밋 다섯 개를 읽고, 끝나면 한 줄 남긴다 — 날짜, 어느 에이전트가, 무엇을, 왜, 미완성은 무엇인지.

말로만 하면 안 지켜진다는 걸 알아서 pre-commit 훅을 걸었다. 코드 변경 커밋에 WORKLOG 갱신이 없으면 커밋이 거부된다. 자동화 봇의 데이터 전용 커밋만 예외다. 지금 WORKLOG에는 “07-27 제작기 2~8편 일괄 작성·예약발행 구축”, “08-02 메인 복구” 같은 줄이 시간순으로 쌓여 있고, 새 에이전트가 들어오면 이 줄들부터 읽는다.

규칙 3. 수정하면 재시작까지 — 재시작이 곧 배포

세 번째는 유령 장애다. 에이전트가 코드를 고쳤고 테스트도 통과했는데 서비스는 옛날처럼 동작한다. 고친 코드는 디스크에 있고 옛 프로세스가 계속 돌고 있기 때문이다. 에이전트는 “고쳤습니다"라고 보고하고 끝낸다. 그 뒤 누군가 “코드는 맞는데 왜 이상하지"를 한참 들여다본다.

그래서 상시 서비스의 코드를 고쳤다면 해당 서비스 재시작까지가 작업 완료다. 재시작 방법은 관리자 화면 버튼이나 로컬에서 프로세스를 내리면 매니저가 되살리는 방식으로 통일했다. 여기에 붙은 사례가 두뇌 오락실이다. 서비스 레지스트리에 등록이 안 된 채로 502가 방치되다가 8월 3일 재등록으로 살아났다. “등록해야 태어난 것"이라는 출생신고 규칙이 이때 문장으로 굳었다.

규칙 4. 같은 폴더, 동시 작업 금지

네 번째는 가장 단순하지만 제일 자주 깨진다. 두 에이전트가 같은 프로젝트 폴더를 동시에 수정하지 않는다. 다른 에이전트의 미커밋 변경을 발견하면 덮어쓰거나 커밋하지 말고 그대로 두고 운영자에게 보고한다.

계기는 8월 9일 맥북 서버에서 났다. 코인 성과 업로더 한 줄을 crontab에 넣었는데, 다른 세션이 주식봇 배치를 이관하면서 crontab을 통째로 다시 설치했고 코인 줄이 지워졌다. 두 에이전트 모두 자기 작업은 맞게 했다. 같은 파일을 공유한 게 문제였다. 결국 코인 업로더는 crontab에서 독립 타이머로 빼내 충돌 원천을 없애는 쪽으로 갔다. 규칙은 “동시에 하지 말 것"이지만 실제 처방은 “공유 자원을 나눌 것"이었다.

규칙 밖에서 온 사고 — 8월 8일 재설치

네 규칙이 자리 잡고도 빠진 게 하나 있었다. 8월 8일 에이전트 도구를 재설치하면서 세션과 메모리가 전부 사라졌다. 프로젝트별로 “지금 어디까지 됐고 포트는 몇 번이고 다음 할 일은 뭔지"가 에이전트 머릿속에만 있었던 것이다.

그래서 규칙 하나를 더했다. 지식은 레포에 산다. 프로젝트마다 CLAUDE.md라는 착륙 문서를 두고 — 무엇인가, 현재 상태, 실행·배포·재시작 방법, 다음 할 일, 하지 말 것 — 새 에이전트는 이 파일부터 읽는다. 그날 17개 프로젝트에 한꺼번에 만들었고, 새 프로젝트 폴더에 이 문서가 없으면 커밋이 거부되도록 훅을 추가했다. 에이전트 메모리도 매일 레포로 백업한다. 역할은 나눴다. WORKLOG는 시간순 이력(무엇을 했나), CLAUDE.md는 현재 상태(지금 어떤가). 이 사이트의 착륙 문서에도 “전체 git add 금지, 자동 커밋 봇 3종 상주, public 빌드 없이 push 금지” 같은 줄이 들어가 있다. 전부 한 번씩 데인 자리다.

돌아보면

네 규칙 다 새로운 발명이 아니다. 사람 팀이 수십 년 전부터 하던 것 — 자주 커밋하라, 기록을 남겨라, 배포까지가 일이다, 같은 파일을 동시에 만지지 마라 — 을 에이전트에게 다시 가르친 것뿐이다. 차이는 에이전트가 이걸 알아서 하지 않는다는 점이고, 그래서 사람의 말이 아니라 훅과 숫자로 강제해야 한다는 점이다. 규칙을 지키는지는 다음 날 아침 운영일지가 알려 준다.

이 글은 제 여행 기록과 작업 로그를 바탕으로 초안을 AI와 함께 정리하고, 직접 편집했습니다.