Agent 코드 검색에는 토큰 예산이 있어요

Semble은 2026년 5월 17일에 GitHub 스타 900개를 넘기면서 직설적인 주장을 내세웠어요. 코딩 에이전트는 grep을 돌리고, 파일을 통째로 열고, 작업에 필요한 것보다 훨씬 많은 코드를 읽느라 맥락 예산 대부분을 낭비한다는 주장이에요.¹

이 주장이 설득력 있는 이유는 코드 검색을 예산 문제로 다시 정의하기 때문이에요. 사람은 잡음이 많은 rg 결과를 훑어보면서 불필요한 부분을 무시할 수 있어요. 하지만 에이전트는 관련 없는 줄 하나하나에 대해 맥락, 주의, 도구 반복 시간이라는 비용을 치러요.

요약

Semble은 에이전트를 위한 코드 검색 라이브러리예요. MCP 서버, AGENTS.md 또는 CLAUDE.md를 통한 셸 통합, CLI, Python API을 제공해요.¹ 내부적으로 Semble은 코드를 청크로 나누고, BM25와 정적 Model2Vec 코드 임베딩으로 검색한 뒤, Reciprocal Rank Fusion으로 순위 목록을 합치고, 심볼 가중치, 정의 부스트, 식별자 어간, 파일 일관성, 잡음 페널티 같은 코드 인식 신호로 다시 순위를 매겨요.¹ 벤치마크는 19개 언어, 63개 저장소, 약 1,250개 쿼리에서 NDCG@10 0.854를 보고해요. 이는 CodeRankEmbed 하이브리드 점수 0.862에 가깝고, 벤치마크 표에서는 훨씬 빠르게 인덱싱해요.² 중요한 제품적 교훈은 “grep을 대체하라”가 아니에요. 더 날카로운 교훈은 이것이에요. 에이전트 검색 도구는 모델이 올바르게 행동하는 데 필요한 가장 작은 증거 묶음을 반환해야 해요.

핵심 정리

• 코딩 에이전트 사용자에게: 정확한 문자열에는 rg를 계속 쓰세요. 하지만 작업이 문자 그대로의 토큰이 아니라 동작을 묻는다면 스니펫 순위 검색을 사용하세요.
• 도구 제작자에게: 검색 정확도만 최적화하지 말고, 가져온 맥락을 최적화하세요. 유용한 단위는 토큰당 증거예요.
• Codex와 Claude Code 사용자에게: 하위 에이전트에는 셸에서 접근할 수 있는 경로를 우선하세요. 최상위 MCP 도구가 위임된 에이전트까지 같은 방식으로 닿지 않을 수 있기 때문이에요.¹
• 벤치마크 독자에게: 공급업체 벤치마크 주장과 로컬 실행 동작을 분리해서 보세요. 제 콜드 uvx 실행은 Semble의 벤치마크 표보다 훨씬 오래 걸렸어요. 패키지, 모델, 인덱스 시작 비용이 지배적이었기 때문이에요.
• 공개 글쓰기에서: 검색 도구는 인용 작업을 없애주지 않아요. 증거 경로를 더 싸게 살펴보게 해줄 뿐이에요.

Grep은 여전히 좋지만, 그것만으로는 부족해요

정확한 문자열에는 rg가 여전히 첫 번째로 써야 할 도구예요. visible_label_residue, 자격 증명 변수 이름, 기능 이름이 필요하다면 어휘 검색이 속도와 확실성에서 이겨야 해요. 제 로컬 테스트에서 번역 잔여 표현을 찾는 리터럴 rg 쿼리는 약 0.1초 만에 결과를 반환했어요.⁵

문제는 에이전트가 정확한 문자열을 모를 때 시작돼요.

에이전트는 종종 의도로 검색해요. “블로그 i18n 관문은 보이는 라벨 잔여 표현을 어디에서 검사하지?” 또는 “번역 릴리스 검증은 어떻게 작동하지?” 같은 식이에요. 리터럴 검색도 유용한 줄을 찾을 수는 있어요. 하지만 에이전트는 단어를 고르고, 수십 개의 결과를 살펴보고, 파일을 읽고, 쿼리를 다시 만들고, 어느 줄이 답을 담고 있는지 판단해야 해요. 모든 단계가 맥락을 소비하고, 너무 일찍 멈출 가능성을 만들어요.

