당신의 코딩 에이전트(coding agent)가 방금 40단계의 실행을 마쳤는데 결과가 틀렸습니다. 당신은 누구나 하는 행동을 합니다. 트랜스크립트(transcript)를 열고 스크롤을 시작하는 것이죠. 20분 후, 당신은

자신의 에이전트 코드를 계측(Instrumenting)하는 것은 코드를 새로 쓰는 것이 아니라 데코레이터(decorator)를 추가하는 것입니다:

from langfuse import observe

@observe()
...

모든 호출은 스팬(span)이 되며, 실행 과정은 입력과 출력이 부착된 접기 가능한 트리(collapsible tree)가 됩니다. 이제 "중간 어디쯤"이라는 표현은 다음과 같이 바뀝니다: 14번째 단계에서 파일 읽기 도구(file-read tool)가 빈 문자열을 반환했고, 그 이후의 모든 단계는 로드되지 않은 파일에 대해 자신 있게 추론했습니다.

초기에 발생한 하나의 잘못된 도구 결과가 그 이후의 확신에 찬 헛소리로 이어지는 이 패턴은, 제가 목격하는 에이전트 실패 사례 중 가장 흔한 것입니다. 모델은 30번째 단계에서 갑자기 환각(hallucination)을 일으키는 것이 아닙니다. 14번째 단계에서 전달받은 거짓말을 충실히 확장하고 있는 것입니다. 첫 번째 잘못된 스팬(span)을 찾아 그 지점에서 읽기를 멈추세요. 수정 사항은 거의 항상 마지막 증상이 아니라 첫 번째 편차(divergence) 지점에 있어야 합니다.

3단계: 실패할 수 있는 체크(check)를 작성하세요

여기에 함정이 있습니다. 14번째 단계를 수정하고 다시 실행한 뒤, 출력을 훑어보고는 "맞아 보이네"라고 생각하는 것입니다. 그것은 느낌(vibe)일 뿐 검증(verification)이 아닙니다. 처음에 버그를 놓쳤던 것과 똑같은 방식의 훑어보기입니다.

"맞아 보인다"를 단언(assertion)으로 바꾸세요. promptfoo를 사용하면 이를 선언적(declarative)으로 만들 수 있습니다:

# promptfooconfig.yaml
prompts:
  - file://task-that-failed.md
...

또는 CI(지속적 통합) 환경이 pytest라면 그대로 유지해도 좋습니다. 중요한 것은 도구가 아니라, 체크가 기계적이고 반증 가능(falsifiable)해야 한다는 점입니다. 실패할 수 없는 체크는 단순한 장식에 불과합니다.

이러한 체크를 위한, 고생 끝에 얻은 두 가지 규칙입니다:

새로운 증거만 채점하세요. 저는 한때 이전 실행의 QA 아티팩트(artifacts)를 사용하여 실패를 "진단"하느라 한 시간을 허비한 적이 있습니다. 새로운 출력에 대해 오래된 스크린샷을 채점하면, 확신에 차고 상세하지만 완전히 틀린 진단이 나옵니다. 이제 모든 검증 스크립트는 자체 증거 디렉토리를 삭제하는 것으로 시작합니다:

rm -rf qa/ && mkdir qa/   # 오래된 증거는 증거가 없는 것보다 나쁩니다

실제 표면(surface)을 확인하세요. 만약 에이전트의 작업이 "페이지 렌더링"이었다면, HTML 파일이 존재하는지 확인하는 것은 잘못된 표면을 검사하는 것입니다. proofshot와 같은 도구들이 존재하는 이유가 바로 이것입니다. 브라우저를 기록하고, 스크린샷을 캡처하며, 에러를 묶어두는 것 말이죠. 왜냐하면 "파일이 디스크에 있다"는 것과 "그 기능이 작동한다"는 것은 서로 다른 주장이며, 에이전트는 두 번째를 실패하면서 첫 번째를 만족시키는 데 매우 능숙하기 때문입니다.

10분 요약 버전

에이전트 실행이 잘못되었을 때:

1. 고정하세요 (Pin it) — 작업을 파일로 만들고, 모델을 고정하며, 리포지토리(repo) 상태를 동결하고, 출력을 캡처하세요. 만약 재현되지 않는다면, 버그는 당신의 환경에 있는 것이며 그것 또한 하나의 발견입니다.
2. 추적하세요 (Trace it) — 데코레이터(decorator) 수준의 계측(instrumentation)을 수행하고, 트리를 읽어 첫 번째 잘못된 스팬(span)을 찾으세요. 그 이후의 모든 것은 무시하세요. 그것은 원인이 아니라 메아리일 뿐입니다.
3. 단언하세요 (Assert it) — "수정됨"을 실패할 수 있는 체크 항목으로 인코딩하고, 새로운 증거에 대해서만 등급을 매기며, 사용자가 실제로 접하는 표면을 확인하세요.

이 중 어느 것도 생소한 것이 아닙니다. 이것은 당신이 이미 알고 있는 디버깅을, 마침 대화가 가능한 런타임(runtime)에 적용하는 것뿐입니다. 코딩 에이전트로부터 일관된 가치를 얻어내는 팀들은 마법 같은 프롬프트를 가진 팀들이 아닙니다. 에이전트의 출력을 단순히 읽는 것이 아니라, 테스트하는 것으로 취급하기 시작한 팀들입니다.

에이전트는 당신에게 거짓말을 하고 있는 것이 아닙니다. 당신이 에이전트가 본 것을 보지 못했을 뿐입니다. 먼저 스스로에게 눈을 부여하세요. 해결책은 보통 하나의 잘못된 스팬(span) 뒤에 있습니다.