Local Search Engine for Claude Code

QMD
Query Markdown
Documents

코드베이스의 마크다운 문서를 사전 인덱싱하여,
Claude Code가 문서를 찾을 때마다 소모되는 토큰을 극적으로 절감하는 로컬 검색 엔진.

◆ BM25 + Vector + LLM Reranking ◆ MCP Server ◆ 100% Local
Scroll

01 — Problem왜 QMD가 필요한가

Claude Code는 코드베이스에서 정보를 찾을 때 glob → grep → read 3단계 과정을 반복한다. 파일 목록을 훑고, 키워드로 검색하고, 실제 파일을 읽는다. 매번 이 사이클이 돌 때마다 수천~수만 토큰이 소모되고, 컨텍스트 윈도우는 빠르게 소진된다.

프로젝트 규모가 커질수록 이 문제는 심각해진다. 레포가 10개, 20개로 늘어나면 동일한 질문에 대해서도 매번 탐색 비용을 지불하게 되는 것이다.

Before — 기존 방식
1
Glob — 파일 패턴 매칭
↓
2
Grep — 키워드 검색
↓
3
Read — 파일 전체 읽기
↓
×N
결과 불충분 시 반복
토큰 소모량 (예상)
~15,000tokens / query
After — QMD 적용
1
Query — 하이브리드 검색
↓
2
Result — 관련 스니펫 즉시 반환
토큰 소모량 (예상)
~2,500tokens / query
~80%
토큰 절감률
1-step
검색 사이클
0
외부 API 의존

02 — Architecture어떻게 작동하는가

QMD는 마크다운 문서를 세 가지 검색 엔진으로 동시에 인덱싱한다. 쿼리가 들어오면 각 엔진이 독립적으로 결과를 반환하고, 최종적으로 LLM 재순위화(reranking)를 통해 가장 관련성 높은 문서를 선별한다.

📄
Documents
*.md 파일 수집
🧮
Indexing
BM25 + 벡터 임베딩
🔍
Hybrid Search
Lex + Vec + HyDE
🏆
Reranking
LLM 기반 최종 순위

모든 처리는 로컬에서 실행된다. 임베딩 모델은 최초 인덱싱 시 다운로드되며, 이후 추가 네트워크 통신 없이 동작한다. Claude Code와는 MCP(Model Context Protocol) 서버로 연결되어, Claude가 자연어 질문을 던지면 QMD가 관련 스니펫을 직접 반환한다.

03 — Search Types세 가지 검색 모드

검색 의도에 따라 최적의 모드를 선택하거나, 여러 모드를 조합한 하이브리드 검색으로 정확도를 극대화할 수 있다.

lex
BM25 키워드 검색
정확한 용어가 포함된 문서를 빠르게 찾는다. 함수명, 설정 키, 에러 메시지 등 정확한 문자열을 알고 있을 때 가장 효과적이다.
{type:'lex', query:'redis connection timeout'}
vec
벡터 의미론적 검색
단어가 정확히 일치하지 않아도 의미적으로 유사한 문서를 찾는다. "에러 처리 방법"을 검색하면 "예외 핸들링", "try-catch 패턴" 등을 함께 반환한다.
{type:'vec', query:'에러를 우아하게 처리하는 방법'}
hyde
가상 문서 임베딩 (HyDE)
질문에 대한 가상의 답변 문서를 먼저 생성한 뒤, 그 문서와 가장 유사한 실제 문서를 찾는다. 복잡한 질문이나 추상적인 개념 검색에 강력하다.
{type:'hyde', query:'마이크로서비스 간 인증 처리'}
Tip: 하이브리드 검색

여러 모드를 조합하면 정확도가 크게 향상된다. 예: [{type:'lex', query:'deploy'}, {type:'vec', query:'배포 자동화 설정'}] 처럼 키워드와 의미 검색을 동시에 실행할 수 있다.

04 — Benefits도입 효과

⚡
토큰 사용량 절감

glob→grep→read 반복 없이 한 번의 쿼리로 관련 문서를 직접 반환. 문서 탐색에 드는 토큰을 최대 80% 이상 줄일 수 있다.

🎯
정확한 문서 발견

