AI 코딩 에이전트를 오래 쓰면 컨텍스트 비용이 커집니다.
대용량 로그를 붙여 넣거나 오래된 레거시 파일을 통째로 읽히면 입력 토큰이 빠르게 늘어납니다. 프로젝트 루트의 긴 AGENTS.md, CLAUDE.md, .cursorrules 같은 지침 파일도 매번 포함됩니다. 실제 답변에 필요한 내용은 그중 일부일 때가 많습니다.
token-router ↗는 “로컬에서는 찾고, 클라우드에서는 추론한다”는 구조로 이 문제를 줄이는 도구입니다. 로컬 LLM이 관련 라인 범위만 찾고, 스크립트가 원문을 그대로 잘라낸 뒤, 클라우드 모델은 그 조각(evidence)만 보고 추론합니다.
이 글은 작성 시점 2026-06-17의 token-router GitHub README ↗와 GeekNews 소개 글 ↗을 바탕으로 정리했습니다.
컨텍스트가 커지면 비용과 노이즈가 늘어납니다
큰 컨텍스트 창은 편하지만 비용이 듭니다. 대형 로그, 단일 거대 파일, 반복 삽입되는 에이전트 지침은 토큰 비용과 대기 시간을 동시에 키웁니다.
노이즈도 늘어납니다. 모델이 읽을 정보가 많을수록 중요한 에러 한 줄이나 변수 정의 하나가 묻힐 수 있습니다. 그래서 AI 코딩 도구를 쓸 때는 프롬프트 작성과 함께 컨텍스트 선별에도 공을 들여야 합니다.
에이전트가 오래 일하려면 모델 성능과 함께 기억, 역할 분리, 결과물 전달 방식, 컨텍스트 밀도를 설계해야 합니다. 앞의 세 가지는 Claude Code Memory, Claude Code Agent Teams, OpenAI Codex Sites에서 다뤘습니다.
token-router의 작동 방식
token-router README는 구조를 세 단계로 나눕니다. 로컬 모델은 search와 triage를 맡고, router script는 원문 추출을 맡고, 클라우드 LLM은 reasoning을 맡습니다.
flowchart TD
A[큰 로그 / 레거시 코드 / 긴 에이전트 문서] --> B[Local Ollama model<br/>관련 라인 좌표 탐색]
B --> C[Router script<br/>원본 파일에서 raw slice 추출]
C --> D[Cloud reasoning model<br/>디버깅·수정·리뷰]
D --> E[답변 또는 패치]
B -.요약하지 않음.-> C
C -.원문 그대로 전달.-> D역할을 이렇게 나누는 이유가 있습니다. 작은 로컬 모델에게 전체 코드를 요약시키면 한 줄의 stack frame, config key, indentation, error suffix가 사라질 수 있습니다. token-router는 이 위험을 피하려고 로컬 모델에게 분석을 맡기지 않고 라우터 역할만 줍니다.
로컬 모델의 출력은 “이 범위를 보라”는 좌표입니다. 실제로 클라우드 모델에 전달되는 내용은 파이썬 스크립트가 파일에서 직접 잘라낸 raw text입니다.
세 가지 모드
README 기준 token-router는 세 가지 routing mode를 제공합니다.
| 모드 | 용도 |
|---|---|
error_log | 로그, stack trace, CI 출력, 배포 실패 조사 |
heavy_code | 긴 소스 파일 안의 특정 버그나 코드 조사 |
agent_context | 긴 에이전트 지침 문서에서 현재 작업 관련 규칙만 검색 |
agent_context 모드는 긴 지침 파일 문제를 다룹니다. Claude Code, Codex, Cursor 같은 도구를 쓰다 보면 루트 지침 파일이 점점 길어집니다. 처음에는 몇 줄짜리 규칙이지만, 시간이 지나면 아키텍처, 테스트 정책, 배포 주의사항, 보안 규칙이 계속 붙습니다.
token-router는 루트 파일을 짧게 유지하라고 권합니다. 긴 작업별 규칙은 별도 reference 문서로 나누고, 필요한 부분만 라우팅합니다. 플랫폼이 긴 루트 파일을 이미 자동 주입했다면 그 비용은 나중에 줄일 수 없습니다. 그래서 구조를 미리 나눠야 합니다.
설치와 실행
README의 quick start는 Python 3.10+, Ollama, 로컬 routing model을 전제로 합니다. 기본 모델 예시는 gemma4:e2b-it-q4_K_M입니다.
ollama pull gemma4:e2b-it-q4_K_M큰 로그를 조사할 때는 다음처럼 실행합니다.
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py error_log path/to/deploy.log --query "database migration timeout"긴 소스 파일은 heavy_code 모드를 씁니다.
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py heavy_code path/to/service.py --query "token expiration"긴 에이전트 reference 문서는 agent_context로 라우팅합니다.
OLLAMA_NUM_CTX=4096 OLLAMA_KEEP_ALIVE=0s \
python3 scripts/router.py agent_context path/to/agent-context/frontend.md --query "frontend testing workflow"이 명령들은 답변을 만들지 않습니다. 클라우드 모델이 읽을 원문 조각을 추려 내는 전처리 단계입니다.
README 벤치마크: 입력 토큰 98~99% 감소
README의 benchmark highlight는 토큰 수를 chars / 4로 추정했다고 밝힙니다. 따라서 청구 금액과 정확히 일치하지 않고, 경향을 보는 지표로 읽어야 합니다.
| 케이스 | 모드 | 추정 입력 토큰 | router 출력 토큰 | 감소율 |
|---|---|---|---|---|
| 2,000줄대 infra log | error_log | 41,711 | 131 | 99.69% |
| 2,155줄 legacy source | heavy_code | 7,520 | 70 | 99.06% |
| keywordless structural source | heavy_code | 4,188 | 48 | 98.85% |
이 수치를 모든 프로젝트에 그대로 대입할 수는 없습니다. 파일이 조밀하거나, 질문이 넓은 architecture review라면 필요한 맥락이 훨씬 많을 수 있습니다.
그래도 클라우드 모델에게 모든 파일을 먼저 읽히는 대신 로컬에서 “읽어야 할 위치”를 찾는 계층을 두면, 입력 토큰을 크게 줄일 수 있습니다.
언제 우회해야 하나
README는 token-router를 쓰지 말아야 할 경우도 적어 둡니다. 다음 작업은 라우터를 우회하거나 넓은 컨텍스트를 직접 제공하라고 설명합니다.
- broad architecture review
- 여러 모듈에 걸친 refactor planning
- 보안상 complete audit이 필요한 코드
- 모든 섹션이 중요한 dense source file
라우터는 필요한 줄을 찾도록 돕지만, 빠짐없이 찾는다고 보장하지는 않습니다. 선택된 범위가 너무 좁으면 클라우드 모델이 더 넓은 라인 범위를 다시 요청할 수 있어야 합니다.
마무리
AI 코딩 에이전트의 비용은 더 싼 모델을 쓰는 방법 외에, 모델이 읽을 컨텍스트를 정확하게 골라서도 줄일 수 있습니다.
token-router에서는 작은 로컬 모델이 탐색을 맡고, 클라우드 모델은 추론을 맡고, 둘 사이에는 원문을 잃지 않는 slicing layer가 있습니다.
AI 에이전트를 자주 쓴다면 지금 워크플로에서 모델이 문제를 푸는 데 토큰을 쓰는지, 불필요한 문서를 뒤지는 데 쓰는지 확인해 보세요.