Agent-Blackbox - 코딩 에이전트의 블랙박스를 열어 토큰 낭비를 줄이다

2026년 6월 현재, Claude Code나 OpenCode를 길게 돌리고 나면 "토큰을 얼마나 썼을까?"라는 질문에 대한 답은 에이전트의 마지막 요약 안에 있을 거라 기대하기 쉽다. 하지만 8개 최첨단 모델을 SWE-bench Verified로 평가한 2026년 연구(Bai et al., arXiv:2604.22750)에 따르면, 모델이 자기 토큰 사용량을 예측한 값과 실제 비용의 상관관계는 단 0.39에 불과하고 체계적으로 과소평가한다. 같은 작업, 같은 모델이라도 실행별로 토큰이 30배까지 차이 난다.

그 빈자리를 채우려는 도구가 Agent-Blackbox다. 로컬에서 동작하는 플라이트 레코더이자 컨텍스트 효율 프로파일러로, 에이전트가 "한 말"이 아니라 "한 일"을 기록한다. 이번 글에서는 TaewoooPark가 만든 이 도구를 직접 시퀀스 맵과 효율 점수 측면에서 정리한다.

• --

Agent-Blackbox가 해결하는 문제: 왜 토큰이 폭발하는가

에이전틱 코딩은 일반 코딩 대비 약 1000배 많은 토큰을 소모한다. 그중 대부분이 입력 컨텍스트다. 마지막 요약만 보면 "성공적으로 끝났다"는 깔끔한 그림이 나오지만, 실제로는 다음이 누적된다.

• 같은 파일을 반복해서 다시 읽음
• 수정량에 비해 너무 많은 파일을 읽음
• 거대한 command/tool 출력이 컨텍스트를 점거
• 실패한 명령을 원인 수정 없이 재실행
• 토큰은 많이 썼는데 실제 변경은 적음
• prompt cache 활용도가 낮음

이런 낭비를 다음 실행으로 넘기지 않고 "관측 → 진단 → 기록 → 측정 → 효과 없으면 롤백" 루프로 묶는 것이 Agent-Blackbox의 핵심 설계다.

• --

한 줄 설치: npx로 즉시 실행

