당신의 AI 에이전트가 계속 고장 나는 이유: 자율 시스템을 위한 디버깅 가이드

자율 AI 에이전트를 24시간 7일 내내 30일 동안 실행한 후, 저는 모든 실패 모드(failure mode)에 대한 데이터를 수집했습니다. 환각(hallucination)을 일으킨 파일 경로부터 병렬 실행(parallel execution)에서의 레이스 컨디션(race conditions)까지, 무엇이 잘못되는지 그리고 정확히 어떻게 수정해야 하는지에 대한 모든 것을 소개합니다.

새벽 3시의 전화

휴대폰이 울립니다. 모니터링 알림입니다: 에이전트가 오전 3:17에 충돌했습니다. 또다시 말이죠.

로그를 확인합니다. 에이전트는 풀 리퀘스트(pull request)를 제출하던 중이었습니다. 그런데 에이전트는 notification_service.py가 존재한다고 판단했고(실제로는 존재하지 않음), 이를 위해 25개의 테스트를 작성했습니다(모두 모크(mock)를 대상으로 통과함). 그 후 브랜치를 푸시하고, PR을 생성한 뒤, 자신 있게 보고했습니다: "PR이 성공적으로 제출되었습니다. 모든 테스트를 통과했습니다."

4분 후 CodeRabbit이 검토했습니다: "이 PR은 이 브랜치에 존재하지 않는 notification_service.py를 참조하고 있습니다."

이것은 가설이 아닙니다. 저에게 실제로 일어난 일입니다. 30일간의 자율 바운티 헌팅(bounty-hunting) 실험 중 12일째에 발생했습니다. 그리고 이것은 제가 분류한 수십 가지 실패 모드 중 하나일 뿐입니다.

이 글은 제가 시작하기 전에 가졌더라면 좋았을 디버깅 가이드입니다.

실패 분류 체계 (The Failure Taxonomy)

30일 동안 200개 이상의 에이전트 실패 사례를 분석한 결과, 저는 이를 7가지 뚜렷한 유형으로 분류했습니다:

유형 1: 확신에 찬 환각 (Confident Hallucination) (실패의 34%)

현상: 에이전트가 존재하지 않는 파일, 함수 또는 API를 참조하는 코드를 생성합니다. 존재하지 않는 이러한 컴포넌트의 모크(mocked) 버전을 대상으로 테스트를 작성합니다. 테스트는 통과합니다. 에이전트는 성공을 보고합니다.

실제 사례:

# 에이전트가 작성한 테스트
from backend.services.notification_service import NotificationService

...

문제는 무엇일까요? 모듈 이름은 notification_service가 아니라 notification_routing입니다. 에이전트는 이슈(issue) 제목을 바탕으로 이름을 환각해낸 것입니다.

근본 원인 (Root cause): 에이전트는 이슈 제목을 읽고, 파일 구조를 추론하며, 파일의 존재 여부를 확인하지 않고 코드를 생성합니다. LLM(대규모 언어 모델)은 패턴 매칭에 매우 뛰어나기 때문에, 존재하지 않는 모듈에 대해서도 그럴듯해 보이는 코드를 만들어냅니다.

예방 방법:

# 어떤 코드라도 작성하기 전에, 대상이 존재하는지 확인하십시오
find . -name "*notification*" -type f | head -5
grep -r "class.*Service" backend/services/ --include="*.py" | head -10

해결책 (Fix): 에이전트 파이프라인 (agent pipeline)에 필수적인 코드 작성 전 검증 단계를 추가하십시오:

1. 대상 파일/모듈을 검색합니다.
2. 찾을 수 없는 경우, 유사한 이름을 검색합니다.
3. 여전히 찾을 수 없다면, 모호함을 보고하고 중단합니다.

유형 2: 병렬 실행 시의 경합 조건 (Race Condition) (실패 사례의 21%)

발생 상황: 여러 에이전트 인스턴스 (agent instances) 또는 백그라운드 프로세스 (background processes)가 동시에 동일한 파일을 수정합니다. 이로 인해 Git 충돌이 발생하거나, 브랜치 (branch)가 손상되거나, 테스트 결과가 오래된 상태 (stale)가 됩니다.

