대부분의 "토큰 사용량을 X% 절감했습니다"라는 게시물들은 숫자를 대충 얼버무립니다. 이 글은 그 방법과 리포지토리(repos), 그리고 도구가 사실상 아무런 역할도 하지 못하는 경우까지 보여줍니다. 저는 여러분이 결과에 감명받기보다는 그 결과를 신뢰하기를 바랍니다.

문제점: 에이전트가 단 세 줄을 보기 위해 파일 전체를 읽는 현상

코딩 에이전트(coding agent)가 대규모 코드베이스(codebase)에서 작업하는 것을 지켜보면 다음과 같은 동일한 루프가 반복되는 것을 볼 수 있습니다:

1. grep -rn "handlePayment" src/ → 수십 개의 file:line 결과가 나옵니다.
2. 그중 네 개의 파일을 **전체(in full)**로 읽습니다. 각 파일은 수백 줄에 달하지만, 단지 각 결과 주변의 약 10줄을 확인하기 위해서입니다.
3. 다음 심볼(symbol)에 대해 이 과정을 반복합니다.

파일 전체를 읽을 때마다 모델이 필요하지 않은 수백에서 수천 개의 토큰 컨텍스트(context)가 소모되며, 매번 새로운 라운드 트립(round trip)이 발생합니다. 작은 리포지토리(repo)에서는 눈에 띄지 않습니다. 하지만 실제 코드베이스에서는 이것이 누적되어 느리고 비용이 많이 드는 세션이 되며, 결국 에이전트가 훑어보기만 했던 파일들로 컨텍스트 윈도우(context window)가 가득 차게 됩니다.

기본 도구들이 틀린 것은 아닙니다. 단지 정밀도가 낮을(coarse) 뿐입니다. Grep은 줄(lines)을 찾고, Read는 파일(files)을 반환하며, 에이전트는 전체 토큰 비용을 지불하며 이들을 하나로 묶어야 하는 상황에 놓이게 됩니다.

Parecode: 파일이 아닌 컨텍스트를 반환하는 검색

Parecode는 해당 루프를 대체하는 세 가지 도구를 갖춘 MCP 서버입니다:

• ParecodeSearch — ripgrep 기반 검색으로, 단 한 번의 호출로 주변 컨텍스트를 포함한 매칭된 윈도우(windows)만 반환합니다. 여러 패턴을 병렬로 실행하고, 중복되는 윈도우를 병합하며, 파일별로 청크(chunk)를 나누어 큰 결과 세트가 컨텍스트(context)를 초과하지 않도록 합니다. 또한 에이전트가 스스로 예산을 책정할 수 있도록 estimatedTokens를 보고하며, 아무것도 조용히 누락되지 않도록 생략된 라인 범위를 나열합니다. 읽기 전용(Read-only)입니다.
• ParecodeExpand — 자연스러운 후속 조치로, 에이전트가 특정 매칭 지점 주변의 정보가 더 필요하다고 판단할 때 특정 (file, startLine, endLine) 범위를 확장합니다. 라인을 찾은 후에는 파일 전체를 읽는 Read 방식보다 효율적입니다. 읽기 전용(Read-only)입니다.
• ParecodeEdit — 공백에 관대한 퍼지 매칭(fuzzy matching)을 지원하며, 한 번의 호출로 여러 파일에 걸친 배치 편집(batched edits)을 수행합니다. 오래된 읽기 데이터가 파일을 조용히 덮어쓰지 않도록 사전/사후 충돌 감지(conflict detection) 기능을 갖추고 있으며, 동일 디렉토리 내의 원자적(atomic) 이름 변경 쓰기를 지원합니다. 파일 간 편집은 병렬로 실행됩니다.

따라서 'grep 후 4개 파일 읽기'와 같은 번거로운 과정은 관련 슬라이스(slices)를 반환하는 단 한 번의 ParecodeSearch 호출로 대체되며, 에이전트가 실제로 더 많은 정보가 필요할 때만 ParecodeExpand를 사용합니다. 컨텍스트가 5번의 응답 대신 한 번의 응답으로 전달되기 때문에 토큰(token) 사용량과 턴(turn) 수가 모두 줄어듭니다.

