BM25 기반의 빠른 코드 검색 도구 Shebe 소개

BM25를 이용한 빠른 코드 검색

Shebe는 BM25를 기반으로 하는 빠르고 간단한 로컬 코드 검색 도구입니다. 임베딩(embeddings)도, GPU도, 클라우드 연결도 필요 없습니다.

연구에 따르면 개발자 코드 검색 가치 중 70~85%가 키워드 기반 쿼리에서 발생합니다. 개발자들은 함수 이름, API 호출, 오류 메시지 등 자신이 아는 정확한 용어로 검색하는 경향이 있습니다. BM25는 이 부분에서 탁월합니다.

트레이드오프 (Trade-offs):

• 인덱싱 전에 리포지토리(Repositories)를 로컬로 클론해야 합니다 (원격 URL 지원 안 함).
• 의미적 유사성 검색은 불가능합니다: "login"이 "authenticate"와 일치하지 않습니다. 하지만 BM25는 성능 저하 없이 다중 용어 쿼리(multi-term queries)를 지원합니다. 따라서 에이전트들은 동의어 포함을 빠르게 학습하게 됩니다 (예: login OR authenticate OR sign-in). 진정한 의미적 검색(semantic search)을 위해서는 벡터 도구와 결합해야 합니다. 자세한 분석은 [링크]를 참조하십시오.

기능 (Capabilities):

• 쿼리 지연 시간 2ms
• 초당 2k~12k 파일 인덱싱 (0.5초에 6k 파일 처리)
• 쿼리당 200~700 토큰 지원
• 전체 UTF-8 지원 (이모지, CJK, 특수 문자)
• 코딩 에이전트를 위한 14개 MCP 도구 제공 (claude, codex 등) (참조)
• 대용량 결과에 대한 페이지네이션: 커서 기반 list_dir, 오프셋 기반 read_file

크기 (Size):

• src/ 디렉토리 내 Rust 코드 약 17.5k 라인 (인라인 유닛 테스트 포함) + 통합 테스트 약 5.2k 라인.
• 바이너리 2개 (cli 및 mcp), 각각 약 8MB 크기.

포지셔닝 (Positioning):
구조적 도구(Serena MCP)와 콘텐츠 검색을 보완합니다. 코딩 에이전트는 다음 도구 선택을 빠르게 학습하게 됩니다:

grep/ripgrep: 정확한 정규 표현식 패턴, 포괄적인 매칭, 소규모 코드베이스에 적합
Shebe: 순위가 지정된 결과, 대규모 코드베이스 (1k+ 파일), 다국어 검색(polyglot search), 불리언 쿼리 지원
Serena: 심볼 리팩토링, AST(추상 구문 트리) 인식 편집, 타입 안전한 이름 변경

대안 (Alternatives):
turbopuffer나 nia와 같은 클라우드 솔루션은 높은 비용이 발생합니다. Shebe는 무료이며 로컬 전용 대안입니다. 벤치마크는 WHY_SHEBE.md를 참조하십시오.

• 빠른 시작하기 (Quick Start)
• 일반적인 작업 (Common Tasks)
• 리팩토링 워크플로우 (Refactoring Workflow)
• 설정 (Configuration)
• 문서화 (Documentation)
• 성능 (Performance)
• 아키텍처 (Architecture)
• 문제 해결 (Troubleshooting)
• 프로젝트 상태 (Project Status)
• 라이선스 (License)
• 기여하기 (Contributing)

Homebrew (macOS 및 Linux):

brew tap shebe-oss/tap
brew install shebe

지원되는 플랫폼 및 문제 해결 방법은 homebrew-tap 저장소를 확인하세요.

수동 다운로드 (Linux x86_64):

export SHEBE_VERSION=v0.6.0
curl -LO "https://github.com/shebe-oss/shebe/releases/download/${SHEBE_VERSION}/shebe-${SHEBE_VERSION}-linux-x86_64.tar.gz"
curl -LO "https://github.com/shebe-oss/shebe/releases/download/${SHEBE_VERSION}/shebe-${SHEBE_VERSION}-linux-x86_64.tar.gz.sha256"
...

검증:

shebe --version

# 테스트 저장소 클론하기
git clone --depth 1 https://github.com/envoyproxy/envoy.git ~/envoy
# 인덱싱하기 (세션 "envoy-v1" 생성)
...

# 접근 로그 포맷팅 검색
shebe search-code envoy-v1 "accesslog format"

Results for "accesslog format" in envoy-v1 (top 10):
1. source/extensions/access_loggers/common/access_log_base.h [0.847]
class AccessLogBase : public AccessLog::Instance {
...

# SubstitutionFormatter에 대한 모든 참조 찾기
shebe find-references envoy-v1 SubstitutionFormatter --symbol-type type

References to "SubstitutionFormatter" (type) - 23 found:
HIGH CONFIDENCE (18):
source/common/formatter/substitution_formatter.h:45
...

자세한 설정은 INSTALLATION.md를 참조하세요.

특정 목표를 달성하기 위한 빠른 링크:

Shebe의 find_references 및 search_code 도구는 리팩토링 작업으로 영향을 받는 모든 코드 위치를 열거하는 데 함께 작동합니다. 이 예시에서 Claude Code는 Shebe를 사용하여 페이지네이션 작업 계획을 분석하고 변경해야 하는 모든 파일을 식별하여 전체 영향 분석을 약 1분 만에 완료했습니다.

전체 워크플로우 보기 (6개의 스크린샷)

단계 1: 리포지토리 인덱싱 및 병렬 find_references 실행

단계 2: search_code가 CLI 라우팅 코드를 찾음

단계 3: 구조적 분석 -- 변경이 필요한 소스 파일

단계 4: 새 모듈, 배선(wiring) 및 문서화

단계 5: 파일 생성 계획 및 제외 목록

단계 6: 영향 요약 (~11개 파일, 1분 14초)

~/.config/shebe/config.toml 파일을 생성하세요 (또는 작업 디렉터리에 레거시인 shebe.toml):

[indexing]
chunk_size = 512
overlap = 64
...

전체 참조는 CONFIGURATION.md를 확인하세요.

INSTALLATION.md - 설치 및 설정 가이드
Quick Start Guide - Claude Code용 5분 설정

MCP Tools Reference - 모든 14개 도구에 대한 전체 API
CONFIGURATION.md - 모든 구성 옵션
Performance Benchmarks - 상세 성능 데이터

ARCHITECTURE.md - 개발자 가이드 (코드 변경 위치/방법)
CONTRIBUTING.md - 기여 방법
CODE_OF_CONDUCT.md - 커뮤니티 지침
SECURITY.md - 보안 정책 및 보고

**Istio (5,605개 파일, Go 중심) 및 OpenEMR (6,364개 파일, PHP 다중 언어)**에서 검증됨:

개발자 가이드는 ARCHITECTURE.md를 참고하세요.

버전 기록은 CHANGELOG.md를 참고하십시오.

LICENSE는 별도 확인 바랍니다.

기여를 환영합니다! 자세한 가이드라인은 CONTRIBUTING.md를 참조해 주십시오.