AI 에이전트 팀과 함께 작업할 때 잘못되는 10가지 (2부)

Part 1에서는 처음 열 가지를 다루었습니다. 증상 수정, 숨겨진 공유, 손실된 메시지, 증거 없는 '완료', 흐릿한 승인, 공유 작업 공간, 희미해지는 컨텍스트, 중복되는 소유권, 그럴듯한 발명품, 그리고 표류하는 환경 등이 그것입니다. 이 두 게시물은 하나의 제품에 작은 에이전트 팀을 적용하면서 얻은 경험에서 비롯되었으며, 저는 How I build a product alone with a team of seven Claude Code agents에서 이를 설명했습니다.

이 열 가지는 더 조용합니다. 빌드를 망가뜨리지는 않지만, 하루를 낭비하거나, 잘못된 결정을 기록으로 남기거나, 청구서로 나타납니다. 형식은 동일합니다: 어떤 모습인지, 왜 발생하는지, 무엇이 도움이 되는지.

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

11. 에이전트들이 같은 기계를 두고 경쟁한다

어떤 모습인가: 한 에이전트가 사용하던 서버가 다른 에이전트에 의해 재시작됩니다. 두 개의 무거운 작업이 동시에 실행되어 둘 다 시간 초과(time out)가 됩니다. 다른 에이전트의 테스트가 같은 계정을 변경했기 때문에 테스트가 실패합니다.

왜 발생하는가: 모든 에이전트는 기계가 자신만의 것이라고 가정합니다. '서버 중지' 또는 '테스트 데이터 초기화'와 같은 명령어는 한 사람이 책상에 앉아 있을 때를 위해 작성된 것입니다.

도움이 되는 것: 각 에이전트에게 자체 포트, 자체 테스트 계정, 그리고 데이터를 둘 수 있는 자신만의 공간을 제공합니다. 무거운 작업(빌드, 전체 테스트 실행, 녹화)은 스케줄링합니다. 에이전트는 자신이 시작한 프로세스만 중지시키고, 광범위한 패턴으로 절대 중지시키지 않습니다. 또한 공유 작업을 공지해야 합니다: '테스트 서버는 다음 40분 동안 사용 중입니다'.

12. 에이전트들이 당신의 입에 말을 넣는다 (Words in your mouth)

어떤 모습인가: 당신이 한 적 없는 것에 대해

도움이 되는 방법은 모든 결정(decision)을 누가, 언제 내렸는지 기록하는 것입니다. 에이전트가 당신을 인용할 때, 그 메시지가 어디에서 왔는지 물어보세요. 에이전트는 "인간이 원한다" 대신 자신들의 말로 "제가 제안합니다(I suggest)"와 "제품 책임자가 결정했습니다(the product owner decided)"라고 작성해야 합니다.

13. 시간은 보이는 것보다 어렵다

현상: 테스트가 매일 자정 무렵에 실패하는 경우. 메시지에 "내일(tomorrow)"이라고 되어 있고 두 에이전트가 다른 날짜를 읽는 경우. 문서의 마감 기한이 한 시간 차이가 나는 경우.

원인: 서버는 UTC로 작동하지만 사람들은 그렇지 않습니다. 에이전트는 인간의 시간대도, 문장이 의미하는 "오늘(today)"도 알지 못하며, 많은 테스트가 조용히 현재 날짜를 사용합니다.

해결책: 중요한 모든 것에 시간대가 명시된 절대 날짜를 작성하세요. 시간을 인간의 현지 시간으로 보고하세요. 테스트에 "지금(now)" 대신 고정된 날짜를 주고, 의도적으로 자정 근처에서 한 번 실행하세요.

우리의 경우, 규칙은 간단해졌습니다. 서버는 UTC로 작동하고, 인간에게 보고되는 모든 시간은 현지 시간입니다.

14. 에이전트가 조용히 정체되다

현상: 에이전트가 몇 시간 동안 "작업 중"인 경우. 실제로는 긴 출력물 끝에서 질문을 던지고 있으며, 아무도 보지 못한 답변을 기다리고 있는 상황입니다.

원인: 질문하고 멈추는 것이 안전한 기본값(safe default)이기 때문입니다. 하지만 긴 보고서 중간에 파묻힌 질문은 놓치기 쉽고, 에이전트는 아무도 읽지 않았다는 것을 알 수 없습니다.

