Sverklo는 로컬 호스팅 코드 검색 서버로, 이제 개발자가 AI 에이전트가 결과에 따라 동작하기 전에 파일 검색부터 심볼 그래프 추론에 이르기까지 쿼리의 모든 단계를 검토할 수 있도록 지원합니다.

기존 코딩 에이전트가 헤매는 이유

대부분의 코드 생성 도구는 저장소를 거대한 텍스트 덤프처럼 취급합니다. 스니펫을 임베딩하고 유사도 검색을 실행한 뒤, 가장 높은 점수를 받은 조각을 반환하는 방식입니다. 만약 해당 조각이 오래되었거나, 범위를 벗어났거나, 단순히 파일 이름일 뿐이라면 에이전트는 그 출처를 지목할 수 없습니다. 여기서 발생하는 실패 양상은 단어가 누락된 것이 아니라, 해당 사실이 어디에서 왔으며 여전히 유효한지를 인간에게 알려주는 컨텍스트 계층이 누락되었다는 점입니다.

Sverklo의 4계층 검증 모델

Sverklo는 전통적인 검색에 구조적 분석을 결합한 "엔지니어링 가설" 서버를 지향합니다.

  • 파일 검색 (File Discovery) – 인덱스는 .gitignore 및 기타 무시 파일을 읽습니다. 결과를 신뢰하기 전에 인덱스를 쿼리하여 실제로 어떤 경로가 스캔되었는지 확인할 수 있습니다.
  • 코드 구조 (Code Structure) – 심볼은 정의, 임포트, 호출 관계를 기록하는 그래프 내에 존재합니다. 조회를 통해 단순히 파일 경로가 아닌 심볼 객체를 반환하므로, 올바른 API 표면(surface)이 참조되었는지 확인할 수 있습니다.
  • 컨텍스트 전달 (Context Delivery) – 토큰 예산을 설정하면, Sverklo는 답변에 기여한 스니펫의 맵을 반환합니다. 이 맵에는 found_by 필드가 포함되어 있어, 매칭 결과가 BM25 키워드 매칭, ONNX 기반 임베딩, 또는 PageRank 기반 심볼 그래프 중 무엇을 통해 도출되었는지 알려줍니다.
  • 메모리 원장 (Memory Ledger) – 서버는 각 결정을 기록합니다. 파일이 변경되면 원장은 해당 메모리 항목을 오래된(stale) 것으로 표시하여, 캐시된 답변이 여전히 유효한지 보여줍니다.

검색 스택의 작동 방식

Sverklo는 임베딩에만 의존하지 않습니다. 정확한 용어 매칭을 위해 클래식 BM25 키워드 엔진을 실행하고, 의미론적 유사성을 위해 ONNX 기반 벡터 임베딩으로 검색 결과를 보강하며, 마지막으로 심볼 그래프에 PageRank 알고리즘을 적용하여 영향력이 큰 정의를 노출합니다. 각 검색 결과가 생성된 방식을 공개함으로써, 개발자는 불일치 사례(예: 임베딩 모델은 관련 없다고 판단했지만 BM25는 매칭된 경우)를 발견하고 어떤 신호를 신뢰할지 선택할 수 있습니다.

실무 활용 사례

  • 익숙하지 않은 코드베이스 탐색 – 수동으로 grep을 실행할 필요 없이 함수 이름에서 모든 호출자로 즉시 이동할 수 있습니다.
  • 의존성 그래프 매핑 – 여러 패키지에 걸쳐 있는 임포트 체인을 시각화합니다.
  • 리팩토링 영향도 추정 – 특정 파일이 변경될 경우 어떤 심볼이 깨질지 확인할 수 있습니다.
  • 의미론적 질문 답변 – "이 헬퍼 함수가 하는 일이 뭐야?"라고 물으면 출처가 명시된 간결한 발췌문을 얻을 수 있습니다.

주의해야 할 함정

  • 최신성 (Freshness) – 재인덱싱이 완료되었더라도 인덱스 타임스탬프는 예전 상태로 남아 있을 수 있습니다. 최신 실행 결과가 현재 상태라고 가정하는 대신, 항상 index-status 엔드포인트를 통해 인덱스 상태를 쿼리하십시오.
  • 프로젝트 등록 – 프로젝트 등록을 해제할 때는 절대 파일 시스템 경로가 아닌 Sverklo에서 제공하는 내부 프로젝트 이름을 사용해야 합니다. 그렇지 않으면 작업이 조용히 실패합니다.
  • 도구 명명 방식의 특이점 – MCP 호스트는 때때로 프로젝트 이름을 두 번 붙여 sverklo_sverklo_impact와 같은 식별자를 생성하기도 합니다. 도구를 호출하기 전에 이름을 다시 한번 확인하십시오.

다음에 시도해 볼 것

  1. 테스트용 저장소를 클론하고 로컬에서 Sverklo를 실행합니다.
  2. 간단한 심볼 조회를 실행하고 found_by 필드를 검토합니다.
  3. 소스 파일을 수정하고 조회를 다시 실행하여, 메모리 원장이 오래된 항목을 어떻게 표시하는지 확인합니다.
  4. 빌드 스크립트에 index-status 확인 기능을 통합하여 오래된 인덱스를 자동으로 감지하도록 합니다.

요약

Sverklo는 코드 검색 엔진을 감사 가능한 증거 체인으로 변모시킵니다. 개발자가 파일 커버리지, 심볼 정확도, 검색 방법 및 메모리 최신성을 직접 검증하도록 함으로써, AI 기반 제안이 프로덕션에 적용되기 전에 신뢰할 수 있는지 스스로 결정할 수 있게 합니다.