AI Agent에 문제가 생겼을 때 최종 답변만 보지 마세요: 요청 단위 디버깅(Request-level Debugging)의 사고방식

지난 2년 동안 AI 프로그래밍 도구는 매우 빠르게 변화했습니다.

Copilot 방식의 코드 완성(Code Completion)부터 Claude Code, Codex, OpenCode, Cursor, Cline과 같은 Agent 도구에 이르기까지, AI는 이제 단순히 "코드 몇 줄을 도와주는 것"에 그치지 않습니다. 프로젝트를 읽고, 파일을 수정하며, 명령어를 실행하고, 도구(Tool)를 호출하며, 에러를 분석한 뒤 다음 단계로 넘어갈 수 있습니다.

하지만 Agent가 "일을 할 줄 아는 사람"과 닮아갈수록 문제도 명확해집니다.

그것이 오류를 범할 때, 당신은 그것이 정확히 어디에서 틀렸는지 판단하기 매우 어렵습니다.

많은 사람이 AI 프로그래밍 도구가 엇나가는 것을 경험할 때, 가장 먼저 떠올리는 반응은 프롬프트(Prompt)를 수정하는 것입니다.

예를 들면 다음과 같습니다:

좀 더 진지하게 임해줘.
게으름 피우지 마.
반드시 코드를 먼저 읽고 수정해.
관련 없는 파일을 함부로 수정하지 마.

이러한 지시사항들이 때로는 도움이 되기도 하지만, 대부분의 경우 문제를 뒤로 미루는 것에 불과합니다.

왜냐하면 진짜 문제는 당신이 작성한 그 문장 안에 있는 것이 아니라, 그것이 실제로 모델(Model)에 보낸 전체 요청(Request) 안에 있을 수 있기 때문입니다.

왜 최종 답변만 보는 것으로는 부족할까요?

AI Agent가 작업을 완료하는 것은 보통 단 한 번의 요청으로 끝나지 않습니다.

그 프로세스는 다음과 같습니다:

사용자가 작업 제안
-> 모델이 system prompt, 컨텍스트(Context), 도구 목록을 수신
-> 모델이 특정 도구 호출을 결정
...

우리가 터미널이나 에디터에서 보는 것은 대개 이 과정의 아주 작은 부분일 뿐입니다.

최종 답변은 "그것이 무엇을 했는지"는 알려줄 수 있지만, "왜 그렇게 했는지"는 알려주기 어렵습니다.

예를 들어, 아래와 같은 문제들은 최종 답변만 봐서는 거의 파악할 수 없습니다:

• 핵심 파일을 실제로 확인했는가?
• 확인한 내용이 전체 컨텍스트인가, 아니면 잘려나간(Truncated) 컨텍스트인가?
• system prompt의 특정 규칙이 영향을 미쳤는가?
• 도구 스키마(Tool Schema)가 불분명하여 도구를 잘못 선택했는가?
• tool result가 다음 라운드로 전달되었는가?
• 어느 라운드부터 토큰(Token)이 폭증하기 시작했는가?
• Provider가 반환한 400 에러가 모델의 문제인가, 아니면 요청 형식의 문제인가?
• 매 라운드마다 대량의 무효한 컨텍스트를 반복해서 포함하고 있는가?

이 모든 것이 "요청 단위 문제(Request-level issues)"에 해당합니다.

AI Agent의 흔한 문제, 사실 계층별로 나누어 볼 수 있습니다

저는 이제 AI Agent의 문제를 단순히 "모델 성능이 안 좋다"라고 뭉뚱그려 말하기보다, 몇 가지 계층으로 나누어 보는 것을 선호합니다.

제1계층: 모델이 봐야 할 것을 보지 못함

가장 흔한 문제 중 하나입니다.

당신은 Agent가 특정 파일을 읽었다고 생각하지만, 실제로 모델에 전달된 요청에는 해당 내용이 포함되어 있지 않을 수 있습니다. 혹은 읽었더라도 후속 요청에서 유지되지 않았을 수도 있습니다.

