컨텍스트 문제의 나머지 절반 — context-mode 써보기

요즘 Claude Code나 Cursor 같은 AI 코딩 에이전트를 오래 붙잡고 일하다 보면 한 가지 패턴이 보인다. 처음엔 척척 잘하다가, 작업이 길어질수록 점점 둔해진다. 방금 본 파일을 또 읽고, 내린 결정을 까먹고, 엉뚱한 데를 고친다. 흔히 "컨텍스트 창이 찼다"고 말하는 그 증상이다.

보통 그 원인을 프롬프트나 시스템 메시지에서 찾는데, 정작 컨텍스트를 가장 빨리 잡아먹는 건 따로 있다. 툴이 뱉는 출력이다. cat으로 연 8천 줄짜리 로그, git log 전체, 수 메가짜리 JSON 응답, 웹페이지 통째. 에이전트가 파일 하나 열거나 명령 한 번 돌릴 때마다 그 원본 바이트가 전부 대화에 쌓이고, 한 번 들어온 건 세션이 끝날 때까지 토큰을 먹으며 남아 있는다.

context-mode는 이걸 "컨텍스트 문제의 나머지 절반(the other half of the context problem)"이라고 부른다. 프롬프트 엔지니어링이 앞쪽 절반이라면, 툴 출력이 뒤쪽 절반이라는 것. 이번에 실제로 붙여서 써봤는데 발상이 꽤 깔끔해서 정리해둔다.

핵심 발상: 데이터를 읽지 말고, 계산해서 답만 꺼내라

context-mode의 한 줄 요약은 "Think in Code"다.

기존 흐름은 이렇다. 7.5MB짜리 JSON에서 특정 레코드 하나를 찾고 싶다 → 에이전트가 그 JSON을 통째로 읽어 대화에 올린다 → 7.5MB가 컨텍스트에 박힌다 → 그제서야 모델이 눈으로 훑어 답을 찾는다. 답은 한 줄인데 비용은 7.5MB다.

context-mode 방식은 이렇다. JSON은 샌드박스(별도 프로세스) 안에 두고, "13000번 인덱스 레코드를 찾아 출력해"라는 코드를 거기서 돌린다. 대화에 들어오는 건 그 코드가 console.log로 찍은 결과 한 줄뿐이다. 원본 바이트는 샌드박스에 그대로 남고, 컨텍스트엔 닿지 않는다.

README의 실측 예시가 직관적이다.

• 7.5MB JSON에서 숨은 레코드 찾기: 7.5MB → 0.9KB (99% 절감)
• React 문서를 받아 cleanup 패턴 찾기: 호출 2번, 컨텍스트 1.8KB

손에 잡히는 도구들

context-mode는 MCP 서버로 11개 툴을 붙여준다. 자주 쓰는 건 사실 네 개다.

• ctx_batch_execute — 셸 명령 여러 개를 병렬로 돌리고, 각 출력을 자동으로 인덱싱한 다음, 질문을 같이 넘기면 매칭되는 구간만 한 번에 돌려준다. 정보 수집의 1차 도구.
• ctx_execute / ctx_execute_file — 데이터·파일 위에서 코드(JS·셸)를 돌린다. 필터·집계·파싱·변환. console.log로 찍은 것만 대화로 올라오고 원본은 샌드박스에 남는다.
• ctx_search — 인덱싱해둔 것(내가 모은 출력 + 자동 캡처된 세션 메모리)을 FTS5 전문검색으로 뒤진다. Porter 어간 + 트라이그램 + RRF 랭킹이라 useEff로 useEffect를 찾는 식이다.
• ctx_fetch_and_index — URL을 받아 HTML을 마크다운으로 바꿔 인덱싱하고, 미리보기 창만 돌려준다. 페이지 원본은 대화에 안 들어오고, 필요한 구간은 ctx_search로 꺼낸다.

실제로 이 글을 쓰면서도 똑같이 했다. context-mode의 README(92KB짜리)를 통째로 읽는 대신 ctx_fetch_and_index로 인덱싱하고, "설치 방법", "절감 수치", "세션 메모리" 같은 질문만 ctx_search로 던져 필요한 조각만 받았다. README 전문이 내 컨텍스트로 들어온 적은 없다.

코드로 보면 이런 그림이다. 셸에서 큰 출력을 그냥 받는 대신:

# 이렇게 하면 8천 줄이 통째로 컨텍스트에 쌓인다
cat huge.log
git log --stat

