도구 호출 쉰 번 대신 코드 한 번 — aside-codemode를 만든 이유

aside-codemode는 에이전트가 도구를 쉰 번 부르는 대신 JavaScript 한 블록을 실행해, 검색·필터·요약을 샌드박스 안에서 끝내고 답만 모델에 넘기게 해 줍니다. 12만 7천 개 파일에서 function이 나오는 줄을 세는 작업은 2,966ms에 778바이트로 끝났고, 같은 일을 grep -r로 시키면 128초 동안 3.23GB를 쏟아내다 중단됐습니다.

문제는 속도가 아니라 모델에 들어가는 양이다

에이전트에게 “TODO가 들어간 파일 다섯 개만 찾아 줘”라고 하면, 보통은 파일을 하나씩 엽니다. 쉰 개를 열면 도구 호출도 쉰 번, 모델 컨텍스트에 들어가는 바이트도 파일 쉰 개 분량입니다. 정작 필요한 답은 경로 다섯 줄인데요.

웹도 마찬가지입니다. 페이지 다섯 개에서 제목과 첫 링크만 필요해도, 페이지를 통째로 읽으면 HTML 186만 바이트가 모델로 들어갑니다.

코드 한 번으로 바꾸기

코드 모드는 순서를 뒤집습니다. 모델은 “무엇을 원하는지”를 코드로 쓰고, 그 코드는 샌드박스에서 돌면서 파일을 읽고 거르고 줄인 뒤 결과만 돌려줍니다.

const hits = await search.content({ path: ".", query: "TODO", max: 50 });
return [...new Set(hits.rows.map((r) => r.file))].slice(0, 5);

모델에 도착하는 건 경로 다섯 개뿐입니다. 브라우징도 URL 여러 개를 한 세션에서 열고, 원하는 값만 타입이 있는 행으로 받습니다. 저장소의 2026년 9월 15일 측정에서는 페이지 다섯 개가 1,865,043바이트 대신 4,430바이트로 돌아왔습니다.

엔진은 원래 있었다

Aside에는 ripgrep이 이미 들어 있었지만, 문서화된 도구 중에 그걸 부르는 게 없었습니다. 에이전트가 쓸 수 있는 건 bash 위의 grep과 find뿐이었죠. aside-codemode는 그 엔진을 도구 표면으로 끌어올린 것이지, 더 빠른 검색 엔진을 만든 게 아닙니다. ripgrep을 직접 부르는 것과 비교하면 속도는 비슷합니다.

숫자를 읽는 법

이 도구에는 수치가 두 종류 있습니다.

• 운영자 보고: 실제 개발 폴더에서 find+grep 55초가 한 번의 호출 1초로 줄었다는 기록. 폴더와 정확한 옵션이 기록되지 않아 독립 재현은 아닙니다.
• 통제 측정: 2026년 9월 18일, 워밍업을 버린 뒤 7회 반복. 12만 7천 개 파일 트리에서 grep -r은 128초 동안 3.23GB를 출력하고도 끝나지 않아 중단했고, search.count는 2,966ms에 778바이트로 502,963줄·57,403개 파일이라는 답을 냈습니다.

두 번째가 더 중요합니다. 이건 속도 향상이라기보다, POSIX 도구만 든 에이전트는 아예 물어볼 수 없던 질문에 답할 수 있게 된 것이니까요. 불리한 경우를 포함한 전체 표는 저장소의 BENCHMARKS.md에 있습니다.

같은 생각의 다른 도구

agbrowse도 같은 원칙으로 만들었습니다. 상주하는 MCP 서버 없이 짧은 명령으로 브라우저를 다루고, 필요한 증거만 출력합니다. 에이전트 도구를 만들 때 가장 먼저 묻는 질문은 “모델에 무엇이 들어가는가”입니다.