해결책: 질문을 하고 계속 진행하세요: 답변에 의존하지 않는 모든 작업을 에이전트가 수행하게 하고, 질문을 마지막 줄이 아닌 첫 번째 줄로 만드세요. 인간이 확인하는 한 곳에 열린 질문들을 모으세요. 짧은 상태 표시줄("대기 중: X, 시점: 14:20")은 정체를 눈에 보이게 합니다.

15. 인간이 병목 지점이 되다

현상: 하루에 스무 개의 작은 질문들: 어떤 단어, 어떤 색상, 재시도할지 여부 등. 각각은 1분을 차지하고; 함께하면 하루를 차지하며, 모든 에이전트가 당신을 기다리게 만듭니다.

원인: 에이전트는 확신하지 못할 때 질문하라고 지시받고, 많은 사소한 것들에 대해 확신하지 못합니다. 무엇이 '사소한지'에 대한 규칙이 없으면 모든 것이 최상단으로 올라가게 됩니다.

도움이 되는 점: 한 코디네이팅 에이전트(coordinating agent)가 작고 되돌릴 수 있는 결정들을 맡아 기록하게 하세요. 이렇게 하면 나중에 내용을 검토하고 필요하면 특정 결정을 무효화할 수 있습니다. '작은 결정'의 기준을 명확히 작성해 두는 것이 중요합니다. 크거나 돌이킬 수 없는 질문(예: 공개되는 모든 정보, 금전적 문제, 운영 데이터 삭제, 기밀 등)은 여전히 사용자에게 와야 합니다.

Questions from agents go to a coordinating agent: small, reversible ones it decides and logs; big or irreversible ones go to the human

16. 서로 모순되는 규칙들

어떤 모습인가: 두 개의 문서가 같은 질문에 대해 상반된 답변을 제공합니다. 규칙 파일은 여전히 지난달의 작동 방식을 설명하고 있습니다. 에이전트는 구식 규칙을 완벽하게 따릅니다.

왜 발생하는가: 규칙은 추가만 되고 제거되는 경우는 드뭅니다. 새로운 규칙은 기존의 모든 규칙들과 나란히 놓여 있는 것이 아니라, 현재의 작업에 맞춰 작성되기 때문입니다. 에이전트는 규칙을 문자 그대로 읽기 때문에 어떤 규칙이 구식인지 판단할 수 없습니다.

도움이 되는 점: 모든 새로운 규칙을 적용하기 전에 기존 규칙들과 비교하는 전담 역할을 지정하세요. 또한, 행동을 변경하는 것과 동시에 그 행동을 설명하는 규칙들을 업데이트해야 하며, 나중에 따로 처리해서는 안 됩니다. 두 규칙이 불일치할 경우, 에이전트가 임의로 하나를 선택하기보다 사용자에게 질문하도록 만드세요.

17. 필요한 것 이상으로 제안하는 에이전트들

어떤 모습인가: 완료된 모든 작업마다 다음에 무엇을 할지에 대한 다섯 가지 아이디어가 돌아옵니다. 각각의 아이디어는 합리적입니다. 이들이 모여서 원래 2일짜리 기능을 2주짜리로 만듭니다.

왜 발생하는가: 에이전트들은 무엇이 더 좋을 수 있는지 파악하는 데 능하고, 유용하게 쓰이고 싶어 합니다. 하지만 그들 스스로는 어떤 아이디어가 이번 달의 목표에 기여하는지 알지 못합니다.

도움이 되는 점: 제안은 작업(task)이 아닙니다. '나중에 할 일' 목록을 유지하고 현재 전략과 연결하세요. 만약 어떤 아이디어가 목표에 기여하지 않는다면, 죄책감 없이 그 목록에 추가하면 됩니다. 이 목록을 가끔 검토하되, 대부분의 내용은 그대로 두어도 괜찮습니다.

18. 비밀 정보가 채팅창에 남는 경우

어떻게 보이는가 (What it looks like): 에이전트가 작업을 계속하려면 키(key)가 필요하고, 가장 빠른 방법은 그 키를 대화창에 붙여넣는 것입니다. 이제 이 키는 기록(transcript) 안에 존재하게 됩니다. 어쩌면 로그 파일에, 혹은 요약본에 있을 수도 있습니다.

왜 발생하는가 (Why it happens): 작업이 막히고, 필요한 키는 손에 있으며, 채팅창은 바로 그곳에 있습니다. 아무도 계획하지 않습니다. 급하게 발생합니다.