샌드박스에서 처리해 결과만 꺼낸다:

// ctx_execute — 원본은 샌드박스에 두고 집계 결과만 print
const log = require('fs').readFileSync('huge.log', 'utf8');
const errors = log.split('\n').filter((l) => l.includes('ERROR'));
console.log(`에러 ${errors.length}건, 최근 3건:`);
console.log(errors.slice(-3).join('\n'));
// 대화로 올라오는 건 이 네 줄뿐이다

세션 메모리: 컴팩션을 넘어 기억한다

오래 돌린 세션은 결국 컨텍스트가 꽉 차서 "압축(compaction)"이 일어난다. 이때 앞쪽 대화가 요약되며 디테일이 날아간다. 내렸던 결정, 밟은 에러, 세웠던 계획이 흐려지는 지점이다.

context-mode는 hook으로 세션 이벤트를 계속 자동 캡처해둔다(결정·에러·계획·사용자 지시 등 26종). 컴팩션 직전에 스냅샷을 만들고, 압축 이후엔 그걸로 복구한다. 그래서 ctx_search에 sort: "timeline"을 주면 이전 세션·압축 이전의 결정까지 시간순으로 다시 꺼낼 수 있다. "아까 왜 이 방식 버렸더라"를 사람한테 다시 묻지 않아도 된다.

모델이 알아서 고르게: 라우팅

좋은 툴이 있어도 모델이 안 쓰면 그만이다. context-mode는 이 부분을 hook으로 강제한다. PreToolUse에서 큰 출력을 내는 툴(셸·파일읽기·grep·웹fetch)을 가로채 "이건 context-mode로 보내라"고 라우팅하고, PostToolUse로 세션 이벤트를 캡처하고, PreCompact로 스냅샷을 만든다.

그래서 절감률 차이가 크다. README 기준 hook까지 붙이면 약 98% 절감, 라우팅 안내 문서만 두는 MCP-only면 **약 60%**다. 그리고 이게 Claude Code 하나가 아니라 Gemini CLI, Cursor, VS Code·JetBrains Copilot, Codex CLI, Kiro 등 17개 플랫폼에 같은 방식으로 붙는다.

설치

가장 가볍게는 MCP 서버만 붙이면 된다.

claude mcp add context-mode -- npx -y context-mode

이러면 11개 툴은 다 쓸 수 있지만 자동 라우팅은 없다(모델이 "쓸 수 있다"는 걸 알 뿐, 강제되진 않는다). hook·슬래시 커맨드·상태줄까지 자동으로 붙이려면 플러그인으로 설치하면 된다. 붙고 나면 상태줄에 이번 세션 절감액 · 누적 절감액 · 효율 %가 실시간으로 뜨고, /context-mode:ctx-stats로 언제든 확인할 수 있다.

붙었는지는 이걸로 확인한다.

/mcp list
# context-mode: ... - Connected 이 보이면 성공

쓰기 전에 알아둘 것

두 가지는 짚고 가는 게 좋다.

• 샌드박스 ≠ OS 격리. ctx_execute 계열은 임의 코드를 돌리고, 그 프로세스의 파일시스템 권한을 그대로 물려받는다. 컨텍스트 절감 장치이지 보안 격리가 아니다. 실행 툴 승인은 곧 "임의 코드 실행 승인"으로 보고, 호스트 레벨 샌드박싱은 켜두는 게 맞다.
• 웹 fetch엔 SSRF 방어가 들어가 있다. ctx_fetch_and_index는 http/https만 허용하고 file://·클라우드 메타데이터 엔드포인트(169.254.169.254)·멀티캐스트 같은 위험 타깃을 기본 차단한다. 단 로컬 dev 서버나 사내망(localhost, RFC1918)은 기본 허용이라 평소 작업은 막지 않는다.

정리

context-mode가 푸는 문제는 한 문장이다. "답은 한 줄인데 왜 원본 7.5MB가 컨텍스트에 남아 있나?" 데이터를 모델 머릿속(=대화)으로 끌어오지 말고, 샌드박스에서 코드로 처리해 결론만 꺼내라는 것. 그 결과 같은 작업을 더 적은 토큰으로, 더 오래, 덜 둔해진 채로 돌릴 수 있다.

긴 작업을 자주 돌리는 사람이라면 MCP-only로라도 한번 붙여보고 ctx-stats로 절감액을 직접 보는 걸 권한다. 숫자가 생각보다 크다.