Originally published on tamiz.pro.
AI 코딩 에이전트가 임계점을 넘었습니다. 이들은 기능을 스캐폴딩(scaffold)하고, 테스트 스위트를 작성하며, 모듈을 리팩토링할 수 있습니다. 하지만 이들이 생성하는 코드는 크게 충돌하여 실패하는 경우는 드뭅니다. 대신 더 조용하고 교묘한 방식으로 잘못됩니다 — 바로 '거의 맞는(almost right)' 패턴입니다. 함수는 실행되고, 테스트는 행복 경로(happy path)에서 통과하지만, 결국 새벽 2시에 프로덕션 사고가 발생합니다. 본 기사에서는 에이전트가 왜 이런 식으로 실패하는지 분석하고, 반복되는 실패 모드를 모델 디코딩(model decoding) 및 컨텍스트 처리(context handling)의 근본 원인에 매핑하며, '거의 맞는' 것을 '실제로 맞는' 것으로 전환하기 위한 구체적인 디버깅 플레이북을 제공합니다.
목차
-
- 거의 맞는 패턴 분류법 (The Almost Right Taxonomy)
-
- 내부 작동 원리(Root Causes Under the Hood)
-
- 디버깅 플레이북 (The Debugging Playbook)
-
- 패턴별 수정 방법 (Pattern-Specific Fixes)
-
- 에이전트 루프 엔지니어링 (Engineering the Agent Loop)
-
- 에이전트를 신뢰해야 할 때
-
- 자주 묻는 질문 (Frequently Asked Questions)
1. 거의 맞는 패턴 분류법 (The Almost Right Taxonomy)
에이전트를 디버깅하려면, 먼저 그 실패의 형태를 인식해야 합니다. '거의 맞는' 버그들은 다섯 가지 반복되는 패턴으로 군집화됩니다.
1.1 경계 및 오프-바이-원 오류 (Boundary and Off-by-One Errors)
가장 흔한 '거의 맞는' 실패 유형입니다. 에이전트가 루프를 작성할 때 한 번 너무 많이 또는 너무 적게 반복하거나, API가 배타적 상한(exclusive upper bound)을 기대하는 곳에 포함적 상한(inclusive upper bound)으로 배열을 슬라이싱하는 경우 등이 있습니다. 리스트의 모든 항목을 처리하도록 요청받은 TypeScript 에이전트를 고려해 봅시다:
// Agent-generated: iterates one past the end
for (let i = 0; i <= items.length; i++) {
process(items[i]); // undefined on the final iteration
...
수정 방법은 단 하나의 문자입니다:
for (let i = 0; i < items.length; i++) {
process(items[i]);
}
왜 이런 일이 발생할까요? 모델의 훈련 분포는 루프 조건에서 <와 <= 사이에 거의 균등한 분배를 가지고 있습니다. 실행 시그널(runtime signal) — 예외(exception), 실패하는 단언문(failing assertion), 타입 에러(type error) — 없이는 디코더가 올바른 것을 선호할 방법이 없습니다. 모델은 더 확률 높은 토큰을 선택하며, 이 확률이 정확성을 의미하지는 않습니다.
1.2 API 오용 및 시그니처 드리프트 (API Misuse and Signature Drift)
에이전트들은 종종 올바른 이름의 함수를 잘못된 인자 순서로 호출하거나, 라이브러리의 이전 버전에서 존재했던 시그니처(signature)를 사용합니다. 고전적인 예시가 JavaScript의 Array.prototype.sort입니다. 이 메서드는 제자리에서 수정(mutates in place)하며 기본적으로 사전순으로 정렬합니다:
// 에이전트 생성: 숫자가 아닌 문자열로 정렬
const sorted = [...items].sort(); // [10, 2, 1] 대신 [1, 2, 10]
에이전트는 메서드 이름은 알았지만 의미론적(semantics)인 바는 몰랐습니다. 이를 수정하려면 비교자(comparator)가 필요합니다:
const sorted = [...items].sort((a, b) => a - b);
이것은 환각(hallucination)이 아닙니다 — 심볼 자체는 존재합니다. 이것은 의미론적 오류이며, 타입들이 정확하기 때문에 타입 검사기(type checker)가 포착하기 훨씬 어렵습니다.
1.3 조용한 논리 역전 (Silent Logical Inversions)
때때로 에이전트는 논리를 거꾸로 이해합니다. if (user.isActive)여야 할 조건이 if (!user.isActive)가 되거나, 비교 연산자가 <에서 >로 뒤바뀌는 경우입니다. 이러한 패턴은 컴파일되고(compile), 린트(lint)를 통과하며, 종종 동일한 잘못된 가정으로 작성된 단위 테스트(unit tests)까지 통과하기 때문에 가장 위험합니다.
1.4 불완전한 리팩터링 (Incomplete Refactors)
에이전트가 함수나 변수의 이름을 변경할 때, 정의와 즉각적인 호출 지점은 업데이트하지만 다른 모듈에 있는 먼 사용처를 놓치는 경우가 많습니다. 그 결과는 알 수 없는(cryptic) ReferenceError로 실패하거나, 에이전트가 전혀 건드리지 않은 파일을 가리키는 TypeScript 오류가 발생하는 빌드가 됩니다.
1.5 컨텍스트 누수 환각 (Context-Bleed Hallucinations)
가장 흔히 발견되는 실패 유형입니다. 에이전트가 주변 코드를 볼 때 그럴 것 같다고 느끼기 때문에 실제로 존재하지 않는 함수나 속성을 만들어냅니다. 예를 들어, 실제 속성이 user.name인데도 불구하고 user.fullName을 호출하거나, 모듈이 다른 경로에서 formatDate만 내보내는 경우에 utils/formatDate를 가져오려고 합니다. 모델은 거짓말을 하는 것이 아닙니다. 그저 훈련 과정에서 여러 번 본 패턴을 완성하는 것일 뿐이며, 이 패턴이 현재 코드베이스와 일치하지 않는 것입니다.
2. 내부 작동 원리로 본 근본적인 원인 (Root Causes Under the Hood)
이 다섯 가지 실패 모드는 무작위가 아닙니다. 이는 자기회귀 언어 모델(autoregressive language models)이 어떻게 훈련되고 디코딩되는지에 따른 직접적인 결과입니다.
2.1 토큰 샘플링과 '충분히 좋은' 디코딩 (Token Sampling and the Good Enough Decoding)
자기회귀 언어 모델은 어휘(vocabulary)에 대한 확률 분포에서 토큰을 하나씩 선택하며 코드를 생성합니다. 그리디 디코딩(greedy decoding)을 사용하면 모델은 항상 가장 높은 확률의 토큰을 선택합니다. top-p 또는 온도 샘플링(temperature sampling)을 사용하면 좁혀진 분포에서 선택합니다. 두 경우 모두, 모델은 테스트 스위트가 정의하는 *정확성(correctness)*이 아니라, 훈련 데이터를 기반으로 한 토큰 시퀀스의 가능성(plausibility)에 최적화하고 있습니다.
가능성은 정확성의 대리 지표(proxy)이며, 대부분의 경우 좋은 대리 지표입니다. 그러나 이 분포는 가능하지만 틀린 완성 패턴이 긴 꼬리(long tail)를 가지고 있습니다. 오프-바이-원(off-by-one)은 분포를 아주 약간만 변화시키는 토큰 하나 차이일 뿐입니다. 모델은 해당 토큰의 런타임 효과(runtime effect)를 볼 수 없기 때문에, 이 둘을 구별할 수 없습니다.
2.2 컨텍스트 창 절단(Context Window Truncation)과 어텐션 감쇠(Attention Decay)
모든 에이전트는 컨텍스트 창을 가지고 있습니다. 대화가 진행되면서 오래된 메시지는 잘리거나 압축됩니다. 세션 초반에 작성했던 명세(spec)는 에이전트가 구현 코드를 작성할 무렵에는 사라질 수 있습니다. 그러면 에이전트는 그 공백을 자신의 사전 지식(prior)—즉, 훈련 과정에서 가장 흔한 패턴—으로 채우게 되는데, 바로 이 부분이 '거의 맞는' 버그가 발생하는 정확한 지점입니다.
어텐션 디케이(Attention decay)가 이를 더욱 복잡하게 만듭니다. 스펙이 여전히 컨텍스트 내에 있더라도, 모델의 원거리 토큰에 대한 주의력은 근접한 토큰보다 약합니다. 8,000 토큰 전에 묻힌 요구사항은 두 줄 위에 있는 주석보다 다음 토큰에 미치는 영향이 적습니다.
2.3 학습 데이터 편향: 일반적인 패턴으로의 치우침
LLM은 공개 코드를 학습하는데, 이는 가장 흔한 관용구(idioms) 쪽으로 크게 치우쳐 있습니다. 모델은 for (let i = 0; i < arr.length; i++)가 오프-바이-원 변형보다 더 흔하다는 것을 배우지만, 동시에 <=가 실제 코드에서 자주 나타난다는 것도 배웁니다. 정답이 덜 일반적인 형태일 때, 모델은 더 일반적인 형태로 기울어집니다.
2.4 진실 기반 피드백 루프의 부재
이것이 가장 깊은 근본 원인입니다. 모델은 다음 토큰 예측 목표(next-token prediction objective)로 학습됩니다. 프로그램 실행을 해보거나, 스택 트레이스(stack trace)를 관찰하거나, 테스트 실패를 읽어본 적이 없습니다. 코드를 생성할 때, 그것은 코드가 무엇을 해야 하는지가 아니라 코드의 모양이 어떠해야 하는지에 대한 통계적 추측을 하고 있는 것입니다. 이 루프를 닫는 유일한 방법은 에이전트를 출력을 실행하고 그 결과를 다시 피드백하는 하네스(harness) 안에 넣는 것입니다.
2.5 국소 최적점으로서의 '거의 맞는' 코드
코딩 작업의 손실 지형(loss landscape)을 고려해 봅시다. 전역 최적점(global optimum)—즉, 올바르고 작동하는 코드—이 있고, 국소적으로 일관성 있는 거의 맞는 해결책들의 광대한 고원(plateau)이 있습니다. 이들은 컴파일되고, 기존 심볼을 참조하며, 코드베이스 스타일을 따릅니다. 에이전트의 샘플링 과정은 이러한 국소 최적점들을 쉽게 찾는데, 왜냐하면 그것들이 풍부하기 때문입니다. 전역 최적점은 희귀하고 개별적으로 확률이 낮은 정확한 토큰 선택을 요구합니다.
3. 디버깅 플레이북
일단 패턴을 인식했다면, 이를 격리하고 수정하기 위한 체계적인 방법이 필요합니다. 이것이 디버깅 플레이북입니다.
3.1 결정론적으로 재현하기
에이전트의 출력을 디버깅하기 전에, 실패가 재현 가능하도록 만들어야 합니다. 의존성(dependencies)을 고정하고, 잠금 파일(lockfile)을 동결하며, 모든 난수 생성기(random number generators)에 시드(seed)를 설정하고, 환경을 스냅샷합니다. 버그가 경쟁 조건(race condition)이거나 불안정한 테스트(flaky test)라면, 먼저 불안정성을 해결해야 합니다. 재현 자체가 비결정적(non-deterministic)이라면, 거의 맞는 패턴에 대해 추론할 수 없습니다.
3.2 프롬프트 이분 탐색(Bisect the Prompt)
대부분의 거의 맞는 버그는 특정 컨텍스트 조각에 의해 발생합니다. 이를 찾으려면, 대화 내용을 이분 탐색하세요. 마지막 N개의 메시지를 제거하고 다시 실행해 보세요. 만약 버그가 사라진다면, 문제가 되는 컨텍스트는 해당 메시지들에 있었습니다. 이는 검색 범위를 전체 세션에서 몇 번의 턴(turns)으로 좁혀주며, 종종 에이전트가 모순되는 지침이나 오래된 코드 스니펫에 의해 오도되었음을 밝혀줍니다.
3.3 diff 기반 포렌식 분석(Diff-Based Forensic Analysis)
에이전트가 대규모 변경 사항을 생성할 때, 이를 알려진 정상 기준선(known-good baseline)과 비교하세요. 이 차이점(diff)이 증거입니다. 사양(spec)의 변화 없이 변경된 줄들을 찾으세요. 그것들이 거의 맞는 후보들입니다. 루프 조건에서의 한 줄 변경, 재배열된 인자 목록(argument list), 뒤집힌 부울 값(boolean) 등은 코드 리뷰에서는 눈에 띄지 않지만, 이전 커밋 대비 diff를 사용하면 명확합니다.
3.4 테스트 주도 프롬프팅(Test-Driven Prompting)
가장 효과적인 단일 기술입니다: 에이전트에게 코드를 작성하도록 요청하기 전에, 실패하는 테스트를 먼저 작성하세요. 테스트는 참값 신호(ground-truth signal)입니다. 에이전트는 루프 내에서 실패하는 테스트를 보면 조정할 수 있습니다. 이것이 없다면, 에이전트는 <=가 잘못되었다는 것을 알 방법이 없습니다. 이는 섹션 2.4의 피드백 루프를 닫는 실질적인 버전입니다.
4. 패턴별 수정 방법(Pattern-Specific Fixes)
각 패턴은 서로 다른 종류의 도구링(tooling)에 가장 잘 반응합니다.
4.1 경계 오류 수정(Fixing Boundary Errors)
경계 오류는 속성 기반 테스트(property-based tests)로 가장 잘 포착됩니다. 단일 입력을 하드코딩하는 대신, 많은 입력에 대한 불변 조건(invariant)을 주장합니다. 여기 Hypothesis를 사용한 Python 예시가 있습니다:
from hypothesis import given, strategies as st
def process_items(items):
...
이 테스트는 생성된 리스트 중 적어도 하나에 대해 출력 길이가 입력 길이와 다르기 때문에 off-by-one 버전에서 실패할 것입니다.
4.2 API 오용 수정 (Fixing API Misuse)
API 오용은 라이브러리의 계약(contract)을 인코딩하는 타입 체커와 린터가 가장 잘 잡아냅니다. JavaScript의 경우 'strict' 모드를 활성화하고 @ts-check를 사용하세요. TypeScript의 경우 컴파일러가 이미 많은 시그니처 불일치(signature mismatches)를 잡아줍니다. sort 예시의 경우, 비교자(comparator)를 추가하고 인수가 없는 형태를 금지하는 린트 규칙을 적용하여 수정할 수 있습니다.
4.3 불완전한 리팩토링 수정 (Fixing Incomplete Refactors)
불완전한 리팩토링은 컴파일러나 전체 코드베이스 검색을 통해 잡아낼 수 있습니다. 에이전트 편집 후에는 항상 tsc --noEmit 또는 pyright를 실행하세요. 만약 에이전트가 호출 지점(call site)을 놓쳤다면, 타입 오류가 해당 파일을 명시할 것입니다. 수정 방법은 그 호출 지점을 수동으로 업데이트하는 것입니다. 에이전트에게 요청하지 마세요. 왜냐하면 에이전트는 동일한 불완전 패턴을 반복하기 때문입니다.
4.4 환각된 심볼 수정 (Fixing Hallucinated Symbols)
환각된 심볼은 정적 분석(static analysis)과 런타임 검사(runtime checks)를 통해 잡아낼 수 있습니다. ReferenceError 또는 ImportError가 가장 명확한 신호입니다. 수정 방법은 코드베이스에서 실제 심볼을 찾아 참조를 올바르게 하는 것입니다. 만약 해당 심볼이 실제로 존재하지 않는다면, 그것을 추가하거나 존재하는 것을 사용하도록 에이전트의 로직을 재작성해야 합니다.
5. 에이전트 루프 엔지니어링 (Engineering the Agent Loop)
위의 수정 방법들은 사후 대응적(reactive)입니다. '거의 맞는' 버그가 들어오는 것을 막으려면, 에이전트의 피드백 루프 자체를 엔지니어링해야 합니다.
5.1 프리 커밋 필터로서의 정적 분석 (Static Analysis as a Pre-Commit Filter)
코드베이스에 진입하기 전에 모든 에이전트 출력에 대해 전체 정적 분석 스위트를 실행하세요: ESLint, Prettier, tsc --noEmit, ruff, mypy. 이것은 사용하지 않는 임포트(unused imports), 잘못된 타입, 정의되지 않은 참조와 같은 기계적인 '거의 맞는' 패턴을 잡아내지만, 플립된 불리언 값과 같은 의미론적(semantic) 오류는 잡아내지 못합니다. 정적 분석을 마지막 단계가 아닌 첫 번째 관문으로 취급하세요.
5.2 속성 기반 테스트 (Property-Based Testing)
속성 기반 테스트(Property-based tests)는 단일 예제가 아닌 넓은 입력 공간에 걸쳐 불변성(invariants)을 확인하기 때문에 '거의 맞는' 패턴에 대한 가장 강력한 방어 수단입니다. 정렬, 페이지네이션, 날짜 계산(date math), 문자열 파싱 등 중요한 경로(critical paths)에 이를 추가하세요. 에이전트가 오프-바이-원(off-by-one) 오류로 인해 우연히 불변성을 만족시킬 수는 없습니다.
5.3 제약 디코딩 (Constrained Decoding)
일부 에이전트 프레임워크는 모델이 유효한 구문만을 출력하도록 강제하는 제약 디코딩(constrained decoding)—또는 문법 기반 생성(grammar-constrained generation)이라고도 함—을 사용합니다. Outlines나 Guidance 같은 도구들은 출력을 특정 문법이나 JSON 스키마로 제한합니다. 이는 구문 오류와 환각된 구조를 제거하지만, 의미론적 오류(semantic errors)는 제거하지 못합니다. 이는 필요하지만 불충분한 방어 장치입니다.
5.4 자체 일관성 및 다수결 투표 (Self-Consistency and Majority Voting)
에이전트에게 한 번만 요청하는 대신, 고정된 시드(fixed seed)와 다른 샘플링 온도(sampling temperatures)를 사용하여 N번 요청하세요. 출력들을 수집하고 가장 자주 나타나는 것을 선택합니다. '거의 맞는' 패턴은 보통 다양합니다—각 실행마다 다르게 실패합니다—반면 정답은 안정적입니다. 이는 비용이 많이 들지만, 실제 정답을 검증하는 실행기(ground-truth executor) 없이 정확도를 높이는 가장 신뢰할 수 있는 방법입니다.
6. 에이전트를 신뢰해야 할 때
다음 조건일 때 에이전트를 신뢰하세요: 작업이 작고 기계적이며, 코드베이스에 강력한 테스트와 타입 검사가 존재하고, 영향 범위(blast radius)가 단일 함수로 제한되며, diff를 빠르게 검토할 수 있을 때.