벤치마크 (The benchmark)

단순히 눈으로 확인하는 대신, 대조군을 설정한 A/B 테스트를 수행했습니다:

• 모델 (Model): Claude Sonnet 4.6
• 실행 (Runs): 각 그룹당 n = 3회, 워밍 캐시(warm-cache) 및 순서 효과를 상쇄하기 위해 **실행 순서를 교차(order alternated)**함
• 세션 (Sessions): 매 실행마다 새로운 세션 사용 — 컨텍스트 유지 없음
• 조건 (Conditions): parecode 사용 여부만 다른 동일한 작업 수행
• 작업 (Tasks): 검색 및 편집 작업 — 두 개의 실제 코드베이스에서 심볼(symbol)의 모든 호출 지점(call site)을 찾아 각각 편집함

두 경우 모두: 비용 약 40% 절감 및 어시스턴트 턴 (assistant turns) 약 75–83% 감소. 이러한 절감 효과는 수많은 Grep/Read/Edit 왕복 과정을 단일 ParecodeSearch/ParecodeEdit 호출로 압축함으로써 발생합니다. 따라서 작업의 검색량과 멀티 파일 확산 (multi-file fan-out) 정도가 클수록 이점은 더욱 커집니다.

도움이 되지 않는 경우

전체 작업이 이미 열려 있는 단일 파일 내에서 이루어진다면, parecode의 절감 효과는 0에 가깝게 줄어듭니다. 압축할 'grep 후 읽기 (grep-then-read)' 루프가 없으므로 얻을 수 있는 이득도 없습니다. 내비게이션 (navigation)과 관련이 없는 추론 중심 (reasoning-heavy) 작업도 마찬가지입니다. 이 도구는 에이전트가 암기하지 못한 코드베이스 전반에 걸친 멀티 파일 작업에서 제 역할을 다합니다. 잘못된 용도로 설치했다가 실망하시는 것보다 차라리 이렇게 말씀드리는 편이 낫겠습니다.

또 다른 주의 사항: 편집 도구의 원자성 (atomicity)은 파일 단위이며, 파일 간(cross-file) 단위가 아닙니다. 설계상 배치 (batch) 내의 한 파일은 실패하더라도 다른 파일들은 적용될 수 있습니다. 광범위한 리팩터링 (refactor)에 이 도구에 의존하기 전에 이 점을 반드시 숙지하십시오.

Claude Code와 함께 사용하기

npm install -g parecode   # Node 20+ 및 PATH에 ripgrep 필요
parecode init             # MCP 서버, SessionStart 훅, explore 플러그인 등록

솔직한 디테일 하나를 말씀드리자면: init은 에이전트가 기본 제공되는 Grep / Read / Edit 대신 ParecodeSearch / ParecodeEdit를 선호하도록 유도하는 SessionStart 훅을 설치합니다. 이러한 유도가 없다면 기본 도구들이 우선권을 갖게 되어 절감 효과를 전혀 볼 수 없습니다. 또한, 더 저렴한 모델에 고정된 읽기 전용

이 프로젝트는 MIT 라이선스를 따르며, TypeScript로 작성되었고, Glama에 등록되어 있습니다.

• Repo: https://github.com/BasilSkyWalk/parecode
• npm install -g parecode

먼저 부담 없이 성능을 확인해보고 싶다면, parecode stats --retroactive를 실행해 보세요. 이 명령어는 사용자의 과거 Claude Code 세션에서 얼마나 비용을 절감했을지 추정해 줍니다 (측정된 값이 아닌 추정치이지만, 워크플로우에 적합한지 판단할 수 있는 합리적인 지표가 될 것입니다).

실제로 사용해 보신다면 여러분이 얻은 결과 수치를 꼭 듣고 싶습니다. 특히 도움이 되지 않는 사례들에 대해 알려주시면 감사하겠습니다. 그런 사례들이 있어야 다음 버전이 더 개선될 수 있기 때문입니다. 이슈(Issues) 및 풀 리퀘스트(PRs)는 언제나 환영합니다.