Semble은 바로 이 실패 양식을 겨냥해요. 에이전트가 자연어로 쿼리하면 전체 파일이 아니라 순위가 매겨진 코드 스니펫을 반환해요.¹ 그렇다고 rg가 쓸모없어지는 것은 아니에요. 기본 상호작용이 “이 용어와 일치하는 모든 줄을 보여줘”에서 “유용한 가장 작은 코드 조각을 줘”로 바뀌는 거예요.

이 차이는 중요해요. 에이전트는 사람처럼 읽지 않기 때문이에요. 사람은 검색 출력 80줄을 훑어보고 흥미로운 3줄만 마음에 남길 수 있어요. 모델은 전체 출력을 토큰으로 받아요. 잡음이 많은 검색 결과는 그대로 작업 환경의 일부가 돼요.

Semble이 실제로 하는 일

Semble의 공개 README는 4가지 통합 경로를 설명해요. MCP 서버, Bash / AGENTS.md, CLI, Python API이에요.¹ Codex 설정은 ~/.codex/config.toml에 로컬 MCP 서버 항목을 추가하는 방식이고, 셸 경로는 AGENTS.md 또는 CLAUDE.md에 코드 검색 섹션을 추가해요.¹

셸 경로는 처음 보이는 것보다 더 중요해요. README는 Claude Code와 Codex CLI 하위 에이전트가 MCP 대신 또는 함께 Bash 통합을 사용해야 한다고 설명해요. 그 설정에서는 하위 에이전트가 MCP 도구를 직접 호출할 수 없기 때문이에요.¹ 이는 실용적인 에이전트 인터페이스 문제예요. 검색 도구는 최상위 작업 맥락이 시작되는 곳에만 있으면 안 되고, 실제 작업이 일어나는 곳에 있어야 해요.

검색 구조도 에이전트 검색이 향하는 방향과 닮아 있어요.

이 설계는 제가 로컬 검색 시스템에서 본 흐름과도 맞아요. 순수 벡터 검색은 식별자를 놓치고, 순수 키워드 검색은 의도를 놓치며, 하이브리드 순위화는 에이전트에게 더 나은 첫 읽기를 제공해요.⁴

벤치마크 주장은 마법이 아니라 맥락에 관한 이야기예요

Semble의 벤치마크 README는 서로 다른 두 종류의 결과를 보고해요.

첫 번째는 검색 품질과 속도를 측정해요. 표에서는 Semble이 NDCG@10 0.854, CodeRankEmbed Hybrid가 0.862, BM25가 0.673, ripgrep이 0.126이라고 보고해요. 벤치마크는 19개 언어, 63개 저장소, 약 1,250개 쿼리를 다루며, CPU 전용으로 실행됐어요.²

두 번째는 토큰 효율을 측정해요. 벤치마크는 흔한 코딩 에이전트 작업 흐름을 모델링해요. 쿼리를 키워드로 나누고, rg --fixed-strings --ignore-case를 실행하고, 서로 다른 키워드 일치 수로 파일 순위를 매긴 뒤, 일치한 파일을 통째로 읽는 방식이에요. 이 기준선과 비교했을 때 벤치마크는 ripgrep과 파일 전체 읽기가 평균 45,692토큰을 쓰는 반면 Semble은 566토큰을 쓴다고 보고해요. 98% 감소예요.²

흥미로운 주장은 바로 이 부분이에요. 모든 상황에서 “의미 검색이 grep보다 낫다”가 아니에요. “에이전트는 정확 검색을 그만 써야 한다”도 아니에요. 작업에 몇 개의 청크만 필요한데 grep 후 파일 읽기 방식이 너무 많은 관련 없는 코드를 모델에 보낸다는 주장이에요.

