문제 해결과 운영 팁: 실패한 실행을 되살리는 디버깅 루틴
막히는 순간을 '사고'가 아니라 '절차'로 바꾸기
Antigravity를 꾸준히 쓰려면 "에이전트가 가끔 실패한다"는 사실을 전제로 운영해야 합니다. 문제는 실패 자체가 아니라, 실패했을 때 사람이 매번 즉흥적으로 대응하면서 시간이 새는 것입니다. 그래서 이 챕터는 막히는 순간을 위한 복구 루틴을 제시합니다. 핵심은 단순합니다. 멈추고, 증거를 모으고, 실패 유형을 분류하고, 가장 작은 실험으로 다시 시작하는 것입니다.
에이전트가 헤매는 신호: '열심히 하는데' 진전이 없다
에이전트가 진짜로 막히면 겉으로는 정상처럼 보일 때가 많습니다. 커밋도 하고 파일도 만들고 말도 그럴듯합니다. 하지만 결과적으로 목표가 가까워지지 않습니다. 장기간 루프를 돌린 데이터를 보면 "문제 있는 루프"가 상당 비율로 등장하며, 에이전트 자기 요약이 실제 상태를 가리는 경우도 흔합니다.2
현장에서 가장 자주 보이는 패턴은 세 가지로 정리할 수 있습니다. 같은 행동을 반복하는 Repeater, 바쁘게 움직이지만 목표와 연결이 끊긴 Wanderer, A와 B 사이를 왕복하는 Looper입니다.1 이 셋은 증상이 비슷합니다. 활동량은 높은데 진행 지표가 정체됩니다.1
여기서 중요한 운영 팁이 하나 있습니다. "에이전트가 무엇을 했는지"가 아니라 "목표에 가까워졌는지"를 측정하는 진행 지표(progress metric)를 반드시 잡아야 합니다.1 코딩 작업이라면 '실패 테스트 개수', '빌드 성공 여부', '재현 스크립트의 pass/fail' 같은 지표가 가장 안전합니다.
10분 응급 루틴: 멈추기 → 스냅샷 → 분류 → 최소 실험
막히는 순간, 가장 먼저 할 일은 "더 시도해보자"가 아니라 "현재 상태를 고정하자"입니다. 디버깅은 근거가 축적될수록 쉬워지지만, 에이전트의 무작정 반복은 근거를 늘리기보다 잡음을 늘립니다.
첫째, 실행을 잠깐 멈추고 현재 상태를 아티팩트로 고정합니다. 터미널 출력, 실패한 테스트 결과, 관련 파일 diff, 브라우저 콘솔/네트워크 캡처 같은 '지금의 증거'를 묶어 둡니다.
둘째, 문제가 '도구 호출'인지 '추론/지시'인지 빠르게 분류합니다. 에이전트 시스템 디버깅에서 가장 중요한 구분이기도 합니다.4
셋째, 가장 작은 단위의 최소 실험(다시 실행할 테스트 1개, 재현 스크립트 1개, 도구 호출 1번)을 정하고, 그 실험이 통과하면 다음 단계로, 실패하면 가설을 바꿉니다. 에이전트 디버깅은 원래 "추측"이 아니라 "가능성을 좁히는 과정"이라는 점이 여러 워크플로 가이드에서도 강조됩니다.5
실패 유형을 분류하면, 재지시 문장이 달라진다
"왜 안 돼?"는 좋은 디버깅 질문이 아닙니다. 먼저 실패를 분류해야, 에이전트에게 줄 지시가 정밀해집니다. 현업에서 유용한 분류는 다음 다섯 가지입니다. 도구 자체가 실패한 Tool failure, 도구를 잘못 고른 Tool selection failure, 필요한 정보가 없는 Context failure, 정보는 있는데 결론을 잘못 낸 Reasoning failure, 형식/제약을 어긴 Instruction failure입니다.3
분류의 장점은 간단합니다. 도구 실패는 리트라이/권한/스키마/타임아웃 같은 엔지니어링 처방이 맞고, 추론 실패는 프롬프트/예시/제약 강화가 맞습니다.4 원인을 잘못 잡으면, "프롬프트를 아무리 다듬어도 깨진 API는 고쳐지지 않고", "리트라이를 아무리 넣어도 잘못된 추론은 그대로"인 상태가 됩니다.4
재지시의 기술: '해결'이 아니라 '진단'을 먼저 시킨다
에이전트가 헤매는 상황에서 가장 흔한 실수는, 바로 "코드를 고치라"고 재지시하는 것입니다. 그러면 에이전트는 자신이 이미 틀린 가설 위에서 더 많은 변경을 쌓기 쉽습니다.
디버깅용 재지시는 다음 두 단계로 끊는 편이 안전합니다. 먼저 가설과 진단 계획만 내게 하고, 그 계획을 사람이 승인한 다음에만 수정하도록 합니다.5
예를 들어 이런 문장이 효과적입니다.
"지금 오류를 5~7개 원인 가설로 분류하고, 각 가설을 검증할 최소 진단(명령/테스트/관찰)을 제안해. 아직 코드는 수정하지 마."5
그리고 진단 결과를 받았으면, 그 다음 지시에서 "무엇을 바꿀지"를 좁힙니다.
"가설 2를 우선 검증하자. 테스트 A만 실행해서 재현을 확인하고, 통과/실패에 따라 다음 행동을 분기해. 변경은 관련 파일 1개로 제한해."
이 방식은 에이전트가 무작정 손대는 범위를 줄이고, 결과가 '검증 가능한 아티팩트'로 남게 합니다.
범위 축소: 에이전트가 길을 잃을수록 '작게' 쪼개라
에이전트가 막히면 "더 많은 맥락"을 주고 싶어집니다. 하지만 실제로는 반대가 유효한 경우가 많습니다. 맥락이 커질수록 에이전트는 그 안에서 그럴듯한 길을 더 많이 찾고, 그만큼 목표에서 벗어나기 쉬워집니다.
범위 축소는 세 가지 축에서 합니다. 첫째는 대상 축소입니다. "전체 로그인 플로우"가 아니라 "이 버튼 클릭 시 네트워크 요청이 나가는지"처럼 관찰 가능한 단일 지점으로 줄입니다. 둘째는 변경 축소입니다. 한 번의 시도에서 수정 파일 수와 함수 수를 제한합니다. 셋째는 검증 축소입니다. 테스트 전체가 아니라 "실패 테스트 1개"를 통과시키는 데 집중합니다.1
에이전트가 같은 시도를 반복하는 Repeater라면 "다른 접근을 강제"해야 하고, 바쁘지만 진전이 없는 Wanderer라면 "done(완료)의 정의를 다시 쓰게" 해야 한다는 운영 패턴도 참고할 만합니다.1
재현을 만들면, 복구가 빨라진다: 최소 재현(MRE)과 회귀 테스트
사람이든 에이전트든, 재현이 없는 디버깅은 감에 의존하게 됩니다. 그래서 실패한 실행을 되살리는 가장 강력한 복구 전략은 재현을 먼저 만드는 것입니다.
재현을 만들 때는 '최소 재현 예제(Minimal Reproducible Example)' 원칙을 따르는 것이 좋습니다. 가능한 한 작게(minimal), 필요한 것을 빠짐없이(complete), 그리고 누가 실행해도 같은 결과(reproducible)가 나오는 형태가 목표입니다.7
실무에서 Antigravity가 해줄 수 있는 역할은 큽니다. 에이전트에게 "재현 프로젝트/재현 스크립트/재현 테스트"를 만들게 하고, 사람이 그 재현이 정말 최소인지 검수하면 됩니다. Gatsby나 Clerk 같은 문서들도, 재현은 '처음부터 작은 템플릿으로 시작해 필요한 것만 추가'하는 방식이 가장 효율적이라고 안내합니다.89
재현을 만드는 과정 자체가 원인을 밝히는 경우도 많습니다. 불필요한 기능과 의존성을 제거하다 보면, 문제가 사라지는 지점이 드러나기 때문입니다.10 그리고 재현이 완성되면, 그 자체를 회귀 테스트로 고정해 "다시는 같은 방식으로 실패하지 않게" 만들 수 있습니다.10
반복 디버깅의 함정: 3번째부터는 '더 시도'가 아니라 '리셋'이 유리하다
에이전트 디버깅에서 특히 위험한 구간이 있습니다. 같은 대화 맥락에서 실패를 3~4번 반복하면, 에이전트가 점점 엉뚱한 코드를 만지거나 이전 버그를 되돌리는 현상이 늘어납니다. 이는 단순한 운이 아니라, 반복 디버깅에서 성능이 떨어지는 '감쇠' 패턴으로 설명됩니다.6
이때 필요한 전략이 'Fresh start(새로 시작)'입니다. 단, 새로 시작하되 아무것도 버리면 안 됩니다. 새 세션에 넘길 것은 다음 두 가지뿐입니다.
첫째, 고정된 사실입니다. 재현 절차, 실패 로그, 실패 테스트, 환경 정보 같은 변하지 않는 증거입니다.4
둘째, 명확한 제약과 목표입니다. "이 테스트를 통과시켜라", "이 파일만 수정해라", "새 의존성 추가 금지" 같은 통제 문장입니다.
그리고 이전 세션에서 나온 긴 설명이나 추측은 과감히 버립니다. 반복된 실패 맥락이 오히려 다음 시도를 왜곡할 수 있기 때문입니다.6
운영 가드레일: 루프 감지, 타임아웃, 추적(Trace) 없이는 못 고친다
에이전트가 막히는 문제는 개인 실수라기보다 시스템 문제에 가깝습니다. 그래서 운영에서는 "잘 쓰는 법"과 함께 "망가졌을 때 자동으로 멈추는 법"이 필요합니다.
우선 루프 감지입니다. 최근 행동 타입이 동일하게 반복되는지, 일정 횟수 동안 진행 지표가 변하지 않는지를 감지해 stuck 상태를 판정하는 방식이 널리 쓰입니다.1 여기에 킬 스위치(즉시 중단 신호)를 두면 비용 폭주를 막을 수 있습니다.1
다음은 추적(Trace)입니다. 에이전트 디버깅은 전통적인 프로그램 디버깅보다 비결정성이 커서, "어떤 프롬프트로 어떤 도구를 어떤 인자로 호출했고 무엇을 받았는지"를 실행 단위로 복기할 수 있어야 합니다.4 트레이스는 에이전트의 '블랙박스'입니다. 그리고 분석은 보통 "결과에서 거꾸로" 보는 편이 빠릅니다. 최종 응답이 어디서 어긋났는지, 바로 이전 단계의 도구 출력이 이상했는지, 그 도구 선택이 애초에 맞았는지 역추적합니다.4
마지막은 측정입니다. 장시간 루프를 돌리는 환경이라면, friction/failure/waste/stagnation 같은 신호를 누적해 "지금이 생산 구간인지, 정체 구간인지"를 분류하고, 효과 없는 자동 복구가 오히려 문제를 증폭시키는 피드백 루프도 탐지해야 합니다.2
팀 운영 팁: 실패를 '사례'가 아니라 '자산'으로 남기기
디버깅 루틴이 개인의 요령으로 끝나면, 팀은 같은 구덩이에 반복해서 빠집니다. 그래서 실패가 발생할 때마다 다음 세 가지를 남겨야 합니다.
첫째, 실패 기록을 표준화합니다. 입력, 기대 결과, 실제 결과, 실행 환경, 관련 트레이스/아티팩트를 한 묶음으로 남깁니다.4
둘째, 실패 유형(도구/선택/컨텍스트/추론/지시)을 태깅해, 반복되는 원인을 통계로 보이게 만듭니다.3
셋째, 재현과 회귀 테스트를 남깁니다. 최소 재현이 곧 다음 배포의 안전장치가 됩니다.710
이렇게 쌓인 실패 아카이브는 다음 챕터에서 다룰 "개인·팀 개발 시스템"의 핵심 부품이 됩니다. 에이전트는 잘 쓰면 생산성을 올리지만, 안정적으로 쓰려면 결국 복구 가능한 운영 체계가 필요합니다.
참고
1How to Detect When Your AI Agent Is Stuck (And What to Do About It)
2How to Tell If Your AI Agent Is Stuck (With Real Data From 220 Loops)
3Debugging Agent Failures: A Systematic Approach
4How to Debug AI Agent Responses When Something Goes Wrong
5Debugging Workflow for Agentic Coding
6Why Coding Agents Fail After Multiple Debugging Attempts
7How to create a Minimal, Reproducible Example
8How to Make a Reproducible Test Case (Gatsby)
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.