AI 에이전트 디버깅: 당신의 대시보드는 비용은 알지만 원인은 모른다

AI 에이전트 디버깅은 옵저버빌리티 대시보드가 끝나는 지점에서 시작됩니다. AI 코딩 에이전트가 무언가를 망가뜨렸는데 실행이 이미 종료된 경우, 대시보드는 실행 비용(토큰, 달러, 지연 시간)을 알려줄 수 있을 뿐, 여러분이 실제로 갖는 유일한 질문인 "에이전트는 왜 그 파일을 변경했는가?"에는 침묵합니다. 이에 답하는 산출물은 열고 읽고 재생할 수 있는 기록된 트레이스입니다. 트레이스는 실행을 외부에서 설명하는 대신, 그 실행 자체를 여러분에게 돌려주기 때문입니다.

에이전트가 실제 작업을 수행하기 시작한 순간부터 이것은 더 이상 드문 일이 아니게 되었다. 에이전트 하나가 리포지토리를 훑고, 여러 파일을 수정하고, 검사를 실행하고, 성공을 보고한다. 그 모든 일은 당신이 몇 분 간격으로 입력한 두 프롬프트 사이에서 일어난다. 그 수정 중 하나가 잘못되었다면, 당신은 나중에야 알게 된다. 터미널이 닫힌 뒤, 스크롤백이 사라진 뒤, 스스로 설명할 수 있었던 프로세스가 종료된 뒤에 말이다. 그다음에 벌어질 일은 전적으로 당신이 무엇을 보관했느냐에 달려 있다. 그 답이 비용 대시보드라면, 당신이 하게 될 일은 고고학이다. 그 답이 녹화 기록이라면, 당신이 하게 될 일은 읽기다.

재현할 수 없는 실패

대략 이런 상황입니다. 리포지토리에 돌아와 보면, 아무에게도 건드리라고 요청한 적 없는 파일이 다시 쓰여 있거나, 삭제되어 있거나, 다른 모든 코드가 의존하는 함수가 비워져 있습니다. 에이전트에게 무슨 일이 있었는지 물어보지만 세션은 이미 종료되어 있고, 기록이 남아 있는 경우에도 에이전트가 자신의 실행 과정에 대해 설명하는 내용은 녹화된 것이 아니라 재구성된 것입니다. 그래서 당연히 다시 실행해 보지만, 이번에는 다른 실행이 됩니다. 도구 호출도 다르고, 편집 내용도 다르며, 어쩌면 전혀 실패하지 않을 수도 있습니다. 원래의 실행 궤적이 샘플링, 리포지토리의 상태, 타이밍에 의존했기 때문입니다. 조사해야 할 바로 그 실행은 더 이상 존재하지 않습니다.

재현 불가능한 것보다 더 나쁩니다. 재현 불가능하면서도 성공으로 표시됩니다. 에이전트가 0으로 종료하면 실행도 0으로 종료되는데, 실행 내부의 검사가 1로 종료되었더라도 그렇습니다. 즉, 실행 내부의 검증 단계가 실패했는데도 파이프라인이 초록색일 수 있고, 자연스럽게 신뢰하게 되는 종료 코드는 아무것도 말해주지 않습니다.

라우터가 실행에 어떤 모델을 선택했는지는 중요하지 않습니다(GLM 5.3 Flash든 다른 것이든). 프로세스가 종료되면 추론 과정도 함께 사라집니다. 증거는 실행이 진행되는 동안에만 존재했습니다: 프롬프트, 도구 호출, 출력, 차이점(diffs) 등입니다. 아무것도 기록하지 않았다면, "왜 그 파일을 변경했는가"에 대한 답은 없습니다. 오직 이론만 있을 뿐입니다.

이것이 바로 AI 코딩 에이전트를 이전의 모든 도구와 구분 짓는 실패 모드입니다. 즉, 피해와 설명이 같은 장소에서 발생하며, 그 장소는 닫힙니다.

대시보드는 무엇을 측정하며, 무엇을 건너뛰는가?

실패한 실행 이후의 본능은 옵저버빌리티 대시보드를 여는 것이다. 그리고 대시보드는 실제로 그 역할을 훌륭히 해낼 것이다. 그 역할은 트래픽을 보여주는 것이다: 일일 토큰 수, 모델별 비용, 지연 시간, 오류율. 용량 계획과 청구에는 이것이 정확히 맞는 도구이며, 프로덕션에서 에이전트를 운영한다면 대시보드를 열어 두어야 한다.