벤치마크 방법론은 이 주장이 어디에 적용되고 어디에는 적용되지 않는지도 설명해요. Semble은 일치한 파일을 통째로 읽는 방식과 비교해요.² 이미 rg -n, sed, 정밀한 줄 범위를 사용하는 작업 흐름이라면 기준선이 벤치마크의 grep 후 파일 전체 읽기 모델보다 더 빡빡할 수 있어요. 반대로 에이전트가 넓은 검색 뒤에 파일을 통째로 여는 일이 잦다면, 벤치마크는 실제 실패 양식에 더 가까워요.

제 로컬 테스트

저는 사이트 저장소에서 uvx --from semble semble로 Semble을 실행한 뒤 리터럴 rg 검색과 비교했어요.

먼저 릴리스 프로세스 쿼리로 시작했어요.

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Semble은 5개의 스니펫을 반환했어요. 최상위 결과는 마이그레이션 글의 표에서 블로그 번역 릴리스 반복 과정을 요약했어요. 또 다른 결과는 scripts/i18n-automation/README.md를 직접 가리켰고, 그 파일에는 품질 관문, 릴리스 검증기, 원어민 검토, 커밋, push, Railway, Cloudflare, 라이브 스모크 단계가 들어 있었어요.⁵

비슷한 rg 명령은 빠르게 끝났지만, 자격 증명 변수, blog_release_verify, 관련 이름에 대한 리터럴 일치가 스크립트, 테스트, 문서 전반에서 큰 흐름으로 반환됐어요.⁵ 사람은 그것을 걸러낼 수 있어요. 에이전트는 같은 일을 하려고 맥락을 써야 해요.

그다음 관문 구현을 물었어요.

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Semble의 최상위 결과는 visible_label_residue가 할당되고, 오류로 변환되며, finding 상태에 영향을 주는 정확한 로컬 관문 블록을 가리켰어요. 출력에는 전체 파일이 아니라 관련 기능 본문 줄이 포함됐어요.⁵

비슷한 rg 쿼리도 다시 더 빠르게 끝났지만, 테스트, 번역 프롬프트, 복구 스크립트, README, 관문 구현 전반에서 많은 결과를 반환했어요.⁵

이 테스트가 Semble의 벤치마크를 증명하지는 않아요. 제 실행은 uvx를 사용했고, 패키지와 모델 자산을 다운로드했으며, 큰 혼합 저장소를 인덱싱했고, Markdown과 JSON 파일을 포함했으며, 콜드 경로에서 실행됐어요. 첫 Semble 쿼리는 약 54초, 두 번째는 약 31초가 걸렸어요.⁵ 이 숫자는 프로젝트의 벤치마크 표와 맞지 않으며, 저는 이것을 Semble 성능 데이터로 인용하지 않을 거예요.

하지만 이 테스트는 제품의 형태를 보여줘요. Semble은 더 작고 답에 가까운 증거 묶음을 반환했어요. 두 번 검색한 뒤 semble savings --verbose는 자체 파일 대비 스니펫 절약 방식으로 약 38,100개의 예상 토큰을 절약했고, 절약률은 94%라고 보고했어요.⁵ 이는 독립 측정이 아니라 도구가 보고한 추정치로 보아야 해요. 그래도 방향은 화면에 보인 출력과 맞았어요.

올바른 사고방식: 증거 묶음

에이전트 검색은 증거 묶음을 만들어야 해요.

증거 묶음에는 4가지 속성이 있어요.

원시 rg는 위치와 속도를 제공해요. 전체 파일 읽기는 맥락을 주지만 너무 많이 줘요. 벡터 검색은 의도를 제공하지만 정확한 이름을 놓칠 수 있어요. 좋은 에이전트 검색 작업 흐름은 이것들을 결합해요.