결국 모델은 불완전한 컨텍스트를 기반으로 판단하게 되고, 결과는 당연히 불안정해집니다.

이럴 때 "코드를 주의 깊게 읽어줘"라고 계속 강조하는 것은 큰 의미가 없습니다. 당신이 진짜 확인해야 할 것은 다음과 같습니다:

핵심 컨텍스트가 다음 라운드 요청에 포함되었는가?

제2계층: 도구 목록 또는 도구 설명의 문제

Agent가 도구를 호출할 수 있다고 해서, 도구를 올바르게 호출한다는 뜻은 아닙니다.

모델은 도구 이름, 설명, 파라미터 구조를 포함한 도구 스키마(Tool Schema) 세트를 봅니다.

도구 설명이 너무 모호하면 모델은 언제 사용해야 할지 모를 수 있습니다. 파라미터 구조가 너무 복잡하면 모델이 잘못된 파라미터를 생성할 수 있습니다. 도구가 너무 많으면 모델이 잘못 선택할 수도 있습니다.

이러한 문제는 MCP, 플러그인, 서브 태스크(Sub-task) 도구가 점점 많아질수록 더 뚜렷해집니다.

제3계층: tool call과 tool result가 제대로 폐쇄 루프(Closed-loop)를 형성하지 못함

정상적인 도구 호출 루프는 다음과 같아야 합니다:

assistant: tool_use
tool: tool_result
assistant: tool_result에 근거하여 계속 진행

만약 중간 단계가 누락되면 Agent는 이상한 행동을 하기 시작합니다.

예를 들어:

• 도구가 실제로 실행되지 않았는데 모델은 실행되었다고 믿는 경우
• tool result가 너무 길어서 다음 라운드 진행 시 컨텍스트를 오염시키는 경우
• 여러 개의 tool_result 순서가 뒤바뀐 경우
• tool_use와 tool_result가 올바르게 매칭되지 않는 경우
• Provider가 요구하는 메시지 형식과 클라이언트가 저장하는 형식이 일치하지 않는 경우

이러한 버그는 육안으로 최종 답변만 보고 판단하기 가장 어렵습니다.

당신은 반드시 실제 요청(Request)과 응답(Response)을 확인해야 합니다.

제4계층: 토큰 및 비용 문제

많은 사람이 AI 프로그래밍 도구를 사용할 때 처음에는 효과에만 집중합니다.

하지만 사용 빈도가 높아지면 토큰 비용이 실제적인 문제가 됩니다.

특히 Agent 시나리오에서는 토큰이 최종 답변에만 소비되지 않습니다.

대량의 토큰은 다음과 같은 곳에서 소비될 수 있습니다:

• system prompt
• 도구 스키마 (Tool Schema)
• 히스토리 메시지 (History Messages)
• 파일 내용
• 검색 결과
• 명령어 출력
• tool result
• 서브 Agent의 컨텍스트

때때로 한 번의 작업이 비싼 이유는 최종 답변이 길어서가 아니라, 특정 라운드의 요청에 거대한 컨텍스트가 포함되었기 때문입니다.

따라서 세션(Session)의 총비용만 보는 것으로는 부족하며, 가급적 매 요청마다의 토큰 사용량을 확인할 수 있어야 합니다.

요청 단위 디버깅 시 무엇을 봐야 할까요?

AI Agent가 엇나갈 때, 저는 보통 다음 유형의 정보들을 먼저 살펴봅니다.

1. system prompt

system prompt는 Agent 행동의 근본적인 제약 조건입니다.

“모델이 스스로 결정한” 것처럼 보이는 많은 행동들은 사실 system prompt의 영향을 받은 것입니다.

예를 들어:

• 왜 항상 계획을 먼저 세울까?
• 왜 명령을 직접 실행하지 않을까?
• 왜 특정 유형의 파일은 수정하지 않을까?
• 왜 반복해서 확인을 요청할까?

