AI 에이전트 팀으로 개발할 때 잘못되는 10가지 (파트 1)

최근 저는 Claude Code 에이전트 7개와 함께 혼자 제품을 구축하는 방법에 대해 글을 썼습니다. 그 글에 대한 피드백 중 한 가지가 마음에 남았는데, 바로 에이전트들이 잘못 작동했던 부분이 다른 개발자들에게는 가장 유용하다는 것이었습니다.

그래서 이 포스트와 파트 2는 오직 그 부분에 대해서만 다룹니다. 저희의 특정 버그가 아니라, 그 뒤에 숨겨진 패턴들입니다. 만약 하나의 프로젝트에서 에이전트를 하나 이상 실행한다면, 어떤 모델이나 도구를 사용하든 이 중 대부분을 경험하게 될 것입니다. 각 항목별로: 어떤 모습인지, 왜 발생하는지, 그리고 무엇이 도움이 되는지를 설명합니다.

Overview: ten failure patterns of agent teams, each with its symptom and the fix

1. 에이전트는 증상을 고치지, 원인을 고치지 못한다

어떤 모습인가: 같은 종류의 실패가 수정할 때마다 반복해서 나타납니다. 각 수정은 그 자체로는 합리적입니다. 여기서는 재시도(retry)를 하고, 저기에서는 타임아웃을 늘리는 식이죠.

왜 발생하는가: 에이전트는 눈앞에 보이는 오류만 보고, 주변의 시스템 전체는 보지 못합니다. 에이전트가 이해하는 임무는 이 실패를 사라지게 만드는 것입니다. 따라서 자신이 작동하는 환경 자체가 문제인지 묻는 경우는 거의 없습니다.

도움이 되는 것: 같은 종류의 실패에 대해 두 번째 수정을 마쳤다면, 멈추고 한 단계 아래(one level down)를 살펴보세요. 머신(Machine), 메모리(Memory), 네트워크(Network), 데이터(Data), 버전(Versions)을 점검해야 합니다. 에이전트에게 명시적으로

확장하기 전에 공유되는 항목들을 목록화하세요: 테스트 계정, 폴더, 포트, 데이터베이스, 호출 제한(rate limits). 각 병렬 작업에 전용 자원을 할당하거나, 공유하는 방식을 명시적으로 처리해야 합니다. 그리고 새로운 실패 사례를 선물처럼 여기세요. 이들은 이전에는 버그였지만 단지 보이지 않았을 뿐입니다.

저희의 경우, 테스트를 병렬로 실행하면서 두 개의 에이전트가 계속해서 하나의 계정을 공유하고 있었다는 것을 알게 되었습니다.

3. "보냄(Sent)"이 "읽음(Read)"은 아니다

어떻게 보이는가: 한 에이전트가 다른 에이전트에게 작업을 넘겨주고 기다립니다. 하지만 다른 에이전트는 그 메시지를 본 적이 없거나, 봤더라도 다음 작업으로 넘어갑니다. 작업이 지연되지만 아무도 몇 시간 동안 이를 눈치채지 못합니다.

왜 발생하는가: 에이전트 간의 메시지가 다음과 같은 지루한 방식으로 실패합니다: 전송 오류(send error), 바쁘거나 재시작된 수신자, 중복으로 인해 손실되는 메시지 등입니다. 발신자는 "내가 보냈다"는 것을 "처리되었다"고 간주합니다.

어떻게 해결하는가: 중요한 모든 인계 작업에는 짧은 확인 응답(acknowledgement)이 필요합니다. 결정 사항은 단순히 메시지에만 넣을 것이 아니라 공유 문서에 기록해야 합니다. 그리고 아무런 피드백을 받지 못한 발신자는 추측하기보다 후속 조치를 취해야 합니다.

A handover with and without acknowledgement: without it, the sender waits on a message nobody read; with it, the receiver confirms and the decision lands in a document

4. 증거 없는 "완료(Done)"

어떻게 보이는가: 한 에이전트가 작업을 완료했다고 보고합니다. 하지만 실제로는 그렇지 않거나, 부분적으로만 완료된 경우입니다.

왜 발생하는가: 성공을 보고하는 것이 작업의 가장 흔한 끝맺음이기 때문에, 에이전트가 작성할 가능성이 가장 높은 내용입니다. 결과를 확인하는 것은 추가 단계이며, 이를 강제하는 요소가 없을 때 건너뛰기 쉽습니다.

