보물창고로 돌아가기
기타 유용한 팁2026-02-074분 읽기

AI 토큰 최적화: qmd 가이드 및 Windows 환경 적용 지침

🚀 AI 토큰 최적화: qmd (Quick Markdown Search) 가이드

AI 에이전트(Claude Code, OpenClaw 등)가 코드베이스를 탐색할 때 발생하는 막대한 토큰 낭비를 줄이기 위한 로컬 문서 인덱싱 솔루션, qmd를 소개합니다. 기존의 Glob -> Grep -> Read 방식보다 최대 90% 이상의 토큰 절감 효과를 제공합니다.

1. qmd의 핵심 이점

  • 탐색 비용 제거: AI가 정보를 찾는 데 쓰는 비용을 최소화하고, 정보를 사용하는 데 집중하게 합니다.
  • 컨텍스트 최적화: 전체 파일을 읽는 대신 필요한 코드 조각(Snippet)만 타겟팅하여 읽습니다.
  • 속도 향상: 처리해야 할 컨텍스트 양이 줄어들어 응답 속도가 비약적으로 빨라집니다.

📊 실제 토큰 절감 수치 (테스트 결과)

시나리오qmd 미사용qmd 사용절감률
인증 로직 찾기~2,700 토큰~250 토큰91%
결제 버그 수정~3,950 토큰~400 토큰90%
DB 스키마 이해~6,050 토큰~400 토큰93%

2. Windows 환경 qmd 적용 가이드

Windows 환경에서 qmd를 사용할 때 발생할 수 있는 내부 셸 실행 오류를 해결하고, 안정적으로 연동하기 위한 지침입니다.

🛠️ 문제 해결: 우회 실행 방식

qmd를 bun으로 설치할 경우, Windows에서도 내부적으로 /bin/bash를 호출하도록 설계되어 있어 실행 오류가 발생할 수 있습니다. 이를 해결하기 위해 qmd 명령어 대신 bun을 이용해 소스 코드를 직접 실행하는 방식을 권장합니다.

핵심 실행 구조:

# 예시: 글로벌 설치 경로의 qmd.ts를 직접 실행
bun "C:\Users\[사용자명]\.bun\install\global\node_modules\qmd\src\qmd.ts" [명령어]

🚀 주요 명령어 요약

  1. 프로젝트 등록 (최초 1회)
bun "C:\Users\[사용자명]\.bun\install\global\node_modules\qmd\src\qmd.ts" collection add . --name [프로젝트명] --mask "**/*.{ts,tsx,md,json,css,js,mjs}"
  1. 인덱싱 및 임베딩 (코드 변경 시 수시로)
bun "C:\Users\[사용자명]\.bun\install\global\node_modules\qmd\src\qmd.ts" embed
  1. AI 에이전트 검색 (예시)
bun "C:\Users\[사용자명]\.bun\install\global\node_modules\qmd\src\qmd.ts" query "인증 로직 파일 찾아줘"

3. 주요 검색 모드 활용

  1. search (BM25): 키워드 기반 빠른 검색. (예: "auth middleware")
  2. vsearch (Vector): 개념적 연관 검색. 의미 기반 탐색에 유리. (예: "에러 처리 방식")
  3. query (Hybrid): 하이브리드 검색 + LLM 재정렬. 가장 높은 품질의 결과 제공.

4. 에이전트 규칙 설정 (Best Practice)

새로운 AI 세션을 시작할 때 다음과 같은 규칙을 부여하면 효과가 극대화됩니다:

"파일 읽기나 디렉터리 탐색 전에 항상 qmd를 사용하여 정보를 검색하라. 무지성 Read/Glob은 금지하며, 필요한 코드 스니펫만 타겟팅하여 컨텍스트를 최적화하라."

🔗 참고 링크