1. 작업이 심볼, 오류, 설정 키, 파일, 리터럴 문자열을 이름으로 말할 때는 정확 검색을 사용하세요.
2. 작업이 동작을 말할 때는 스니펫 순위 의미 검색 또는 하이브리드 검색을 사용하세요.
3. 스니펫이 관련성을 입증한 뒤에만 전체 파일을 여세요.
4. 최종 답변에서 파일과 줄 범위를 인용하세요.
5. 스니펫이 구체적인 식별자를 제시하면 정확 검색으로 다시 확인하세요.

Semble은 이 작업 흐름의 많은 부분을 도구로 인코딩해요. 그래도 에이전트에는 여전히 판단이 필요하고, 증거 관문에는 검토할 수 있는 흔적이 필요해요.

Semble이 Codex와 Claude Code 작업 흐름을 바꾸는 방식

실용적인 질문은 모든 새 검색 도구를 설치해야 하느냐가 아니에요. 코드 검색이 에이전트의 운영 계약에서 어디에 속해야 하느냐예요.

최상위 작업 맥락에서는 MCP가 잘 작동할 수 있어요. 에이전트가 도구 스키마를 보고 서버를 직접 호출하기 때문이에요. Semble의 README에는 Claude Code, Codex, OpenCode, Cursor, 기타 MCP 호환 클라이언트를 위한 MCP 설정 예시가 들어 있어요.¹

위임된 작업에서는 셸 접근이 더 중요할 수 있어요. Semble의 README는 Claude Code와 Codex CLI 하위 에이전트를 위해 Bash 통합을 명시적으로 언급해요.¹ 최상위 MCP 도구에 닿을 수 없는 하위 에이전트라도, 작업 흐름이 언제 어떻게 쓰는지 가르쳐주면 셸 명령은 실행할 수 있어요.

따라서 가장 좋은 통합은 평범해 보일 수 있어요.

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

이런 지침은 막연한 “의미 검색을 사용하라”는 규칙보다 나아요. 어떤 질문에 어떤 도구를 써야 하는지 라우팅 결정을 이름 붙여주기 때문이에요.

제가 하지 않을 일

저는 rg를 대체하지 않을 거예요.

로컬 테스트에서 그 점은 분명했어요. rg는 리터럴 쿼리에 약 0.1초 만에 답했어요. Semble은 동작 중심 쿼리에 더 나은 묶음을 반환했지만, 제 콜드 셸 실행에는 실제 시작 비용과 인덱싱 비용이 있었어요.⁵

Semble의 98% 토큰 주장을 보편적인 것으로 취급하지도 않을 거예요. 벤치마크는 grep 후 파일 전체 읽기와 비교해요. 그 기준선이 에이전트 동작과 닮아 있다면 주장은 타당해요. 이미 좁은 줄 범위를 읽는 절제된 작업 흐름이라면 이득은 과장돼요.

라우팅 선택을 블랙박스 안에 숨기지도 않을 거예요. 에이전트는 자신이 정확 조회, 의미 발견, 관련 코드 탐색, 증거 확인 중 무엇을 하고 있는지 알아야 해요. 라우팅 규칙 없는 도구 사용은 그럴듯한 실패의 또 다른 원천이 돼요. 채팅 중심 에이전트 작업 뒤에 있는 인터페이스 문제와 같아요.

Semble이 Grep 논문 옆에 놓일 만한 이유

최근 “Is Grep All You Need?” 논문은 장기 기억 대화형 질의응답에서 Chronos, Claude Code, Codex CLI, Gemini CLI에 걸쳐 grep과 벡터 검색을 테스트했어요. 그 환경에서는 인라인 grep이 인라인 벡터보다 나았지만, 논문의 더 깊은 교훈이 더 중요해요. 실행 환경은 검색 방식만큼이나 결과를 바꿨어요.³

Semble은 코드 쪽에서 같은 운영 계층을 가리켜요. 검색 품질은 검색기 하나에만 있지 않아요. 검색 품질은 다음에 걸려 있어요.

• 쿼리가 어떻게 만들어지는지;
• 정확 경로와 의미 경로가 모두 있는지;
• 도구가 얼마나 많은 맥락을 반환하는지;
• 스니펫이 파일과 줄 증거를 함께 담는지;
• 에이전트가 필요한 경우에만 전체 파일을 여는지;
• 위임된 에이전트가 도구에 접근할 수 있는지;
• 최종 답변이 검색이 실제로 찾은 것을 인용하는지.