하지만 당신의 질문은 집계적이지 않습니다. 그것은 개별적이고 인과적입니다. 왜 이번 실행이 이 파일을 변경했는가? 집계는 바로 그 질문에 답하는 세부 수준을 건너뜁니다. 여러 실행에 걸쳐 평균을 내면, 당신이 관심을 갖는 그 실행은 잡음이 됩니다. 그 실행 안에서도 당신이 관심을 갖는 도구 호출은 다시 잡음이 됩니다.

대시보드는 실행을 외부에서 서술한다. 즉, 그것이 일어났다는 것, 그것의 무게가 어떠했는지, 그것의 비용이 어떠했는지를 보여 준다. 대시보드는 실행 자체를 당신에게 건네줄 수 없으며, '왜'는 서술의 속성이 아니다. '왜'는 순서의 속성이다.

실행 비용은? — 비용 대시보드로 확인 vs 기록된 트레이스로 확인

• 에이전트가 그 파일을 변경한 이유는? — 비용 대시보드 답변 없음 vs 기록된 트레이스 순서대로의 편집 및 해당 diff

• 그린 실행에서 실패한 검사는 무엇인가? — 비용 대시보드: 응답 없음 vs 기록된 트레이스. 해당 검사와 그 종료 코드.

• 정확한 실패를 다시 실행할 수 있나요? — 비용 대시보드: 아니요 vs 기록된 추적: 예, 오프라인에서 무료로

그것에 답하는 계층은 바로 그 아래에 있습니다: 기록된 요청 로그— 실행이 진행되는 동안 캡처되어, 전송된 모든 프롬프트와 실행된 모든 도구 호출, 반환된 모든 응답이 순서대로 담겨 있습니다. 실행의 요약이 아니라 실행 그 자체입니다.

하나의 실행을 타임라인으로 읽기

녹화물이 있으면 디버깅은 고고학이 아니라 독서가 된다. 고고학은 녹화물 없이 하는 일이다: git reflog, 스태시 항목, 셸 히스토리, 그리고 그날 일찍 당신이 요청했던 것에 대한 자신의 기억. 독서는 녹화물이 있을 때 하는 일이다: 타임라인을 열고 스크롤하는 것.

타임라인은 실행 과정을 일어난 순서 그대로 보여준다. 그것을 시작한 프롬프트, 각 도구 호출, diff가 포함된 각 파일 편집, 각 검사, 각 종료 코드까지. 파일 시스템 스냅샷은 도구 호출마다가 아니라 턴마다 한 번씩 찍히는데, 이는 대화의 각 단계에서 저장소 상태를 확인하기에 충분하면서도 호출별 잡음에 파묻히지 않게 한다. 이것을 브라우징이 아니라 디버깅이 되게 하는 것은 인접성이다. 편집과 그걸 잡아낸 검사가 순서대로 서로 나란히 놓여 있으며, 그 사이에는 추측할 것이 아무것도 없다. "왜"는 대부분 인접성의 속성이다.

기록된 픽스에서 읽어낸 구체적인 예로는, +1 -3으로 출력된 파일 변경과 종료 코드 1로 실패한 검사를 포함한 14개의 이벤트가 있습니다. 그 기록에서 편집과 그로 인해 실패한 검사는 인접해 있습니다. 이것이 바로 조각에서 실행을 재구성하는 것과 실행 하나를 읽는 것 사이의 차이의 전부입니다. 이는 터미널 코딩 에이전트에게 가장 중요합니다. 이들의 작업 공간은 작업이 끝나는 순간 닫히는 터미널이므로, 타임라인은 살아남는 스크롤백입니다.

기록 또는 추론: 트레이스가 아는 것과 자체적으로 알아낸 것의 차이

타임라인은 어떤 일이 어떤 순서로 일어났는지 알려줍니다. 인과 그래프는 무엇이 무엇을 초래했는지 알려주며, 이 둘 사이의 간극이 바로 신뢰가 쌓여야 하는 지점입니다.

그래프는 이벤트들을 연결합니다: 이 편집, 그다음 이 실패한 검사. 그 간선들 중 일부는 기록된 사실입니다. diff를 생성한 도구 호출이 트레이스에 그대로 있습니다. 다른 간선들은 추론된 것입니다. 검사가 그 diff 때문에 실패했다는 그래프의 결론입니다. orca graph는 모든 간선을 recorded 또는 inferred로 표시하고, 어느 쪽이든 사용한 규칙을 밝힙니다. 따라서 여러분은 자신이 보고 있는 것이 실행에서 수행된 것인지, 아니면 도구가 그 실행에 대해 알아낸 것인지 항상 알 수 있습니다.

