qmd Windows 가이드: AI가 무작정 파일을 읽지 않게 만드는 로컬 검색 워크플로우

먼저 결론

qmd는 AI 에이전트가 프로젝트를 탐색할 때 "일단 다 읽고 보자"로 흐르는 것을 막아주는 로컬 검색 도구입니다. 문서, 회의록, 코드, 지식 베이스를 인덱싱하고, 키워드 검색, 벡터 검색, 하이브리드 질의를 통해 필요한 조각만 찾게 합니다.

이 프로젝트에서는 특히 Windows, OneDrive, 한글 경로, UTF-8 출력이 함께 얽혀 있습니다. 그래서 qmd를 쓸 때는 일반 설치 설명보다 운영 규칙이 더 중요합니다.

핵심은 네 가지입니다.

1. PowerShell에서 UTF-8 부트스트랩을 먼저 로드한다.
2. Windows에서 qmd 래퍼가 깨지면 bun으로 qmd.ts를 직접 실행한다.
3. status -> search/query -> get/read 순서로 탐색한다.
4. .next, node_modules, out, build 같은 산출물은 인덱스에서 제외한다.

왜 이 글을 저장해야 하는가

AI가 코드베이스를 망치는 순간은 보통 수정할 때가 아니라 읽을 때 시작됩니다.

• 파일을 너무 많이 읽는다.
• 빌드 산출물을 원본처럼 착각한다.
• 오래된 문서와 최신 코드를 섞는다.
• 한글이 깨진 로그를 그대로 복사한다.
• OneDrive 동기화 중인 DB를 열다가 실패한다.

qmd는 이런 문제를 줄이기 위한 검색 레이어입니다. 공식 qmd README는 qmd를 마크다운 노트, 회의록, 문서, 지식 베이스를 위한 온디바이스 검색 엔진으로 설명합니다. BM25 full-text search, vector semantic search, LLM re-ranking을 결합하고, search, vsearch, query 모드를 제공합니다. 참고: tobi/qmd GitHub

qmd의 한 문장 정의

qmd는 로컬 문서와 코드에서 필요한 스니펫만 찾기 위해 BM25, 벡터 검색, 하이브리드 재정렬을 제공하는 CLI 검색 도구입니다.

qmd의 목적은 모든 파일 읽기를 대체하는 것이 아닙니다. 어디를 읽어야 할지 찾는 비용을 줄이는 것입니다.

이 프로젝트의 기본 실행 규칙

Windows PowerShell에서는 먼저 UTF-8 환경을 고정합니다.

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1

그다음 qmd를 직접 실행합니다.

bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" status

기존 문서에 있던 global\node_modules 경로가 줄바꿈으로 깨진 형태는 그대로 복사하면 안 됩니다. 반드시 한 줄 경로로 써야 합니다.

C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts

기본 명령 세트

1. 상태 확인

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" status

작업 시작 전에는 status를 먼저 봅니다. 인덱스가 없거나 오래됐으면 검색 결과를 믿기 어렵습니다.

2. 컬렉션 등록

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" collection add . --name mouseco-hub --mask "**/*.{ts,tsx,js,mjs,json,md,mdx,css}"

등록 범위는 무작정 넓히지 않습니다. 이 프로젝트에서는 앱 저장소인 mouseco-hub/에서 실행하는 것이 안전합니다.

3. 임베딩 생성

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" embed

파일이 많이 바뀌었거나 새 문서가 늘었으면 다시 실행합니다.

4. 키워드 검색

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" search "theme toggle"

정확한 단어를 알고 있을 때 씁니다.

5. 의미 검색

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" vsearch "게시판 헤더 색상이 흐린 문제"

정확한 파일명이나 키워드가 떠오르지 않을 때 씁니다.

6. 하이브리드 질의

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" query "라이트 테마에서 브리핑 게시판 스타일을 담당하는 파일"

질문형 탐색에서는 query가 가장 편합니다. qmd README도 query를 full-text, vector, query expansion, re-ranking을 결합한 하이브리드 모드로 설명합니다.

7. 문서 가져오기

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1; bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" get "#abc123"

검색 결과에 docid가 나오면 get으로 특정 문서를 가져옵니다. 단, 코드 수정 전에는 실제 파일도 확인해야 합니다.

검색 모드 선택표

상황	먼저 쓸 명령	이유
정확한 함수명/파일명을 안다	search	빠르고 단순함
개념만 안다	vsearch	의미 기반 후보를 찾음
질문처럼 묻고 싶다	query	검색+재정렬을 함께 수행
결과 문서가 정해졌다	get	특정 문서 확인
인덱스 상태가 의심된다	status	먼저 상태를 봐야 함

AI 에이전트용 운영 규칙

프로젝트 AGENTS.md 또는 세션 첫 지시에 아래 규칙을 넣으면 좋습니다.

파일 경로가 명확하지 않은 탐색 작업에서는 qmd를 먼저 사용한다.
순서는 status -> search/query -> 필요한 파일 직접 읽기다.
전체 디렉터리 무차별 읽기, 빌드 산출물 읽기, 깨진 한글 출력 재사용을 피한다.
Windows PowerShell에서는 UTF-8 부트스트랩을 먼저 로드한다.

다만 모든 작업에 qmd가 필요한 것은 아닙니다. 사용자가 특정 파일 경로를 줬거나, rg로 정확한 검색이 더 빠른 경우에는 바로 해당 도구를 쓰는 것이 낫습니다.

제외해야 할 경로

qmd 컬렉션이나 검색 대상에서 아래는 제외해야 합니다.

.git/
.next/
.vercel/
node_modules/
out/
build/
output/
.tmp/
.gstack/

이 경로들은 원본 지식이 아니라 산출물, 캐시, 의존성, 배포 상태입니다. 여기를 읽으면 토큰도 낭비되고 판단도 흐려집니다.

Windows에서 자주 나는 문제

1. /bin/bash 오류

증상:

/bin/bash not found

해결:

bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts" status

qmd 래퍼 대신 TypeScript 진입 파일을 직접 실행합니다.

2. 한글 깨짐

증상:

���, ì..., Ã...

해결:

. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1

깨진 문자열은 복사해서 문서에 재사용하지 않습니다. 원본 명령을 UTF-8 환경에서 다시 실행합니다.

3. OneDrive 파일 잠금

증상:

database is locked
permission denied

대응:

• OneDrive 동기화가 끝난 뒤 다시 실행합니다.
• 가능하면 qmd DB나 캐시를 동기화 폴더 밖에 둡니다.
• 동시에 여러 인덱싱 작업을 실행하지 않습니다.

4. 검색 결과가 너무 많음

원인:

• mask가 너무 넓음
• 빌드 산출물 포함
• 컬렉션 루트가 너무 상위 폴더

대응:

collection add . --name mouseco-hub --mask "**/*.{ts,tsx,js,mjs,json,md,mdx,css}"