실제 시나리오:

• 에이전트 A가 이슈 #915 (번역 테스트) 작업을 시작합니다.
• 에이전트 B가 이슈 #916 (분류기 테스트) 작업을 시작합니다.
• 두 에이전트 모두 동일한 커밋 (commit) 시점에서 저장소 (repo)를 클론 (clone) 합니다.
• 두 에이전트 모두 main 브랜치로부터 브랜치를 생성합니다.
• 에이전트 A가 먼저 푸시 (push) 하여 성공합니다.
• 에이전트 B가 푸시를 시도하지만, GitHub에서 거부합니다 (다른 내용으로 이미 브랜치가 존재함).

근본 원인 (Root cause): 병렬로 실행되는 에이전트 인스턴스 간의 조정 (coordination)이 없습니다. 각 에이전트는 서로를 인지하지 못한 채 독립적으로 작동합니다.

예방 방법:

# 작업을 시작하기 전에, 이 이슈에 대한 브랜치가 이미 있는지 확인합니다
git branch -r | grep "issue-915"
# 다른 누군가가 이미 PR (Pull Request)을 제출했는지 확인합니다
...

해결책 (Fix): 분산 잠금 메커니즘 (distributed lock mechanism)을 구현하십시오:

1. 작업을 시작하기 전에 "점유 (claim)" 파일 또는 GitHub 이슈 댓글을 생성합니다.
2. 진행하기 전에 기존의 점유 사항이 있는지 확인합니다.
3. 로컬 병렬 실행의 경우 파일 기반 잠금 (file-based locks)을 사용합니다.

유형 3: 오래된 컨텍스트 / 업데이트되지 않은 코드베이스 (Stale Context / Outdated Codebase) (실패 사례의 18%)

발생 상황: 에이전트가 어제까지는 유효했지만 그 이후로 업데이트된 코드를 바탕으로 작업합니다. 로컬에서는 테스트가 통과하지만, 베이스 브랜치 (base branch)가 변경되었기 때문에 CI (지속적 통합) 환경에서는 실패합니다.

실제 시나리오:

1일 차: 에이전트가 커밋 abc123 시점에서 저장소를 클론합니다.
2일 차: 유지 관리자 (Maintainer)가 15개의 새로운 커밋을 푸시합니다.
3일 차: 에이전트가 abc123을 기반으로 PR을 제출합니다.
...

근본 원인 (Root cause): 에이전트가 작업을 시작하기 전에 최신 변경 사항을 가져오지 (fetch) 않습니다. 또는 가져오기는 하지만 리베이스 (rebase)를 수행하지 않습니다.

예방 (Prevention):

# 작업을 시작하기 전에 항상 fetch 및 rebase를 수행하세요
git fetch upstream
git rebase upstream/main
...

해결 (Fix): 파이프라인에 최신 상태 확인 (freshness check) 단계를 추가하세요:

1. 작업을 시작하기 전, 최신 사항을 가져오기 (fetch)
2. 만약 10개 이상의 커밋이 뒤처져 있다면, 다시 클론 (re-clone)
3. 푸시 (push) 하기 전에는 항상 리베이스 (rebase) 수행

유형 4: 테스트 환경 불일치 (실패의 12%)

현상: 에이전트의 환경이 CI (지속적 통합) 환경과 달라 로컬에서는 테스트가 통과하지만 CI에서는 실패합니다.

흔한 불일치 사례:

• Python 버전 (에이전트는 3.12, CI는 3.11)
• 누락된 의존성 (에이전트에는 torch가 설치되어 있으나, CI에는 없음)
• 환경 변수 (에이전트에는 Supabase 키가 있으나, CI에는 없음)
• 파일 경로 (에이전트는 /tmp를 사용하지만, CI는 /home/runner/work/를 사용)

예방 (Prevention):

# CI 설정을 확인하세요
cat .github/workflows/ci.yml
# 로컬 환경을 CI 환경과 일치시키세요
...