어떻게 해결하는가: 완료를 증거(evidence)로 정의해야 합니다. 테스트 실행 결과, 스크린샷, 열리는 링크, 측정된 숫자 등이 될 수 있습니다. 더 나은 방법은 다른 에이전트에게 결과를 확인하도록 맡기는 것입니다. 이 에이전트는 구축(build)을 담당하는 것이 아니라 측정(measure)을 담당하는 역할을 해야 합니다.

저희의 경우, 한 에이전트가 실제로 작성하기도 전에 메모가 작성되었다고 보고한 적이 있습니다.

5. 승인 과정이 전달되면서 모호해진다

한 에이전트가 다른 에이전트에게 "인간이 동의했다"고 말합니다. 두 번째 에이전트는 이에 따라 행동하다가 지나치게 나아가거나, 신뢰하지 못하고 영원히 기다립니다.

에이전트는 당신이 다른 사람에게 실제로 무슨 말을 했는지 알 수 없습니다. 전달된 "예스(yes)"는 과정에서 그 범위가 사라집니다. 무엇에 동의했는지, 정확히 어느 기간 동안 동의했는지 말입니다.

사전에 누가 무엇을 승인할 수 있는지 결정하고 문서로 남기세요. 구체적으로 무엇이 승인되었는지 명시적이고 표시된 방식으로 승인을 하세요. 누가 요청하든 인간만이 승인할 수 있는 항목의 짧은 목록(예: 공개되는 모든 것, 돈, 프로덕션 데이터 삭제, 비밀 정보)을 유지하세요.

A relayed yes versus a marked approval: the relayed one loses its scope, the marked one says who approved what

6. 공유 작업 공간 하나가 미완성 작업을 누설함

한 에이전트의 테스트가 다른 에이전트의 미완성 변경 사항 때문에 실패합니다. 커밋(commit)에 다른 사람에게 속한 파일들이 포함됩니다. 방 안에 있는 누구도 원인 제공을 하지 않은 이유로 빌드(build)가 깨집니다.

하나의 작업 복사본(working copy)에 있는 여러 에이전트들이 서로의 진행 중인 작업을 모두, 항상 볼 수 있기 때문입니다. 도구들은 워크스페이스당 한 명의 사람을 가정합니다.

진행 중인 작업을 격리하세요. 더 큰 작업의 경우 별도의 브랜치(branch)나 작업 복사본을 사용하고, 커밋은 파일 이름을 명시적으로 지정하며, 공유 폴더를 누가 건드릴 수 있는지에 대한 명확한 규칙을 만드세요. 공유 사본을 공동 주방처럼 취급하세요: 시작한 것은 정리해야 합니다.

7. 긴 세션에서 컨텍스트(Context)가 사라짐

장시간 실행되는 에이전트가 어제의 결정을 잊거나, 질문을 반복하거나, 구식 계획으로 자신 있게 계속 진행합니다.

컨텍스트는 제한적입니다. 긴 세션은 요약되거나 잘려나가며, 이 과정에서 세부 사항(예외 조항, 예외 사항, 규칙의 근거)이 누락됩니다.

도움이 되는 것 (What helps): 생존해야 하는 모든 것은 대화 내용에만 넣는 것이 아니라 파일에 넣어두어야 합니다. 살아있는 명세서(spec), 상태 문서(status document), 또는 긴 휴식 전에 작성하는 짧은 인수인계 메모가 그것입니다. 에이전트가 돌아오면, 자신의 기억을 읽기 전에 문서를 먼저 읽습니다.

8. 소유권 중복 (Overlapping ownership)

어떻게 보이는가 (What it looks like): 두 에이전트가 같은 파일을 수정하거나, 동일한 텍스트의 두 가지 버전을 작성하거나, 서로의 작업을 되돌립니다(undo).

왜 발생하는가 (Why it happens): 에이전트는 도움이 되고 싶어 합니다. 만약 고칠 수 있는 것을 본다면, 그것이 다른 사람의 영역일지라도 수정합니다.

도움이 되는 것 (What helps): 영역별로 한 명의 소유자(owner)를 지정하고, 모든 에이전트가 읽을 수 있는 곳에 이를 문서화해야 합니다. 다른 에이전트는 제안할 수는 있지만, 소유자가 결정하고 수정합니다. 에이전트가 자신의 영역 밖의 것이 필요하면, 스스로 하려고 하기보다 소유자에게 요청합니다.