필요한 확장자만 포함합니다.

5. 검색 결과가 비어 있음

점검:

• 현재 폴더가 맞는가
• 컬렉션이 등록되어 있는가
• embed를 실행했는가
• mask가 너무 좁지 않은가
• 검색어가 파일 내용과 너무 동떨어져 있지 않은가

qmd와 rg의 역할 차이

qmd가 있다고 rg가 필요 없어지는 것은 아닙니다.

도구	강한 상황	예시
rg	정확한 문자열, 파일명, 코드 심볼	rg "ThemeToggle"
qmd search	문서/마크다운 키워드 검색	search "배포"
qmd vsearch	의미 기반 탐색	vsearch "글머리표가 안 보이는 문제"
qmd query	질문형 후보 찾기	query "관리자 페이지 표 스타일"

실무에서는 보통 이렇게 씁니다.

qmd로 후보 영역을 찾는다.
rg로 정확한 심볼을 좁힌다.
필요한 파일만 읽는다.

이 프로젝트에서 추천하는 탐색 루틴

콘텐츠 작업

1. Supabase 원문 확인
2. docs/treasure-rewrites 초안 확인
3. content/treasures 샘플 검색
4. 공식 자료 검색
5. 초안 파일 작성
6. DB 반영 전 사용자 검수

프론트엔드 작업

1. qmd query로 관련 라우트/컴포넌트 후보 확인
2. rg로 CSS module/class 검색
3. 실제 파일 읽기
4. 최소 수정
5. 브라우저/빌드 검증

배포 작업

1. git status로 변경 범위 확인
2. 커밋에 넣을 파일과 제외할 파일 분리
3. build 또는 국소 검증
4. 배포
5. 배포 URL 확인

qmd는 배포 자체를 하는 도구가 아닙니다. 배포 전에 어디를 수정했는지 파악하는 데 쓰는 도구입니다.

qmd 인덱스 품질 체크리스트

• 컬렉션 루트가 너무 상위 폴더가 아닌가
• node_modules, .next, out, build가 제외되어 있는가
• 한글 출력이 깨지지 않는가
• 최근 추가 문서가 embed에 반영되어 있는가
• 검색 결과가 너무 오래된 파일에 치우치지 않는가
• qmd 결과를 그대로 믿지 않고 실제 파일을 확인했는가
• 민감 파일이나 환경변수를 인덱싱하지 않았는가

에이전트에게 붙이는 복사용 지시문

현재 환경은 Windows PowerShell이다.
qmd 작업 전에는 반드시 다음 부트스트랩을 로드한다.
. C:\Users\mouse\.codex\scripts\utf8-bootstrap.ps1

qmd는 래퍼 명령 대신 아래 진입 파일을 bun으로 직접 실행한다.
bun "C:\Users\mouse\.bun\install\global\node_modules\qmd\src\qmd.ts"

탐색 순서:
1. status
2. search 또는 query
3. 후보 파일만 직접 읽기

주의:
- 깨진 한글 출력은 재사용하지 않는다.
- .next, node_modules, out, build는 근거로 보지 않는다.
- 사용자가 특정 파일 경로를 준 경우에는 qmd보다 해당 파일 확인을 우선한다.

마무리

qmd의 가치는 "검색 도구 하나 더"가 아닙니다. AI 작업에서 가장 비싼 낭비인 불필요한 읽기를 줄이는 데 있습니다.

특히 이 프로젝트처럼 문서, 포스트, 코드, 배포 설정, 한글 경로가 함께 있는 저장소에서는 탐색 규칙이 없으면 세션마다 같은 파일을 다시 읽고, 같은 실수를 반복합니다.

qmd는 AI에게 지도를 주는 도구입니다. 지도만 보고 공사하면 안 되지만, 지도 없이 땅을 파는 것보다는 훨씬 낫습니다.

참고 문헌

• tobi/qmd GitHub README
• 로컬 문서: C:\Users\mouse\OneDrive\Documents\mouseco\python\11.Landing Page\qmd-windows-guide.md