래퍼가 곧 제품이에요. 검색은 실행 환경이 검색 결과를 증거로 바꿀 때만 유용해져요. 그래서 에이전트형 디자인 제어 표면은 검색 알고리즘만큼 중요해요.

제가 원하는 기준

에이전트 검색 도구는 일치 결과 이상의 것을 보고해야 해요.

다음을 보고해야 해요.

• 실행한 쿼리;
• 사용한 검색 경로;
• 파일과 줄 범위;
• 스니펫;
• 반환된 토큰의 추정치;
• 결과가 정확 검색, 의미 검색, 하이브리드 검색 중 어디에서 나왔는지;
• 에이전트가 언제 스니펫에서 전체 파일 읽기로 확장했는지.

이런 출력은 코드 검색을 감사 가능하게 만들어요. 리뷰어는 에이전트가 올바른 코드를 찾았는지, 충분한 맥락을 읽었는지, 관련 없는 파일에 스스로를 빠뜨리지 않았는지 볼 수 있어요. 같은 원칙이 에이전트 실행 흔적을 움직여요. 증명은 답만이 아니라 경로 안에 있어요.

Semble은 이미 스니펫 크기와 토큰 절약을 제품의 일급 관심사로 다루면서 그 방향으로 움직이고 있어요. 에이전트 실행 환경의 다음 단계는 그 증거 경로를 검토 묶음과 최종 답변에서 보이게 만드는 일이에요.

목표는 더 예쁜 검색이 아니에요. 목표는 토큰당 근거 없는 주장을 줄이는 거예요.

FAQ

Semble은 grep을 대체하나요?

아니요. 정확한 문자열, 심볼, 설정 키, 파일 이름, 빠른 확인에는 rg를 사용하세요. 작업이 동작이나 관련 구현을 설명하고 에이전트가 정확한 식별자를 모를 때는 Semble식 스니펫 검색을 사용하세요.

로컬 테스트가 Semble의 속도 주장을 확인했나요?

아니요. 제 로컬 uvx 실행은 첫 번째 쿼리에 약 54초, 두 번째 쿼리에 31초가 걸렸어요. 대부분 패키지와 모델 시작, 인덱싱이 임시 실행을 지배했기 때문이에요. Semble의 벤치마크 표는 훨씬 빠른 통제 측정값을 보고하지만, 제 로컬 실행은 성능 벤치마크가 아니라 작업 흐름 증거로 보아야 해요.²⁵

로컬 테스트가 토큰 절약 방향은 확인했나요?

네, 작업 흐름 수준에서는 확인했어요. Semble은 넓은 리터럴 rg 출력보다 훨씬 작은 스니펫을 반환했고, savings 명령은 두 번의 검색 뒤 약 38,100개의 예상 토큰을 절약했다고 보고했어요. 절약 수치는 Semble 자체 계산 방식에서 나온 것이므로 독립 증명이 아니라 도구 원격 측정으로 보세요.⁵

에이전트 코드 검색이 Codex와 Claude Code에 왜 중요한가요?

검색이 너무 많은 맥락을 쏟아내거나 너무 많은 증거를 숨기면 에이전트 품질이 떨어져요. 좋은 작업 흐름은 에이전트에게 언제 정확 검색을 쓰고, 언제 스니펫 순위 검색을 쓰며, 언제 전체 파일을 열고, 결과를 어떻게 인용해야 하는지 가르쳐요.

팀은 AGENTS.md에 Semble을 추가해야 하나요?

자기 코드베이스에서 테스트한 뒤에만 추가하세요. 첫 지침은 하나면 충분해요. 동작 중심 질문에는 스니펫 순위 검색을 사용하고, 정확한 문자열에는 rg를 사용하세요. 에이전트가 올바른 파일을 더 빨리 찾고 관련 없는 줄을 덜 읽는지 측정하세요.

참고 문헌