이 모든 것들이 system prompt와 관련이 있을 수 있습니다.

2. messages

messages는 모델이 현재 무엇을 볼 수 있는지를 결정합니다.

중요한 것은 “이 Agent가 과거에 무엇을 읽었는가”가 아니라, 다음과 같습니다:

현재 이 라운드의 요청(request)에 실제로 무엇이 포함되어 있는가?

이 두 질문은 서로 다릅니다.

Agent가 로컬에서 파일을 읽었다고 해서, 이후의 모든 모델 요청(model request)에 해당 파일이 포함되어 있다는 뜻은 아닙니다.

3. tools schema

만약 Agent가 당신이 기대한 도구(tool)를 호출하지 않는다면, 모델을 탓하기 전에 먼저 확인해 보세요.

• 도구가 실제로 tools 목록에 포함되어 있는가?
• 도구 설명(description)이 명확한가?
• 파라미터 schema가 합리적인가?
• 모델을 혼란스럽게 만드는 유사한 도구가 여러 개 있지는 않은가?
• provider가 해당 schema를 지원하는가?

4. tool call / tool result

이 단계는 Agent가 왜 잘못된 행동을 했는지 파악하기에 가장 적합합니다.

다음 사항들을 확인할 수 있습니다:

• 모델이 어떤 도구를 선택했는가
• 어떤 파라미터를 전달했는가
• 도구가 무엇을 반환했는가
• 반환 결과가 다음 라운드로 전달되었는가
• 다음 라운드의 모델이 이 결과를 바탕으로 동작을 이어갔는가

여기서 흐름이 끊긴다면, 이후에 prompt를 아무리 조정해도 결과는 불안정할 것입니다.

5. token / cache / cost / latency

이 지표들은 문제가 어느 라운드에서 발생했는지 판단하는 데 도움을 줍니다.

예를 들어:

• 어느 라운드에서 input token이 갑자기 급증했는가?
• 어느 라운드에서 tool result가 유독 큰가?
• cache가 적중(hit)했는가?
• 어떤 모델이 가장 비용이 많이 드는가?
• 어떤 요청의 지연 시간(latency)이 가장 높은가?
• 실패한 요청에 usage 정보가 포함되어 있는가?

이는 단순히 “오늘 돈을 얼마나 썼나”를 보는 것보다 훨씬 유용합니다.

ccglass는 바로 이 단계를 해결합니다

최근 저는 ccglass라는 오픈소스 도구를 발견했습니다.

프로젝트 주소:
https://github.com/jianshuo/ccglass

이것은 또 다른 AI 프로그래밍 어시스턴트가 아니라, 로컬 관측(observability) 도구입니다.

간단히 말해, 로컬에 프록시와 Dashboard를 실행하여 Claude Code, Codex, OpenCode, CodeBuddy, Qoder 등의 도구가 실제로 모델에게 보내는 요청을 볼 수 있게 해줍니다.

다음 항목들을 확인할 수 있습니다:

• system prompt
• messages
• tools schema
• tool calls
• tool results
• request / response body
• token / cache / cost
• latency
• turn-to-turn diff

즉, 이 도구의 목적은 “코드를 대신 작성해 주는 것”이 아니라, “Agent가 실제로 어떻게 작동하는지 명확히 보여주는 것”입니다.

전형적인 사용 시나리오

당신이 Claude Code에게 버그 수정을 요청했다고 가정해 봅시다.

결과적으로 코드는 수정되었지만, 수정 방식이 매우 이상하다고 느껴질 수 있습니다.

이때 성급하게 다시 실행하기보다, ccglass를 열어 다음 사항들을 확인해 보세요:

1. 첫 번째 요청에 관련 파일이 포함되었는가?
2. system prompt가 수정 전략에 영향을 미쳤는가?
3. 어떤 도구들을 호출했는가?
4. 각 도구가 무엇을 반환했는가?
5. 어떤 tool result가 다음 라운드로 넘어갔는가?
6. 코드를 수정하기 전, 모델이 실제로 테스트 실패 정보를 확인했는가?
7. 특정 라운드에서 token이 갑자기 폭증하지는 않았는가?