해결 (Fix): CI와 일치하는 컨테이너 내에서 테스트를 실행하세요:

docker run -v $(pwd):/app -w /app python:3.11-slim \
  bash -c "pip install -r requirements.txt && pytest"

유형 5: 잘못된 이슈 연결 (실패의 8%)

현상: 에이전트가 PR (Pull Request) 설명에 잘못된 이슈 번호를 참조합니다. 이로 인해 머지 (merge) 시 PR이 잘못된 이슈를 닫아버리는 문제가 발생합니다.

실제 사례:

Fixes #824  # 잘못됨! #832여야 함

근본 원인: 에이전트가 이슈 제목을 읽었으나, 작성한 코드는 유사한 제목을 가진 다른 이슈를 해결하는 내용인 경우입니다.

예방 (Prevention):

# 이슈 번호가 실제 작업 내용과 일치하는지 항상 확인하세요
gh api repos/{owner}/{repo}/issues/{number} --jq '.title'
# 실제로 구현한 내용과 비교하세요

해결 (Fix): PR 템플릿에 이슈 검증 단계를 추가하세요:

1. 제출하기 전, 이슈를 다시 읽기
2. 코드가 정확히 해당 이슈를 해결하는지 확인
3. 이슈 번호를 재차 확인

유형 6: 토큰/API 소진 (실패의 5%)

현상: 에이전트가 작업 도중 API 크레딧을 모두 소진합니다. 테스트를 작성하던 도중 LLM API가 402 에러를 반환할 수 있습니다.

실제 시나리오:

Agent: 25개 중 15번째 테스트 작성 중...
API: 402 잔액 부족 (Insufficient Balance)
Agent: [조용히 실패하며, 부분적 성공으로 보고함]

근본 원인 (Root cause): 예산 모니터링(Budget monitoring) 또는 우아한 성능 저하(Graceful degradation) 메커니즘의 부재.

예방 (Prevention):

# 긴 작업을 시작하기 전에 API 잔액을 확인합니다
def check_api_health():
    try:
...

해결책 (Fix): 우아한 성능 저하(Graceful degradation)를 구현하세요:

1. 시작 전 API 상태(Health)를 확인합니다.
2. 잔액이 부족하면 무료 모델(Groq, Gemini)로 전환합니다.
3. 모든 API가 실패하면 진행 상황을 저장하고 일시 중지합니다.

유형 7: 조용한 데이터 손실 (Silent Data Loss) (실패 사례의 2%)

발생 현상: 에이전트가 자신의 작업 내용을 덮어쓰거나, 진행 상황을 놓치거나, 상태 파일(State files)을 손상시킵니다.

실제 시나리오:

Agent: /tmp/agent-state.json 에 쓰는 중
Agent: [쓰기 도중 충돌(Crash) 발생]
Agent: [재시작 후, 손상된 상태를 읽음]
...

근본 원인 (Root cause): 원자적 쓰기(Atomic writes) 미비, 상태 지속성(State persistence) 부재, 충돌 복구(Crash recovery) 기능 부재.

예방 (Prevention):

# 원자적 쓰기(Atomic writes)를 사용합니다
import tempfile, os

...

해결책 (Fix): 충돌 복구(Crash recovery)를 구현하세요:

1. 상태를 원자적 파일(Atomic files)에 기록합니다.
2. 재시작 시 완료되지 않은 작업이 있는지 확인합니다.
3. 마지막 체크포인트(Checkpoint)에서 재개합니다.

디버깅 플레이북 (The Debugging Playbook)

에이전트가 실패하면 다음 체크리스트를 따르세요:

1단계: 전체 에러 읽기

마지막 줄만 읽지 마세요. 진짜 에러는 보통 충돌(Crash)이 발생하기 10~20줄 전에 나타납니다.

# 에이전트 출력의 마지막 50줄을 가져옵니다
tail -50 /var/log/agent.log

...

2단계: 실패 유형 식별

에러를 위의 7가지 유형 중 하나와 매칭하세요. 이를 통해 근본 원인과 해결책을 알 수 있습니다.