9. 그럴듯한 발명 (Plausible inventions)

어떻게 보이는가 (What it looks like): 존재하지 않는 메뉴 항목, 아무도 말하지 않은 인용구, 적절하게 들리는 숫자, 하루 차이가 나는 날짜 등입니다. 종종 완벽하게 읽히는 텍스트에서 나타납니다.

왜 발생하는가 (Why it happens): 에이전트는 패턴을 완성합니다. 사실(fact)이 누락되었을 때, 가장 그럴듯한 버전이 빈틈을 채우고, 이 '그럴듯함'은 알아차리기 어렵습니다.

도움이 되는 것 (What helps): 독자가 조치를 취할 수 있는 모든 것에 대해 출처(source)를 요청해야 합니다: 단계, 이름, 숫자, 인용구. 에이전트가 추측할 이유가 없도록 '검증되지 않음(not verified)'을 허용 가능한 답변으로 만듭니다. 사실은 스타일과 분리하여 검토합니다.

저희의 경우, 설정 가이드의 모든 단계를 공식 문서와 대조한 결과, 저희가 추천하고 싶었던 기능이 여전히 제한적인 베타 버전임을 확인했습니다.

10. 테스트 환경과 운영 환경의 혼재 (Test and production drift into each other)

어떻게 보이는가 (What it looks like): 테스트가 실제 데이터에 쓰는 경우, 스테이징(staging)용 스크립트가 운영(production) 환경에서 실행되는 경우, 또는 테스트 환경이 점차 라이브(live)한 무언가에 의존하게 되는 경우입니다.

왜 발생하는가 (Why it happens): 에이전트는 주어진 모든 접근 권한을 사용합니다. 만약 운영 연결(production connection)이 손닿는 거리에 있다면, 조만간 무언가가 그것을 사용하게 됩니다.

좋은 방법: 환경을 엄격하게 분리하고, 데이터, 저장소, 자격 증명을 각각 분리합니다. 각 에이전트가 필요한 영역에만 접근 권한을 부여하세요. 테스트 환경을 기본값으로 하고, 프로덕션 환경을 인간의 검토가 필요한 예외로 만드세요.

체크리스트

Checklist: ten questions to ask before you add another agent

1. 동일한 실패가 두 번 발생하면, 환경을 점검하나요?
2. 확장하기 전에 어떤 병렬 작업들이 공유하는지 알고 있나요?
3. 모든 중요한 인계(handover)에 확인(acknowledgement)이 포함되나요?
4. '완료'라는 것이 항상 증거와 함께 오나요?
5. 누가 무엇을 승인할 수 있는지, 그리고 승인이 어떻게 이루어지는지가 문서화되어 있나요?
6. 작업 중인 내용(work in progress)이 다른 사람의 작업과 격리되어 있나요?
7. 생존해야 하는 모든 결정은 파일에 저장되나요?
8. 모든 영역에 정확히 한 명의 소유자(owner)가 있나요?
9. 독자가 행동할 수 있는 사실에는 출처(source)가 있나요?
10. 테스트 환경과 프로덕션 환경이 좁은 접근 권한을 가지고 엄격하게 분리되어 있나요?

이 중 어느 것도 특정 모델이나 도구에 국한된 것은 아닙니다. 이는 여러 능력이 있지만 건망증이 있는 협력자들이 하나의 프로젝트를 공유할 때 발생하는 문제입니다. 대부분의 해결책은 좋은 인간 팀이 사용하는 것과 동일합니다: 명확한 소유권, 문서화된 결정, 상태 보고 대신 증거 제시, 그리고 한 사람만이 승인할 수 있는 몇 가지 사항들입니다.

Part 2에는 열 가지가 더 있습니다: 하나의 기계를 두고 경쟁하는 에이전트들, 말을 왜곡하는 것, 시간대 문제, 침묵의 정체(silent stalls), 병목 지점으로서의 인간, 그리고 한 변화가 연결된 모든 것에 파문을 일으킬 때 발생하는 일입니다.

제가 설명한 이 에이전트 팀은 AI 아키텍처를 위한 다이어그램 편집기인 DuctTape.io를 구축합니다.