설치 단계는 없다. Node 20+ 환경에서 아래 명령 중 하나만 실행하면 데몬이 뜨고 대시보드(http://127.0.0.1:5173/)가 열린다.

# Claude Code만 기록 — ~/.claude/projects JSONL transcript를 tail
npx @taewooopark/agent-blackbox up --host claude-code

# OpenCode만 기록 — 글로벌 플러그인으로 이벤트 수신
npx @taewooopark/agent-blackbox up

# 둘 다 한 대시보드로 통합
npx @taewooopark/agent-blackbox up --host all

기존 방식으로 Claude Code나 OpenCode를 그대로 쓰면 맵이 실시간으로 채워진다. 종료는 npx @taewooopark/agent-blackbox uninstall.

자주 쓰는 레시피

# Claude Code만 보고 싶을 때
npx @taewooopark/agent-blackbox up --host claude-code
claude

# 둘 다 + 무료 로컬 모델 제안(--suggest free: OpenCode Zen + Ollama + 로컬 자동 로테이션)
npx @taewooopark/agent-blackbox up --host all --suggest free

# 멀티 에이전트 위임 — 각 subagent가 자체 lane으로 분기
claude "Delegate exploration, implementation, and tests to subagents, then summarize."

# 포트 충돌 회피 (47831/5173이 점유당했을 때)
npx @taewooopark/agent-blackbox up --host claude-code --port 48000 --ui-port 4000

• --

무엇을 보는가: 트랜스크립트가 아니라 세션 맵

스크롤하는 선형 로그와 "마지막 요약"만으로는 "이 에이전트가 무엇을 했는지" 알기 어렵다. Agent-Blackbox는 관측된 이벤트에서 재구성한 세션 맵을 실시간으로 그린다.

| 일반 트랜스크립트 | Agent-Blackbox |

|---|---|

| 스크롤하는 선형 로그 | 한눈에 읽는 세션 맵 |

| 에이전트 요약을 신뢰 | 관측 이벤트에서 재구성 |

| "테스트 통과" | fail → fix → pass 흐름 가시화 |

| 긴 실행에서 흐름 손실 | 임의 시점으로 스크럽·리플레이 |

| 불투명한 한 에이전트 | 서브에이전트 계보 — 누가 누구에게 위임했는가 |

| 비용 알 수 없음 | 컨텍스트 효율 점수 + 회수 가능 토큰 |

| 재개를 위해 다시 읽음 | 원클릭 핸드오프 요약 |

| 코드와 프롬프트가 기기를 떠남 | 로컬 우선, 최소 캡처, API 키 불필요 |

지도는 작업 중에 만들어진다. 리프레시도, 리플레이도 필요 없다. 노드 한 개가 등장하고, 파일이 호선처럼 연결되고, 토큰이 증가하고, 실패한 테스트는 oxblood로 표시된다. 비행이 끝나기 전에도 블랙박스를 열어볼 수 있다는 게 핵심이다.

• --

컨텍스트 효율 점수: 7가지 지표

모든 실행은 관측된 크기와 토큰 스냅샷에서 점수를 받는다. 자기 보고(self-report)는 절대 사용되지 않는다.

| 지표 | 잡아내는 문제 |

|---|---|

| Context pressure | 프롬프트가 피크에서 얼마나 컸는가 |

| Cache hit ratio | 캐시에서 얼마나 제공되었는가 |

| Redundant re-reads | 같은 파일을 두 번 이상 끌어옴 (회수 가능 토큰 표시) |

| Read amplification | 수정한 것보다 훨씬 많이 읽음 — 파일 통째 대신 슬라이스만 읽기 |

| Large injections | 단일 tool 출력이 컨텍스트를 범람 |

| Retry waste | 원인 수정 전에 실패 명령 재실행 |

| Yield density | 1k 토큰당 산출한 구체적 변화량 |

각 지표는 "구체적 수정 제안"으로 펼쳐진다. 규칙 기반 기본 동작에 더해, --suggest free로 API 키 없이도 무료 모델 풀을 자동 로테이션하며 조언을 받을 수 있다.

조언의 근거: 어떤 연구에서 왔는가

제안은 그럴듯한 일반론이 아니다. 모든 권고는 매 실행의 자체 수치를 인용하고, 문제 파일/명령을 지명하며, 메커니즘과 기대 효과를 명시해야 한다.

| 출처 | 기여 | 영향 지표 |

|---|---|---|

| Anthropic — Effective context engineering for AI agents | 컴팩션, sub-agent 컨텍스트 격리, just-in-time retrieval | context-pressure, read-amplification, redundant-reads, yield-density |

| Manus — Context Engineering for AI Agents: Lessons from Building Manus | KV-cache 적중률을 1차 비용 레버로, 바이트 안정 prefix, mask tools, 파일 시스템을 외부 기억으로 | cache-hit, large-injections, retry-waste |

| Liu et al. — Lost in the Middle | 모델이 긴 컨텍스트의 중간을 체계적으로 덜 사용 (U자 정확도, 약 30%+ 저하) | context-pressure, yield-density |

| Anthropic — Building effective agents | 최소·비중복 tool set, 도구 경계 명확화, 일괄 실행 | tool-overhead |

| Schulhoff et al. — The Prompt Report | 대비 few-shot, 수치 기반 grounding, 엄격한 구조화 출력 | advisor prompt 자체 형태 |

로컬 소형 모델에서 검증된 사례: "read each file once"라는 일반론이 아니라 "calculator.js가 2회 읽힘(약 282 토큰 회수 가능) — 한 번만 읽고 캐시한 뒤 변경된 줄 범위만 재읽으라"로 구체화된다.

• --

닫힌 루프: 발견을 AGENTS.md에 다시 쓰기

손으로 다시 적용해야 할 조언은 마찰이다. optimize는 마지막 실행의 발견을 프로젝트의 AGENTS.md 끝에 캐시-안전한 메모리 블록으로 적는다. 다음 실행은 같은 실수를 반복하기 전에 이미 회피한다.

# 미리보기 (변경 없음)
npm run optimize -- --project ~/code/my-app

# 적용: AGENTS.md에 관리 블록 추가 + 기준 점수 기록
npm run optimize -- --project ~/code/my-app --apply

# 다음 실행 후 효과 확인 — 점수가 떨어지면 자동 롤백
npm run optimize -- --project ~/code/my-app --check

# 되돌리기
npm run optimize -- --project ~/code/my-app --revert

블록은 파일 끝의 마커 사이에 기록되어 안정된 prompt-cache prefix를 건드리지 않는다. 파일을 한 번만 읽으라, 큰 출력은 범위를 좁히라, 검증된 build/test 명령은 재사용하라 — 구체 위반자를 이름 붙이고, opt-in이며, 모든 쓰기는 표시되어 자동 무음이 아니다.

실측: 같은 작업, 같은 모델, 메모리만 추가

oh-my-openagent의 ultrawork 실행(Claude Sonnet이 멀티 에이전트 팀을 운전)에 대한 공정한 before/after다. 작업은 "add a modulo operation end-to-end".

| | 실행 A (전) | 실행 B (후) |

|---|---|---|

| Context-efficiency score | 80 | 99 |

| Redundant re-reads | 9개 파일 (약 1.8k 회수 가능) | 0개 |

| 총 토큰 | 939k | 521k (−44%) |

| Tool calls / events | 619 | 253 |

| Yield density | 63/k | 154/k |

두 실행 모두 동일한 깨끗한 저장소에서 시작(git-reset 사이)했고 새 OpenCode 세션이었다 — 추가된 건 메모리뿐. 9개 파일의 중복 읽기 해소(9개 → 0개)는 메모리가 직접 작동한 결과다. OMO는 확률적이라 일부 토큰/이벤트 감소는 실행 간 분산이지만, ABB가 못 박은 레버는 정확히 사라진 낭비다.

• --

in-run optimizer: 재실행 없이 같은 실행 안에서 절감

AGENTS.md 메모리는 미래 작업에 효과가 있다. in-run optimizer는 현재 실행 안에서 낭비를 줄인다. 리코더는 더 이상 순수 수동적이지 않고, OpenCode tool hook을 통해 재읽기를 싸게 서빙한다. 기본값은 OFF, AGENT_BLACKBOX_OPTIMIZE=1 또는 --optimize로 켠다.

• 재읽기를 no-op 또는 diff로 서빙. 에이전트가 이미 읽은 파일을 다시 읽으면 tool.execute.after 훅이 결과를 다시 쓴다. 변경 없음 → "이전 사본을 재사용하라" 한 줄. 편집됨 → 변경된 줄 범위만. 120줄 파일 실측: 변경 없는 재읽기 96% 토큰 절감, 편집된 재읽기 94% 절감 — 같은 실행 안, 재실행 없이.
• 구조적으로 정확. 재읽기는 절대 차단되지 않는다(정말 필요할 수 있다). no-op/diff는 마지막 서빙 이후 컴팩션이 없을 때만 발동하므로 내용은 문맥상 여전히 유효함이 보장된다. 컴팩션 후에는 전체 파일이 다시 서빙된다 — 에이전트가 잃었을 수 있기 때문이다.
• 작업 세트 메모리를 라이브로 주입. experimental.chat.system.transform을 통해 작은 최신 블록(핫 파일 + 검증된 명령, 관측 이벤트에서 도출)이 system prompt에 추가되어 에이전트가 재읽기 대신 기억에서 꺼낸다.

• --

oh-my-openagent와 페어링: 토큰맥스 러너의 측정기

oh-my-openagent(OMO)는 OpenCode를 11명 전문가의 멀티 에이전트 토큰맥서 하네스로 바꾼다. 복잡한 작업을 토큰을 쏟아부어 끝낸다. Agent-Blackbox는 정확히 그 워크로드용 계기다 — OMO가 액셀을 바닥까지 밟고, ABB는 다이너모와 텔레메트리.

둘 다 OpenCode 플러그인이라 무설정 공존한다. 리코더 설치 후 OMO를 돌리면 팀 전체가 맵에 등장한다.

• 팀 전체를 본다. SDK가 생성한 모든 서브에이전트(Sisyphus, explore, librarian, plan, oracle…)가 각자 lane을 갖고, 위임은 trunk를 갈라친다.
• 비용을 보고 줄인다. "토큰맥서" 실행은 정확히 컨텍스트 경제성이 가장 중요한 자리다. ABB가 점수를 매기고(컨텍스트 압력, 재읽기, 읽기 증폭, tool 오버헤드), 정밀한 위반자를 이름 붙인다 — 하네스 안에서는 절대 보이지 않던 비용.
• 루프를 닫는다. 발견을 AGENTS.md에 못 박아 다음 실행에 반영하고, in-run optimizer(AGENT_BLACKBOX_OPTIMIZE=1)를 켜면 같은 실행 안에서 재읽기를 no-op/diff로 서빙한다.

npx @taewooopark/agent-blackbox up --suggest free
opencode "ultrawork: refactor the auth module and add tests"

• --

핸드오프: 어디서든 실행을 이어받다

다른 곳에서 실행을 이어받아야 할 때 — 팀 동료, 다음 에이전트, 컨텍스트 리셋 후 같은 에이전트 — 구조화된 handoff를 내보낸다.

• objective (목표)
• 관측된 것 (이벤트, 노드, 엣지)
• 플레이 중인 파일
• 결정
• 명령 / 검증
• 차단 사항
• 다음 안전 동작

원클릭으로 Markdown 복사 → 다음 세션에 그대로 붙여넣기.

• --

동작 방식: 데이터 흐름

Claude Code transcripts (tailed) ─┐
OpenCode hooks → recorder plugin ─┴─▶ host adapter ─▶ daemon ─▶ dashboard
                                       redact+normalize  NDJSON    live session map
                                                         + graph   + efficiency

• packages/core — 정식 TraceEvent, 워크플로우 그래프 모델, redact, 리플레이, audit, 핸드오프 생성, 컨텍스트 효율 엔진
• packages/claude-code-adapter — Claude Code가 이미 쓰는 JSONL transcript(~/.claude/projects/)를 tail해 정식 redact 이벤트로 정규화. 플러그인/설치 없음
• packages/opencode-adapter — OpenCode 플러그인. 호스트 이벤트와 tool 호출을 정식 이벤트로 변환(콘텐츠 크기만, 내용은 안 함)
• apps/daemon — NDJSON 로그 인제스트, 그래프 머터리얼라이즈, 임의 시점 리플레이, 효율 리포트, 제안 라우팅, WebSocket 라이브 스냅샷
• apps/dashboard — 운영 콘솔: 라이브 세션 맵, 리플레이, 인스펙터, 효율 코파일럿, 핸드오프

Daemon API

| Method & path | 용도 |

|---|---|

| POST /events | 정식 TraceEvent 인제스트 |

| GET /events | 영구 이벤트 로그 |

| GET /graph?seq= | 시퀀스까지 그래프 리플레이 |

| GET /snapshot?seq= | 이벤트·그래프·audit·효율 리포트·handoff markdown |

| GET /audit | 약속/주장 검사 |

| GET /efficiency?seq= | 컨텍스트 효율 리포트(점수+지표) |

| POST /suggest | 리포트 기반 최적화 제안(결정론 또는 로컬 모델) |

| GET /handoff | 생성된 핸드오프 markdown |

| WS /stream | 인제스트 후 라이브 스냅샷 push |

• --

설계 철학: 관측하라, 서술자를 신뢰하지 말라

> 자유 형식 자기 보고가 아니라 관측된 이벤트에서 진실을 도출하라.

• 서술이 아닌 행동. 모든 노드는 에이전트가 실제로 내뱉은 이벤트다 — 읽기, 편집, 명령과 exit code, 위임 — 자기 자신을 묘사한 문장이 아니다.
• 비용도 증거다. 효율 점수와 모든 제안은 모델의 자기 검약담이 아니라 관측된 크기와 토큰 스냅샷에서 온다.
• 로컬 우선, 키 없음. 트레이스는 사용자 머신에 남는다. 원시 프롬프트, 비밀, 파일 내용은 기본적으로 redact. 선택적 모델 제안조차 로컬에서 실행되며 redact된 다이제스트만 받는다.
• 호스트 무관 코어. 정식 이벤트 + 그래프 코어에 얇은 호스트 어댑터 — 어떤 에이전트 하네스 뒤에도 같은 블랙박스를 둘 수 있다. Claude Code와 OpenCode가 최초 두 개.

• --

정리

Agent-Blackbox는 "에이전트가 한 말"이 아니라 "에이전트가 한 일과 그 비용"을 보여주는 로컬 우선 도구다. 한 줄 npx로 설치 없이 시작하고, 세션 맵·컨텍스트 효율 점수·서브에이전트 계보·원클릭 핸드오프를 즉시 얻는다. --suggest free로 API 키 없는 무료 모델 풀을 자동 로테이션해 조언을 받고, optimize로 발견을 AGENTS.md에 못 박으면 다음 실행이 같은 실수를 반복하지 않는다. in-run optimizer는 같은 실행 안에서도 재읽기를 no-op/diff로 서빙해 토큰을 94~96% 절감한다. 멀티 에이전트 하네스를 굴리는 팀이라면, 이 도구는 다이너모에 해당한다 — 액셀을 밟는 OMO 옆에서 정확히 무엇이 얼마를 먹는지 알려준다.

GitHub: https://github.com/TaewoooPark/Agent-Blackbox

npm: https://www.npmjs.com/package/@taewooopark/agent-blackbox