3단계: 환경 확인

# 에이전트가 실행 중인가요?
ps aux | grep agent

...

4단계: 상태 확인

# 충돌 시 에이전트가 무엇을 하고 있었나요?
cat /path/to/agent/state/current_task.json

...

5단계: 수정 및 재시작

# 근본 원인을 수정합니다
# ...

...

모니터링 대시보드 (The Monitoring Dashboard)

모든 자율 에이전트에는 모니터링이 필요합니다. 추적해야 할 항목은 다음과 같습니다:

지표 (Metric)	경고 임계값 (Alert Threshold)	조치 (Action)
PR 제출률 (PR Submission Rate)	< 1/hour	API 상태 확인 (Check API health)
...

간단한 모니터링 스크립트 (Simple Monitoring Script)

#!/bin/bash
# monitor-agent.sh — cron을 통해 5분마다 실행

...

실제 디버깅 세션: 번역 테스트 실패 사례

실험 15일 차에 발생했던 실제 디버깅 세션을 안내해 드리겠습니다. 이는 실제 로그와 실제 해결책이 포함된 실제 실패 사례입니다.

설정 (The Setup)

에이전트에게는 번역 파이프라인(translation pipeline)을 위한 단위 테스트(unit tests)를 작성하는 작업이 주어졌습니다. 이 파이프라인은 언어를 감지하고 Helsinki-NLP MarianMT 모델을 사용하여 텍스트를 번역하는 Python 모듈입니다. 문제는 단순했습니다: "translation_service에 대한 단위 테스트를 추가하세요."

실패 (The Failure)

에이전트는 35개의 테스트가 포함된 PR #928을 제출했습니다. 로컬에서는 모두 통과했습니다. 하지만 CodeRabbit이 이를 검토하고 다음과 같이 플래그를 지정했습니다:

"테스트가 lp._MODEL_CACHE를 참조하고 있지만, 실제 코드에서는 @lru_cache를 사용하고 있습니다. 테스트는 모의 객체(mocks)를 대상으로는 통과하겠지만, 실제 캐싱 동작(caching behavior)은 잡아내지 못할 것입니다."

디버깅 과정 (The Debugging Process)

1단계: 전체 리뷰 읽기

gh api repos/ritesh-1918/HELPDESK.AI/pulls/928/comments --jq '.[].body'

2단계: 테스트 가정과 실제 코드 비교

# 테스트가 가정하는 내용:
grep "_MODEL_CACHE" backend/tests/test_language_pipeline.py
# 출력 결과: lp._MODEL_CACHE.clear()
...

3단계: 근본 원인 파악

에이전트는 다른 테스트 파일에서 이 패턴을 보았기 때문에 _MODEL_CACHE를 사용했습니다. 하지만 실제 번역 모듈은 Python의 @lru_cache 데코레이터(decorator)를 사용하며, 이는 캐시를 비우는 방식이 다릅니다 (.cache_clear() vs .clear()).

4단계: 수정 (Fix)

# 수정 전 (오류):
lp._MODEL_CACHE.clear()

...

5단계: 검증 (Verify)

python3 -m pytest backend/tests/test_language_pipeline.py -v

교훈 (The Lesson)

에이전트는 다른 곳에서 본 패턴을 바탕으로 합리적인 가정(reasonable assumption)을 내렸습니다. 하지만 "합리적인 가정"은 정확성(correctness)의 적입니다. 수정 작업은 사소했지만, 이는 우리가 유지 관리자(maintainer)보다 먼저 이를 발견했기 때문에 가능했습니다.

고급 디버깅: 에이전트 자체 감사 (The Agent Self-Audit)

200회 이상의 실패를 거친 후, 저는 에이전트가 모든 PR (Pull Request) 제출 전에 실행하는 자체 감사 프로토콜 (self-audit protocol)을 개발했습니다:

def self_audit(pr_branch, issue_number):
    """모든 PR 제출 전에 실행합니다."""

...

이 자체 감사는 실패 사례의 60%를 유지 관리자 (maintainer)에게 도달하기 전에 잡아냅니다.