그 구분은 이상이 아니라 강제됩니다. 추론된 엣지는 트레이스에 다시 기록되지 않습니다. 트레이스는 일어난 일에 대한 충실한 기록으로 남고, 추론은 그 위에 얹힌 뷰로서 살펴보고 의문을 제기하고 동의하지 않을 수 있습니다. 둘 이상의 에이전트가 관여할 때 이 점이 가장 중요합니다. 리팩터 에이전트와 테스트 작성 에이전트가 같은 파일을 수정할 때, "어느 에이전트가 이 변경을 일으켰는가"가 바로 그 질문이며, 멀티 에이전트 귀인은 그 질문에 답하기 위해 존재합니다. 추론에서 사실로 조용히 승격되는 엣지는 실행 대신 이야기를 디버깅하게 되는 방식입니다.

원하는 만큼 자주 무료로 복제할 수 있습니다.

읽기는 설명한다. 재실행은 증명한다. 일단 가설을 세우면(편집이 리셋 호출을 제거해서 검사가 실패했다는 가설), 다시 실행해 그 일이 실제로 일어나는 것을 지켜보고 싶어진다. 라이브 에이전트를 재실행하는 것은 새로운 궤적과 새로운 비용을 치르는 일이다.

녹음을 재생하면 동일한 실행이 보장됩니다. 재생 실행은 네트워크가 차단된 상태로 진행되므로 토큰 비용이 들지 않고 변동도 없습니다. 매번 동일한 이벤트, 오프라인으로 발생합니다. 이 속성이 에이전트 디버깅을 도박에서 엔지니어링으로 바꿔 놓습니다. 실패가 결정론적이 되고, 결정론적 실패는 수정되기 때문입니다.

이 도구 역시 블랙박스가 아닙니다.OrcaReplay는 Apache-2.0 라이선스로 공개된 오픈소스이며, 트레이스 형식은 CC BY 4.0이므로 누구든 이를 다시 구현할 수 있습니다. 따라서 여러분의 녹화물도 저희의 녹화물도 독점 형식에 얽매이지 않습니다. 또한 이 도구는 시연용이 아니라 실제 테스트로 검증됩니다. Node 20과 Node 22에서 1393개의 테스트가 실행됩니다. 팀의 실행 기록을 이 도구에 맡기기 전에, 소스 코드를 읽고 형식을 확인한 뒤 테스트 스위트를 직접 실행해 볼 수 있습니다.

핵심 요점

대시보드는 청구서다. 기록된 트레이스는 실행이다. AI 에이전트 디버깅 계획이 비용 대시보드에서 끝난다면, 당신에게는 디버깅 계획이 없다: 당신에게는 청구 시스템이 있다. 대시보드는 항상 실행 비용이 얼마인지 알려줄 수 있지만, 에이전트가 왜 당신의 파일을 삭제했는지는 절대 알려줄 수 없다. "왜"라는 답은 시퀀스 속에 살아 있으며, 시퀀스는 당신이 그것을 보관했을 때만 존재하기 때문이다.

전체 방법은 네 단계로 구성됩니다:

• 실행을 기록하세요.

• 타임라인을 읽으세요.

• 그래프의 간선을 확인하세요.

• 두려운 것들은 원하는 만큼 무료로 다시 재생해 보세요.

출처 참고: 이 글의 모든 수치는 벤더가 보고한 것으로, 자체 제품 및 OrcaReplay 저장소와 해당 문서에서 비롯되었습니다: 실행의 exit-code 동작, +1 -3 diff와 exit-1 검사를 포함하는 14개 이벤트 기록 픽스, orca graph의 엣지 레이블링, 턴당 한 번의 스냅샷 주기, 네트워크 차단 상태의 오프라인 리플레이, Node 20과 Node 22에서의 1393개 테스트 스위트. 이 글에서는 제3자 측정 수치를 어디에서도 인용하지 않았습니다. 1393개 테스트 스위트만이 저장소를 클론하고 실행하여 직접 검증할 수 있는 주장입니다. 모든 항목은 2026-09-04에 마지막으로 확인되었습니다.