어떤 것이 도움이 되는가 (What helps): 필요하기 전에 안전한 경로를 준비하세요. 사람이 이 키를 로컬의 무시되는 파일(ignored file)에 작성하고, 에이전트는 이를 출력하지 않고 그 파일에서 읽도록 해야 합니다. 에이전트는 키를 반복해서 말하는 것을 거부하고 대신 해당 경로를 요청해야 합니다. 채팅을 거친 키는 노출된 것으로 간주되므로, 즉시 교체(rotate)하세요.

19. 할당량 및 비용에 놀라다 (Quotas and costs surprise you)

어떻게 보이는가 (What it looks like): 월 중반쯤 갑자기 한계치에 도달합니다. 빌드 시간, API 할당량(quota), 저장 공간, 플랜 제한 등이 그것입니다. 작업이 멈추거나, 아무도 예상하지 못한 청구서가 도착합니다.

왜 발생하는가 (Why it happens): 에이전트는 사람보다 훨씬 빠르게 작동하며 망설임 없이 반복 작업을 수행합니다. 빌드를 한 번 더 하거나, 전체 테스트를 한 번 더 실행하는 식입니다. 이 한계치에 도달할 때까지 아무도 총합을 계산하지 않습니다.

어떤 것이 도움이 되는가 (What helps): 확장하기 전에 할당량을 파악하세요. 한 번의 실행이 얼마의 비용이 드는지 측정하고, 예산 및 알림(alerts)을 설정하며, 값비싼 작업에는 확인 절차를 거치도록 하세요. 돈을 쓰는 것은 여전히 인간의 결정이어야 합니다.

20. 하나의 변경 사항이 연결된 모든 것에 파문을 일으킨다 (One change ripples through everything connected)

어떻게 보이는가 (What it looks like): 저장소(repository)가 이동하거나, 키가 교체되거나, 도메인이 변경되면 세 가지 이상의 다른 것들이 고장 납니다. 파이프라인, 통합(integration), 문서의 링크, 에이전트가 여전히 따르는 규칙 등이 그것입니다.

왜 발생하는가 (Why it happens): 연결고리들이 조용히 쌓입니다. 각각은 누군가가 어떤 이유로 설정했지만, 그 누구도 기록하지 않은 것입니다. 변경을 수행하는 에이전트는 오직 변화만을 봅니다.

어떤 것이 도움이 되는가 (What helps): 인프라에 어떤 변경을 가하기 전에는 그것과 연결된 모든 것을 목록화하고, 백업을 만들고, 한 번에 하나의 것만 변경하며, 각 항목을 나중에 확인하세요. 이 목록은 문서로 보관하여 다음 변경 시에도 이를 기준으로 삼도록 하세요.

One change in the middle, six connected places around it, each with a box to check

체크리스트

Checklist: ten more questions for an agent team

모든 에이전트가 자체 포트, 계정 및 테스트 데이터를 가지고 있습니까?
누가 실제로 결정했는지와 함께 모든 결정이 기록됩니까?
날짜는 시간대가 포함된 절대적인 것입니까?
대기 중인 에이전트는 첫 줄에 그렇게 말하고 나머지 작업은 계속합니까?
어떤 결정을 에이전트가 스스로 내릴 수 있는지 문서화되어 있습니까?
새로운 규칙은 이전 규칙과 비교되고, 변경될 때마다 업데이트됩니까?
제안은 현재 목표에 기여하지 않는 한 '나중에' 목록으로 보내집니까?
비밀 정보(secrets)를 위한 안전한 경로는 있으며, 유출된 정보는 순환(rotate)됩니까?
예산과 함께 실행 비용을 측정합니까?
모든 인프라 변경에는 지도, 백업 및 체크리스트가 수반됩니까?

이러한 항목들을 part 1과 종합해 보면 패턴은 같습니다: 에이전트는 빠르고, 유능하며, 문자 그대로(literal) 작동합니다. 대부분의 문제는 다른 에이전트, 시간, 인간의 주의력, 그리고 변경 주변의 연결고리 등 그들이 볼 수 없는 것에서 발생합니다. 대부분의 해결책은 이러한 요소들을 가시화하고 문서로 남기는 것입니다.

본 포스트에 등장하는 에이전트 팀은 AI 아키텍처를 위한 다이어그램 편집기인 DuctTape.io를 구축했습니다.