발표에서 확인된 핵심 사실

Agent-Blackbox는 Claude Code와 OpenCode의 실행 과정을 로컬에서 기록하고 분석하는 도구다. 세션 맵과 컨텍스트 효율 점수를 통해 AI 에이전트가 실제로 어떤 경로로 토큰을 소모하는지 시각화한다. AI가 예측한 사용량과 실제 청구 비용 사이의 괴리가 크다는 점에 주목해, 로컬 기록 기반의 정밀 추적 방식을 택했다.

oh-my-openagent나 oh-my-claudecode 같은 멀티 에이전트 하네스(여러 AI 에이전트를 제어하는 틀)와도 호환된다. 실행 시간이 길어질수록 누가 어떤 파일을 수정했는지, 어디서 작업 반복이 발생했는지 파악하기 힘든 지점을 눈으로 직접 확인해 비효율을 찾아낸다.

개발자는 기록된 이력을 통해 에이전트의 반복 실수와 토큰 낭비 지점을 구체적으로 식별할 수 있다. 이렇게 분석된 데이터는 CLAUDE.md 같은 설정 파일을 최적화하는 실무적 기준으로 활용되며, 불필요한 컨텍스트를 제거해 운영 비용을 낮추는 경로가 된다.

기술이 실제로 작동하는 방식

별도의 설치 과정 없이 `npx` 명령어로 즉시 실행한다. 모든 기록과 대시보드 동작이 사용자 로컬 환경에서 완결되므로 외부 서버로 데이터를 보내지 않으며, API key 입력 단계도 생략된다. 인프라 구축 비용 없이 에이전트의 동작을 즉각 추적할 수 있는 구조다.

수집 방식은 도구별 기록 체계에 맞춘다. Claude Code는 `~/.claude/projects transcript` 파일을 tailing(실시간으로 파일 끝부분을 읽는 방식)하여 데이터를 수집하고, OpenCode는 글로벌 플러그인을 통해 이벤트를 수신한다. 에이전트가 파일을 읽거나 bash 명령을 실행하는 실제 이벤트를 로컬에서 가로채 기록하는 방식이다.

컨텍스트 효율 분석은 구체적인 낭비 요소를 집어낸다. 동일 파일을 반복해서 읽거나, 수정량 대비 과도하게 많은 파일을 읽는 행위를 탐지한다. 큰 툴 출력값이 컨텍스트를 점유하거나 원인 수정 없이 실패한 명령을 반복하는 구간, 즉 토큰 소모는 많지만 코드 변경은 적은 지점을 찾아낸다. 프롬프트 캐시(Prompt Cache, 이전 입력값을 저장해 재사용하는 기술) 활용도가 낮은 지점도 함께 분석한다.

이 분석 결과는 `CLAUDE.md` 설정 파일 최적화의 직접적인 근거가 되어, 에이전트의 반복 실수를 줄이고 토큰 소모를 제어하는 기준이 된다.

확인해야 할 핵심 지점

Agent-Blackbox는 에이전트가 마지막에 내놓는 요약본을 파싱하지 않는다. 대신 시스템에서 실제로 발생한 개별 이벤트를 직접 기록해 에이전트의 주관적 요약이 아닌 실제 동작 궤적을 추적한다. 불투명한 비용 소모 지점을 정확히 찾아낼 수 있는 이유다.

기록 대상은 매우 구체적이다. 파일 읽기·수정 내역, bash 실행 결과와 종료 코드는 물론 검색 수행, todo 업데이트, 권한 요청, 서브에이전트 위임, 스킬 사용 내역까지 모두 수집한다. 모델과 토큰의 흐름뿐 아니라 실패 후 수정 및 재시도 과정까지 상세히 담아 낭비 요소를 분석하는 객관적 근거로 쓴다.

분석된 낭비 요소를 AGENTS.md 또는 CLAUDE.md(에이전트 동작 지침 설정 파일)에 관리 블록 형태로 기록하면 다음 실행의 효율이 올라간다. 실제 동일 작업과 모델로 재실행한 사례에서 토큰 사용량은 939k에서 521k로 줄었고, 효율 점수는 80에서 99로 상승했다. 기록된 데이터를 바탕으로 설정 파일을 최적화하는 조치가 직접적인 비용 절감으로 이어진 셈이다.

이제 AI 코딩 에이전트의 비용 관리는 모델의 지능에 맡기는 것이 아니라, 로컬 이벤트 기록을 통해 `CLAUDE.md`를 얼마나 정교하게 최적화하느냐의 문제로 바뀐다. 에이전트의 생산성은 결국 컨텍스트 관리 능력에서 결정된다.