이 질문들에 답할 수 있다면, Agent 디버깅은 “느낌상 이상하다”에서 “증거 체인(evidence chain)이 잘못되었다”로 바뀝니다.

일반적인 패킷 캡처(packet capture) 도구와 무엇이 다른가요?

많은 분들이 질문할 것입니다: “Charles, mitmproxy, Proxyman으로도 할 수 있는 것 아닌가요?”

어떤 경우에는 가능하지만, AI 프로그래밍 Agent에는 몇 가지 까다로운 점이 있습니다:

• 반드시 시스템 프록시를 따르지 않을 수 있음
• 일부 클라이언트는 커스텀 base URL을 사용함
• 일부는 OpenAI / Anthropic 호환 인터페이스를 사용함
• 일부 provider는 streaming 형식이 다름
• 일부 도구 호출 정보는 단순 HTTP 패킷이 아니라 Agent의 의미론적(semantic) 구조에 맞춰 보여줄 필요가 있음

ccglass의 목표는 범용 패킷 캡처 도구를 대체하는 것이 아니라, AI Agent 요청 구조를 전문적으로 시각화하는 것입니다.

이 도구는 system, messages, tools, tool call, tool result, usage, cost, diff 등을 Agent 디버깅에 최적화된 뷰(view)로 정리하여 보여줍니다.

왜 이 작업이 점점 더 중요해질 것이라고 생각하는가?

AI 프로그래밍 도구의 발전 방향은 명확합니다: Agent는 점점 더 자동화될 것입니다.

그들은 더 많은 파일을 읽고, 더 많은 도구 (tool)를 호출하며, 더 긴 작업을 수행하고, 심지어 하위 에이전트 (sub-agent)를 스케줄링할 것입니다.

이는 당연히 효율성을 높여줄 것입니다.

하지만 관측 능력 (observability)이 없다면, 복잡성 또한 함께 상승할 것입니다.

앞으로 우리가 마주하게 될 문제는 더 이상 다음과 같지 않을 것입니다:

이 코드 보완이 올바르게 되었는가?

대신 다음과 같을 것입니다:

왜 이 에이전트 (Agent)가 7번째 라운드에서 이 도구를 호출했는가?
왜 이 도구 결과 (tool result)를 이후 12번의 라운드까지 끌고 갔는가?
왜 이번 작업에 30만 토큰 (token)이 소모되었는가?
왜 동일한 작업임에도 프로바이더 (provider)를 바꾸니 실패하는가?
왜 컨텍스트 압축 (context compression) 후에 핵심 제약 사항을 놓쳤는가?

이러한 문제들은 모두 요청 단위 (request-level)의 시각을 필요로 합니다.

결론

저는 AI 프로그래밍 도구의 향후 중요한 방향이 단순히 에이전트 (Agent)를 더 강력하게 만드는 것뿐만 아니라, 에이전트를 더 관측 가능하게 (observable) 만드는 것이라고 생각합니다.

최종 답변만 보는 것은 프로그램이 충돌한 후의 마지막 로그 한 줄만 보는 것과 같습니다.

복잡한 시스템을 진정으로 디버깅하려면 입력, 출력, 중간 상태, 그리고 호출 체인 (call chain)을 살펴봐야 합니다.

AI 에이전트 (AI Agent) 역시 마찬가지입니다.

만약 여러분도 Claude Code, Codex, OpenCode, CodeBuddy, Qoder와 같은 도구들을 사용하고 있다면, ccglass를 사용해 보세요:

https://github.com/jianshuo/ccglass

이 도구가 해결하고자 하는 것은 "AI를 더 똑똑하게 만드는 것"이 아니라, 사용자가 다음과 같은 사실을 더 명확하게 알 수 있도록 하는 것입니다:

AI가 정확히 무엇을 보았으며, 무엇을 근거로 다음 단계로 나아갔는가.