키워드 매칭을 넘어 의미 기반 검색으로 관련 문서를 놓치지 않는다. LLM 재순위화가 최종 결과의 품질을 보장한다.

🔒
완전한 로컬 실행

외부 API를 호출하지 않는다. 모든 인덱싱과 검색이 로컬에서 처리되어 민감한 코드가 외부로 유출될 위험이 없다.

🔌
MCP 네이티브 통합

Claude Code의 MCP 서버로 등록하면 별도 설정 없이 자연어 검색을 바로 활용할 수 있다.

05 — Setup Guide설정 예시

실제 프로젝트에 QMD를 적용하는 전체 과정을 단계별로 살펴보자. 아래 예시는 여러 레포를 관리하는 모노레포 또는 멀티레포 환경을 가정한다.

  1. QMD 설치

    npm으로 전역 설치한다.

    npm install -g @tobilu/qmd
qmd --version  # 2.1.0+

  2. Claude Code에 MCP 서버 등록

    QMD를 MCP 서버로 등록하면 Claude Code가 직접 검색을 요청할 수 있다.

    claude mcp add qmd -- qmd mcp
claude mcp list  # qmd: qmd mcp - ✓ Connected

  3. 워크스페이스 구조화

    관련 레포를 카테고리별로 정리하면 컬렉션 관리가 용이해진다.

    workspace/
    ├── projects/      # 활성 프로젝트 레포
    │   ├── web-app/
    │   ├── mobile-api/
    │   └── admin-dashboard/
    ├── libraries/    # 공유 라이브러리 & 도구
    │   ├── shared-utils/
    │   └── design-system/
    └── archived/      # 이전 버전 레포
        └── legacy-api/

  4. 컬렉션 등록 & 인덱싱

    워크스페이스를 컬렉션으로 등록하고 임베딩을 실행한다.

    # 컬렉션 등록
qmd collection add ./workspace --name my-repos
qmd collection add ./docs --name my-docs

# 인덱싱 (첫 실행 시 모델 다운로드)
qmd embed

  5. 검색 테스트

    세 가지 검색 모드로 인덱싱 결과를 확인한다.

    # 키워드 검색 (BM25)
qmd search "redis connection"

# 의미론적 검색 (Vector)
qmd vsearch "에러를 우아하게 처리하는 방법"

# 하이브리드 검색 (BM25 + Vector + Reranking)
qmd query "배포 설정"

  6. CLAUDE.md에 지침 추가

    프로젝트의 CLAUDE.md에 QMD 우선 사용 지침을 명시하면, Claude Code가 파일을 읽기 전에 항상 QMD를 먼저 참조하게 된다. 

    # CLAUDE.md

## QMD

파일을 읽기 전에 항상 QMD MCP 도구로 먼저 검색.
glob/grep 대신 QMD 우선 사용.
레포 업데이트 & 재인덱싱

워크스페이스 레포를 최신 상태로 유지하려면 주기적으로 git pull 후 qmd embed를 재실행한다. 변경된 파일만 증분 인덱싱되므로 이후 실행은 빠르게 완료된다.

06 — In Practice실제 사용 예시

QMD가 MCP 서버로 연결되면, Claude Code 대화 중에 다음과 같은 방식으로 자동 활용된다. 

# 사용자 질문
"Redis 연결 설정은 어떻게 되어있어?"

# Claude Code의 내부 동작
→ QMD query: [{type:'lex', query:'redis connection'},
                 {type:'vec', query:'Redis 연결 설정 방법'}]

# QMD 결과
→ 3개 관련 문서 반환 (스니펫 포함, ~800 tokens)
  1. projects/web-app/docs/infra.md — Redis 클러스터 설정
  2. libraries/shared-utils/README.md — 캐시 유틸리티
  3. projects/mobile-api/docs/env.md — 환경변수 목록

# glob→grep→read 없이 즉시 답변 생성
핵심 포인트

QMD는 Claude Code의 도구 체인에 검색 단축키를 추가하는 것이다. 기존 glob/grep/read가 사라지는 것이 아니라, 대부분의 문서 탐색을 QMD가 먼저 처리하여 불필요한 토큰 소모를 방지한다. 필요한 경우 Claude는 여전히 파일을 직접 읽을 수 있다.