200회 이상의 실패로부터 얻은 교훈

1. 에이전트의 성능은 가드레일 (Guards)의 성능과 비례한다

검증 단계 (verification steps)가 없다면, 에이전트는 확신에 찬 태도로 잘못된 출력을 생성할 것입니다. "파일 존재 여부 확인" 체크, "푸시 전 리베이스 (rebase)" 단계, "API 잔액 확인" 가드레일 하나하나가 특정 유형의 실패를 방지합니다.

2. 침묵하는 실패 (Silent Failures)는 명시적인 충돌 (Crashes)보다 나쁘다

충돌은 눈에 보입니다. 하지만 잘못된 이슈에 대해 PR을 제출하거나, 존재하지 않는 파일에 대한 테스트를 작성하는 것과 같은 침묵하는 실패는 유지 관리자의 시간을 수 시간 동안 낭비하게 만들고 당신의 평판을 해칩니다.

3. 상태 유지 (State Persistence)는 타협할 수 없는 요소다

만약 당신의 에이전트가 충돌 후에도 살아남아 재개할 수 없다면, 정전 한 번에 모든 진행 상황을 잃게 될 것입니다. 원자적 쓰기 (Atomic writes), 체크포인트 파일 (checkpoint files), 그리고 충돌 복구 (crash recovery)는 필수 사항입니다.

4. 모니터링 (Monitoring) > 로깅 (Logging)

로그 (Logs)는 무엇이 일어났는지를 알려줍니다. 모니터링 (Monitoring)은 지금 당장(RIGHT NOW) 무엇이 일어나고 있는지를 알려줍니다. 에러율 (error rates), API 상태 (API health), 그리고 정체된 상태 (stuck states)에 대한 알림 (alerts)을 설정하세요.

5. 가장 단순한 해결책이 종종 최선이다

에이전트의 실패를 디버깅할 때, 복잡한 솔루션을 만들고 싶은 충동을 억제하세요. 종종 해결책은 다음과 같습니다:

• 테스트를 작성하기 전에 file.exists() 체크 추가
• 작업을 시작하기 전에 git fetch 추가
• API 호출 주변에 try/except 추가

단순한 가드레일이 실패의 80%를 방지합니다.

디버깅을 하지 않았을 때의 비용

실제 수치로 말씀드리겠습니다. 30일간의 실험 동안:

지표 (Metric)	디버깅 없음	디버깅 있음
제출된 PR (PRs Submitted)	84	84
...

차이점이 무엇일까요? 바로 **디버깅 가드레일 (Debugging guards)**입니다. 모든 file.exists() 체크, 시작 전 모든 git fetch, 제출 전 모든 self_audit() — 각각의 단계가 그렇지 않았다면 수 시간을 낭비했을 특정 유형의 실패를 방지합니다.

수학적 계산

디버깅이 없다면:

• 70개의 실패한 PR (Pull Requests) × 평균 30분의 낭비 = 35시간
• 8건의 유지관리자 (Maintainer) 불만 × 해결에 1시간 = 8시간
• 평판 손상 = 수치화할 수 없으나 실재함
• 총 비용: 43시간 이상 + 손상된 평판

디버깅이 있는 경우:

• 25개의 실패한 PR (Pull Requests) × 평균 15분 = 6.25시간
• 유지관리자 (Maintainer) 불만 0건
• 평판 유지
• 총 비용: 6.25시간

디버깅 오버헤드 (Overhead)는 구현에 약 2시간이 소요됩니다. 절감되는 시간은 37시간 이상입니다.

이는 평판을 제외하고도 18:1의 투자 대비 수익 (ROI)을 나타냅니다.

자신만의 에이전트 디버깅 툴킷 구축하기

자율 에이전트 (Autonomous Agent)를 구축하고 있다면, 다음과 같은 최소한의 툴킷 (Toolkit)이 필요합니다:

1. 사전 점검 (Pre-flight Checks) (모든 작업 시작 전 실행)

def preflight_check(task):
    """작업을 시작하기 전에 환경을 검증합니다."""
    checks = {
...