memory-layer-mcp 0.5.0__py3-none-any.whl

hybrid_search/__init__.py

@@ -0,0 +1,3 @@
+"""Hybrid Search MCP Server — BM25 + Vector search with cross-language support."""
+
+__version__ = "0.1.0"

hybrid_search/_skills/bootstrap-wiki.md

@@ -0,0 +1,150 @@
+---
+name: bootstrap-wiki
+description: "프로젝트의 코드베이스를 분석하여 wiki 페이지를 자동 생성합니다. hybrid_search 인덱스 + MCP 도구를 활용하여 주요 모듈/기능별 wiki를 만듭니다."
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, mcp__hybrid-search__hybrid_search
+---
+
+# Bootstrap Wiki
+
+프로젝트의 코드베이스를 분석하여 `.hybrid-search/wiki/` 디렉토리에 wiki 페이지를 자동 생성합니다.
+
+## 실행 절차
+
+### 1. 인덱싱 완료 확인 (필수)
+
+**인덱싱이 완료될 때까지 절대 Step 2로 넘어가지 말 것.**
+
+```bash
+hybrid-search-mcp status
+```
+
+상태를 확인하고:
+- 인덱스가 없거나 파일 수가 0이면 → 인덱싱 실행 후 **완료될 때까지 대기**
+- 인덱스가 있지만 파일 수가 프로젝트 규모에 비해 너무 적으면 → `--force` 재인덱싱
+
+```bash
+# 인덱싱 실행 (완료까지 대기 — 백그라운드로 보내지 말 것)
+hybrid-search-mcp index {project_root} --force
+```
+
+**인덱싱이 "Done: +N added" 메시지를 출력할 때까지 다음 단계로 진행 금지.**
+
+### 2. 페이지 목록 확정 (기계적, 판단 금지)
+
+Step 2a: 디렉토리 스캔으로 페이지 목록 생성
+```bash
+ls {project_root}/
+ls {project_root}/app/ 또는 src/ 또는 lib/
+```
+
+Step 2b: 디렉토리별 파일/하위폴더 수를 세어서 페이지 수를 결정한다.
+
+```bash
+for dir in app services components hooks lib types database src; do
+  [ -d "{project_root}/$dir" ] && echo "$dir: $(find {project_root}/$dir -maxdepth 1 -type d | wc -l) subdirs, $(find {project_root}/$dir -maxdepth 2 -name '*.ts' -o -name '*.tsx' -o -name '*.py' | wc -l) files"
+done
+```
+
+**페이지 수 결정 규칙:**
+
+1. **architecture.md** — 항상 1개
+2. **작은 디렉토리 (하위폴더 5개 미만, 파일 10개 미만)** → 디렉토리당 1페이지
+3. **중간 디렉토리 (하위폴더 5~15개)** → 도메인 그룹별 2~5페이지로 분리
+4. **큰 디렉토리 (하위폴더 15개+)** → 하위폴더/도메인마다 개별 페이지
+
+**최소 페이지 수 가이드라인:**
+- 파일 100개 미만: 10~20페이지
+- 파일 100~500개: 20~40페이지
+- 파일 500개+: 40~80페이지
+
+Step 2c: **목록을 사용자에게 보여주고 확인받은 후 진행**
+
+### 3. Wiki 디렉토리 생성 + .gitignore
+
+```bash
+mkdir -p {project_root}/.hybrid-search/wiki
+```
+
+`.gitignore`에 `.hybrid-search/` 추가 (없으면 생성).
+
+### 4. 병렬 Agent로 페이지 동시 생성
+
+확정된 목록을 Agent로 병렬 실행합니다. 한 메시지에 여러 Agent를 동시 호출.
+
+각 Agent에게 전달할 프롬프트 템플릿:
+```
+프로젝트: {project_name} ({project_root})
+Wiki 페이지 생성: {filename}.md
+주제: {topic_description}
+관련 디렉토리: {directory_path}
+
+다음을 수행하세요:
+1. hybrid_search MCP 도구로 "{topic_keywords}" 검색
+2. Glob으로 {directory_path}/ 하위 파일 목록 확인
+3. 핵심 파일 1-2개를 Read로 읽기
+4. {project_root}/.hybrid-search/wiki/{filename}.md 작성
+
+형식:
+# {title}
+> 마지막 업데이트: {today} | 상태: fresh
+## 개요 (1-2줄)
+## 핵심 파일 (backtick 경로 + 역할)
+## 데이터 흐름 (가능하면 ASCII 다이어그램)
+## 주의사항
+
+작성 원칙: 200줄 이하, 코드 덤프 아님, 시그니처만, 경로는 실제 존재하는 파일만.
+```
+
+한 번에 최대 5개 Agent 병렬 실행. 5개 초과 시 배치로 나누기.
+
+### 5. 병렬 완료 후: index.md 생성
+
+```markdown
+# Wiki Index
+
+> 프로젝트: {name} | 페이지: {count}개 | 생성: {YYYY-MM-DD}
+
+## 페이지 목록
+- [architecture](architecture.md) -- 전체 아키텍처 개요
+- [{module}]({module}.md) -- {1줄 설명}
+
+## 커버리지 gap
+{아직 wiki가 없는 디렉토리/모듈 목록}
+```
+
+### 6. DB 동기화 (필수)
+
+```bash
+hybrid-search-mcp sync-wiki --cwd {project_root}
+```
+
+### 7. CLAUDE.md 연동
+
+프로젝트의 CLAUDE.md에 `<!-- hybrid-search -->` 마커 추가.
+
+### 8. post-commit hook 설치
+
+```bash
+hybrid-search-mcp install-hook --cwd {project_root}
+```
+
+### 9. 검수 Agent 실행 (필수)
+
+누락된 파일이 있으면 해당 파일만 추가 Agent로 생성합니다.
+
+### 10. 최종 결과 보고
+
+```
+Wiki Bootstrap 완료
+- 확정 목록: N개
+- 생성 완료: N개 (100%)
+- DB 동기화: N개
+- CLAUDE.md 연동: 완료
+- post-commit hook: 설치됨
+```
+
+## 주의사항
+
+- Step 2의 페이지 목록을 100% 생성할 때까지 완료 보고 금지
+- wiki 생성 전 반드시 hybrid_search 인덱스가 최신인지 확인
+- Step 6(sync-wiki)를 건너뛰면 staleness 추적이 작동하지 않음

hybrid_search/_skills/maintain.md

@@ -0,0 +1,196 @@
+---
+name: maintain
+description: "hybrid-search 인덱스와 wiki를 유지보수합니다. delta reindex + stale wiki 갱신(LLM synthesis 자동 실행) + wiki gaps 생성 + CLAUDE.md 최신화."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Maintain — 일상 유지보수
+
+검색과 분리된 유지보수 스킬. delta reindex + synthesis 자동화 + wiki gaps를 한 번에 처리한다.
+인덱스 자체가 깨졌거나 불일치가 의심되면 `/rebuild-index`를 대신 사용할 것.
+
+**핵심 원칙**: post-commit hook이 `reindex --synthesize`를 자동 실행하므로
+`_synthesis_input/*.md`는 이미 쌓여있을 수 있다. 이 스킬은 거기서부터 이어받아
+**LLM synthesis → finalize**까지 자동으로 돌린다.
+
+**needs_synthesis flag 관리**: 이 스킬이 Step 2 → Step 4를 완료하면
+`.hybrid-search/needs_synthesis` flag가 자동으로 사라진다. Step 2의 reindex는
+stale이 0이면 flag를 제거하고, Step 4의 finalize는 합성 후 남은 stale을 기준으로
+flag를 갱신하거나 삭제한다. 수동으로 지울 필요 없음.
+
+## Step 1: 상태 확인
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+# hybrid-search-mcp 파이썬 경로: setup이 기록한 MCP 등록에서 읽는다.
+VENV=$(python3 -c "import json,pathlib;print(json.load(open(pathlib.Path.home()/'.claude.json'))['mcpServers']['hybrid-search']['command'])" 2>/dev/null)
+if [ -z "$VENV" ]; then
+  for dir in ~/project/claude_project/hybrid-search-mcp ~/projects/hybrid-search-mcp ~/hybrid-search-mcp; do
+    [ -f "$dir/.venv/bin/python" ] && VENV="$dir/.venv/bin/python" && break
+  done
+fi
+"$VENV" -m hybrid_search.cli status --cwd "$PROJECT_ROOT"
+```
+
+## Step 2: Delta Reindex + Synthesis Prepare
+
+```bash
+"$VENV" -m hybrid_search.cli reindex --synthesize --cwd "$PROJECT_ROOT"
+```
+
+- 변경된 파일만 재인덱싱 (delta)
+- stale wiki 감지 → `_synthesis_input/*.md` 자동 생성
+- hook이 이미 돌렸으면 "no changed files"로 빠르게 끝남
+
+## Step 3: Synthesis 병렬 실행 (신규 — Sonnet 에이전트)
+
+`.hybrid-search/wiki/_synthesis_input/`에 `.md` 파일이 있으면 **Sonnet 에이전트를 모듈당 1개씩 병렬 spawn**한다.
+
+### 3-1. input 파일 목록 확인
+
+```bash
+ls "$PROJECT_ROOT/.hybrid-search/wiki/_synthesis_input/"*.md 2>/dev/null
+```
+
+파일이 없으면 Step 4로 건너뜀.
+
+### 3-2. 병렬 Agent 호출
+
+input 파일 각각에 대해 Agent를 **한 메시지에 병렬로** 호출한다.
+
+```
+Agent({
+  description: "Synthesize wiki: <module>",
+  subagent_type: "general-purpose",
+  model: "sonnet",
+  prompt: <아래 템플릿>
+})
+```
+
+**에이전트 프롬프트 템플릿** (파일마다 경로만 교체):
+
+```
+다음 hybrid-search wiki synthesis 작업을 수행해줘.
+
+[입력 파일] <ABSOLUTE_PATH>/.hybrid-search/wiki/_synthesis_input/<module>.md
+[출력 파일] <ABSOLUTE_PATH>/.hybrid-search/wiki/_synthesis_output/<module>.md
+
+작업 절차:
+1. 입력 파일을 Read로 읽는다. 파일에는 이미 아래가 포함되어 있다:
+   - SYNTHESIS_INSTRUCTIONS (반드시 따를 규칙)
+   - Deterministic Wiki (구조 데이터 — 절대 부정하지 말 것)
+   - Source Code (실제 코드 청크)
+   - Related Module Summaries
+2. 입력 파일 안의 "Rules"와 "Output ONLY these sections" 지시를 그대로 따른다.
+3. 결과물(## Overview, ## Key Design Decisions, ## Data Flow, ## Caveats, ## Related Modules만)을
+   출력 파일에 Write로 저장한다. 제목(# ...)이나 metadata는 포함하지 않는다.
+4. 파일:라인 인용(`file.py:L42`)은 입력 파일의 Source Code 섹션에 실제로 나온 것만 사용한다.
+   존재하지 않는 심볼이나 파일은 인용하지 않는다 (verify가 제거함).
+5. 기존 wiki의 언어(한국어 / 영어)를 그대로 유지한다.
+
+완료되면 간단히 "done: <module>" 만 보고. 추가 설명 불필요.
+```
+
+**병렬 실행 예시** (input 파일 3개가 있으면):
+
+```
+메시지 하나에 Agent 호출 3개를 담아 보낸다.
+subagent_type="general-purpose", model="sonnet".
+description은 "Synthesize wiki: <module-name>" 형태로 각기 다르게.
+```
+
+input 파일이 많으면(5개 초과) 최대 5개씩 batch로 묶어 순차 병렬 실행한다.
+모든 에이전트 완료까지 기다린 후 Step 3-3으로 진행.
+
+### 3-3. Output 파일 존재 확인
+
+```bash
+ls "$PROJECT_ROOT/.hybrid-search/wiki/_synthesis_output/"*.md 2>/dev/null
+```
+
+에이전트 하나라도 실패해서 output이 빠져있으면 해당 모듈만 재시도(다시 Agent spawn).
+
+## Step 4: Finalize (검증 + DB 병합)
+
+```bash
+"$VENV" -m hybrid_search.cli synthesize-wiki --finalize --cwd "$PROJECT_ROOT"
+```
+
+- `_synthesis_output/*.md`를 읽어 `verify_references`(존재하지 않는 파일:라인 제거) + `verify_symbols` 실행
+- `merge_synthesis_with_structure`로 deterministic wiki와 병합
+- DB `wiki_pages` 업데이트 + `_raw/<module>.raw.md` 백업
+- input/output 파일 자동 정리
+
+## Step 5: 안전망 — verify + auto-fix
+
+```bash
+"$VENV" -m hybrid_search.cli verify-synthesis --fix --cwd "$PROJECT_ROOT"
+```
+
+병합된 wiki에서 잔존 bad refs를 한 번 더 제거.
+
+## Step 6: Wiki Gaps 채우기
+
+`.hybrid-search/wiki-gaps.txt`가 있으면:
+
+1. gap 목록 확인 — wiki가 없는 모듈/디렉토리
+2. 중요도 판단: 파일 3개 이상인 디렉토리만 대상
+3. `/bootstrap-wiki`와 동일한 형식으로 새 wiki 페이지 생성
+4. `index.md` 갱신
+
+gap이 3개 이상이면 Sonnet Agent 병렬로 생성.
+
+## Step 7: DB 동기화 (gaps 생성 시에만)
+
+gap으로 새 wiki를 만들었으면:
+
+```bash
+"$VENV" -m hybrid_search.cli sync-wiki --cwd "$PROJECT_ROOT"
+```
+
+finalize는 이미 DB에 썼으니 이 단계는 gap 생성 시에만 필요.
+
+## Step 8: CLAUDE.md 확인
+
+프로젝트의 CLAUDE.md에 `<!-- hybrid-search -->` 마커가 있는지 확인.
+- 있으면: 의도 기반 라우팅 표가 최신인지 확인
+- 없으면: 새 라우팅 표 삽입
+
+## Step 9: Confidence 재캘리브레이션 (인덱스가 크게 변했을 때만)
+
+reindex 결과가 대규모(변경 파일이 수백 개 이상, 또는 force rebuild 직후)이면
+confidence 임계값이 새 점수 분포와 어긋날 수 있다. 프로젝트용 gold 배터리가
+있으면 재캘리브레이션한다:
+
+```bash
+# 배터리 탐색: 프로젝트 로컬 → hybrid-search-mcp 레포 순.
+HSDIR=$(dirname "$(dirname "$(dirname "$VENV")")")
+GOLD="$PROJECT_ROOT/.hybrid-search/router_gold.json"
+[ -f "$GOLD" ] || GOLD=$(ls "$HSDIR"/benchmarks/router_calibration/*_gold.json 2>/dev/null | head -1)
+[ -n "$GOLD" ] && "$VENV" -m hybrid_search.cli recalibrate \
+  --cwd "$PROJECT_ROOT" --gold "$GOLD"
+```
+
+- `strong_score`/`weak_score`/`strong_gap` 백분위와 `cosine_anchor`(중앙값)를
+  `~/.hybrid-search/config.toml`에 갱신한다.
+- 배터리는 실제 사용자가 칠 법한 탐색형 질문이어야 함 — 쉬운 쿼리만 모으면
+  임계값이 과대해져 false-weak이 늘어난다.
+- 소규모 delta reindex 후에는 건너뛴다 (분포가 거의 안 변함).
+
+## 결과 보고
+
+```
+Maintain 완료
+- Reindex: +N added, ~N changed, -N deleted
+- Synthesis: N개 모듈 LLM 갱신 (Sonnet 병렬)
+- Finalize: N개 병합, K bad refs 제거
+- Wiki gaps: N개 생성
+- CLAUDE.md: OK
+```
+
+## 주의사항
+
+- **Sonnet 모델 고정**: synthesis 작업은 Opus가 아니라 Sonnet으로. 컨텍스트 격리 + 속도 이득.
+- **에이전트 병렬 호출은 단일 메시지**: Agent tool 호출 여러 개를 한 메시지에 담아야 실제로 병렬 실행됨.
+- **finalize가 verify를 자동 수행**: 에이전트가 환각 ref를 써도 CLI가 제거하니 관대하게 가도 됨. 단 너무 많으면 재시도.
+- **실패 모듈만 재시도**: output 파일이 없는 모듈만 Agent 재spawn. 전체 재실행 금지.

hybrid_search/_skills/rebuild-index.md

@@ -0,0 +1,129 @@
+---
+name: rebuild-index
+description: "인덱스 손상/불일치 시 복구. 상태 진단 → 불일치면 force rebuild, 아니면 delta reindex → 결과 검증."
+allowed-tools: Bash, Read
+---
+
+# Rebuild Index — 인덱스 복구
+
+인덱스에 문제가 있을 때 사용하는 **복구 전용** 스킬.
+`/maintain`이 일상 유지보수(delta reindex + wiki 갱신)라면, `/rebuild-index`는 인덱스 자체가 깨졌을 때 쓴다.
+
+## 역할 구분
+
+| 스킬 | 용도 | 비용 |
+|------|------|------|
+| `/maintain` | 일상 유지보수 — delta reindex + stale wiki + gaps 채우기 | 낮음 (변경분만) |
+| `/rebuild-index` | 인덱스 복구 — 손상/불일치 진단 + 필요시 full rebuild | 높음 (전체 재임베딩) |
+
+## 언제 사용하는가
+
+- 검색 결과가 이상하거나 인덱스 손상이 의심될 때
+- ConsistencyMismatchError가 발생했을 때
+- auto-rebuild가 실패해서 최신 변경이 미반영될 때
+- embedding 설정이나 chunking 로직이 변경된 후
+
+## Step 1: 상태 진단
+
+현재 프로젝트의 인덱스 상태와 3-store 일치 여부를 확인한다.
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+# hybrid-search-mcp 파이썬 경로: setup이 기록한 MCP 등록에서 읽는다.
+VENV=$(python3 -c "import json,pathlib;print(json.load(open(pathlib.Path.home()/'.claude.json'))['mcpServers']['hybrid-search']['command'])" 2>/dev/null)
+if [ -z "$VENV" ]; then
+  for dir in ~/project/claude_project/hybrid-search-mcp ~/projects/hybrid-search-mcp ~/hybrid-search-mcp; do
+    [ -f "$dir/.venv/bin/python" ] && VENV="$dir/.venv/bin/python" && break
+  done
+fi
+"$VENV" -m hybrid_search.cli status --cwd "$PROJECT_ROOT"
+```
+
+추가로 3-store chunk 수를 직접 비교한다:
+
+```bash
+"$VENV" -c "
+from hybrid_search.config import load_config
+from hybrid_search.storage.indexes import get_project_dir, IndexPaths
+from hybrid_search.storage.db import StoreDB
+from hybrid_search.project import project_hash
+import tantivy, usearch.index
+from pathlib import Path
+
+pid = project_hash(str(Path('$PROJECT_ROOT').resolve()))
+config = load_config()
+project_dir = get_project_dir(config.projects_dir, pid)
+idx = IndexPaths(project_dir)
+
+if not idx.store_db.exists():
+    print('인덱스 없음 — delta reindex로 충분')
+else:
+    db = StoreDB(idx.store_db)
+    sqlite = db.get_chunk_count(pid)
+    db.close()
+    t = tantivy.Index.open(str(idx.tantivy_dir))
+    bm25 = t.searcher().num_docs
+    v = usearch.index.Index.restore(str(idx.vector_index))
+    vec = len(v)
+    print(f'SQLite={sqlite}, Tantivy={bm25}, USearch={vec}')
+    if sqlite == bm25 == vec:
+        print('일치 — force rebuild 불필요')
+    else:
+        print('불일치 — force rebuild 필요')
+"
+```
+
+사용자에게 결과를 보고한다.
+
+## Step 2: 판단 분기
+
+### 불일치 발견 → Force Rebuild
+
+전체 파일을 다시 chunking + embedding한다.
+- atomic rebuild로 실행되므로, 실패해도 기존 인덱스는 보존된다
+- 파일 수에 따라 수 분~수십 분 소요된다
+- OpenAI embedding API 비용이 발생한다
+
+```bash
+"$VENV" -m hybrid_search.cli reindex --force --cwd "$PROJECT_ROOT"
+```
+
+파일이 500개 이상이면 백그라운드 실행을 권장한다.
+
+### 불일치 없음 → Delta Reindex
+
+변경된 파일만 재인덱싱한다. 비용이 훨씬 적다.
+
+```bash
+"$VENV" -m hybrid_search.cli reindex --cwd "$PROJECT_ROOT"
+```
+
+### 인덱스 자체가 없음 → 첫 인덱싱
+
+```bash
+"$VENV" -m hybrid_search.cli reindex --cwd "$PROJECT_ROOT"
+```
+
+## Step 3: 결과 검증
+
+rebuild/reindex 완료 후 상태를 다시 확인한다.
+
+```bash
+"$VENV" -m hybrid_search.cli status --cwd "$PROJECT_ROOT"
+```
+
+검증 항목:
+- chunk 수가 합리적인지
+- 에러 없이 완료되었는지
+- 마지막 인덱싱 시간이 방금으로 갱신되었는지
+- (force rebuild 한 경우) 3-store 일치 여부 재확인
+
+결과를 사용자에게 보고한다.
+
+## 주의사항
+
+- force rebuild는 OpenAI embedding API 호출 비용이 발생한다
+- 대형 프로젝트(1000+ 파일)는 수 분 이상 걸린다
+- 실패해도 기존 인덱스는 유지된다 (atomic rebuild)
+- 동시에 다른 reindex가 돌고 있으면 lock file 충돌 가능 — 먼저 확인할 것
+- 단순히 최신 반영이 필요한 거면 `/maintain`을 사용할 것

hybrid_search/_skills/save-wiki.md

@@ -0,0 +1,65 @@
+---
+name: save-wiki
+description: "대화 중 분석한 내용을 wiki 페이지로 저장합니다. .hybrid-search/wiki/에 저장하고 index.md를 갱신합니다."
+allowed-tools: Read, Write, Edit, Glob, Bash
+---
+
+# Save Wiki
+
+대화 중 분석한 내용을 `.hybrid-search/wiki/` 디렉토리에 wiki 페이지로 저장합니다.
+
+## 언제 사용하는가
+
+- 사용자가 "이거 저장해", "wiki에 추가해", "나중에 참고" 등 요청할 때
+- 복잡한 코드 분석을 마친 후 결과를 영구 보존하고 싶을 때
+- 기존 wiki 페이지가 stale이라 업데이트가 필요할 때
+
+## 실행 절차
+
+### 1. 저장할 내용 결정
+
+방금 대화에서 분석/설명한 내용을 기반으로:
+- 제목 결정 (예: "인증 시스템", "학원비 결제 흐름")
+- 파일명 결정 (예: `auth-system.md`, `tuition-billing.md`)
+- 디스크에서 Glob으로 `.hybrid-search/wiki/*.md` 확인하여 중복 체크
+
+### 2. Wiki 파일 작성
+
+`{project_root}/.hybrid-search/wiki/{filename}.md` 에 작성합니다.
+
+형식:
+```markdown
+# {제목}
+
+> 마지막 업데이트: {YYYY-MM-DD} | 상태: fresh
+
+## 개요
+{1-2줄 요약}
+
+## 핵심 파일
+- `path/to/file.ts` -- 역할
+
+## 상세
+{분석 내용}
+
+## 주의사항
+{특이사항}
+```
+
+### 3. index.md 갱신
+
+`.hybrid-search/wiki/index.md`의 페이지 목록에 새 항목을 추가합니다.
+기존 항목을 업데이트하는 경우 날짜만 갱신합니다.
+
+### 4. DB 동기화
+
+```bash
+hybrid-search-mcp sync-wiki --cwd {project_root}
+```
+
+## 작성 원칙
+
+- 대화에서 분석한 내용을 정리하여 작성 (코드 복붙 아님)
+- 파일 경로는 현재 존재하는 파일만
+- 200줄 이하
+- 다음 대화에서 이 wiki만 읽으면 검색 없이 이해할 수 있는 수준

hybrid_search/_skills/search.md

@@ -0,0 +1,104 @@
+---
+name: search
+description: "코드베이스를 검색합니다. 질문 의도에 따라 Wiki(구조)와 hybrid_search(디테일)를 병렬 실행하고, 부족하면 Grep/Read로 보충합니다."
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, mcp__hybrid-search__hybrid_search
+---
+
+# Search — 의도 기반 병렬 검색
+
+코드베이스를 검색하는 통합 스킬. 질문 유형을 판단하고 최적 경로로 검색한다.
+
+**자동 주입:** Claude가 `Grep`/`Glob`을 호출하기 직전, 이 프로젝트에 `.hybrid-search/wiki/index.md`가 있으면 **PreToolUse 훅**이 wiki 우선 탐색을 리마인드한다 (`route_hook`, matcher=`Glob|Grep`). 구조/관계 질문에서 Wiki를 스킵하고 Grep으로 직행하는 경향을 바로잡기 위함.
+
+## Step 0: needs_synthesis flag 체크 (선행)
+
+검색 시작 전 `.hybrid-search/needs_synthesis` 존재 여부를 한 번만 확인한다. 파일이 있으면 최근 커밋으로 wiki가 stale 상태 → 검색 결과에 **오래된 wiki**가 섞일 수 있음을 사용자에게 고지한다.
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+FLAG="$PROJECT_ROOT/.hybrid-search/needs_synthesis"
+if [ -f "$FLAG" ]; then
+  cat "$FLAG"
+fi
+```
+
+- flag가 있으면: 답변 상단에 한 줄 경고 — "⚠ wiki가 stale입니다 (N개 모듈). `/maintain` 실행 후 재질문 권장." (stale_modules 중 상위 3개 미리 보여줘도 됨)
+- 없으면: 조용히 진행. 다음 Step으로.
+- **기능 차단 금지:** 경고만 하고 검색은 그대로 수행. 사용자가 급히 답을 원할 수 있음.
+
+## CLI 단독 사용
+
+Claude Code 없이도 터미널에서 바로 검색 가능:
+
+```bash
+hybrid-search-mcp search "authentication flow"
+hybrid-search-mcp search "인증 로직" --json
+hybrid-search-mcp search "handleSubmit" --node-types function
+hybrid-search-mcp search "schema migration" --file-pattern "*.sql"
+```
+
+## Step 1: 의도 분류
+
+사용자 질문을 아래 5가지 중 하나로 판단한다:
+
+| 유형 | 신호 | 예시 |
+|------|------|------|
+| **구조/관계** | "누가 호출", 의존, 모듈 구조, 전체 그림 | "A가 B를 호출하나?" |
+| **기능 탐색** | 자연어, 한국어, 넓은 기능 질문 | "문제 업로드 기능 설명해줘" |
+| **정밀 조회** | 정확한 심볼명, 파일명, 에러 문자열 | "handleSubmit 어디?" |
+| **설계/맥락** | "왜 이렇게", QA 히스토리, 계획 문서 | "스키마 왜 이래?" |
+| **스키마/DB** | 마이그레이션, DDL, 테이블 구조 변화 | "problems 테이블 히스토리" |
+
+## Step 2: 실행
+
+### 구조/관계 질문
+
+**병렬 실행:**
+- Wiki: `.hybrid-search/wiki/index.md` Read → 관련 페이지 Read (콜그래프, 모듈 관계)
+- hybrid_search: 동시에 시맨틱 검색 실행
+
+두 결과를 합쳐서 답변. Wiki가 구조를 잡고 hybrid_search가 디테일을 채운다.
+
+### 기능 탐색 질문
+
+**병렬 실행:**
+- hybrid_search: 시맨틱 검색 (1차, 코드+문서+계획 문서 크로스 도메인)
+- Wiki: `.hybrid-search/wiki/index.md` Read → 관련 모듈 페이지 확인
+
+hybrid_search 결과가 주축, Wiki는 호출 흐름 보충.
+
+### 정밀 조회 질문
+
+**Grep first:**
+- Grep으로 정확한 심볼/문자열 검색
+- 결과가 부족하거나 맥락이 필요하면 → hybrid_search 또는 Wiki 보충
+
+### 설계/맥락 질문
+
+**hybrid_search first:**
+- hybrid_search로 설계 문서, QA 기록, 계획 문서 검색
+- 관련 모듈 구조가 필요하면 → Wiki 보충
+
+### 스키마/DB 질문
+
+**hybrid_search first:**
+- hybrid_search 호출 시 `file_pattern: "*.sql"` 또는 `node_types` 활용
+- 부족하면 → Grep으로 마이그레이션 디렉토리 직접 탐색
+
+## Step 3: 보충 (fallback)
+
+1차에서 답이 부족하면 도구를 **바꾸지 말고 보충**한다:
+- hybrid_search 결과 부족 → Wiki에서 콜그래프/모듈 관계 확인
+- Wiki 결과 부족 → hybrid_search로 문서/코드 디테일 보충
+- Grep 결과에 맥락 부족 → Read로 파일 전문 확인
+
+## 운영 규칙
+
+- **쿼리는 사용자의 자연어 문장을 그대로** 쓸 것 — 키워드 뭉치로 재작성 금지.
+  (예: "우리 환불 기능에 대해 알려줘" ⭕ / "환불 퇴원 refund 워크플로우 정산" ❌)
+  자연어 문장이 벡터 레인 매칭 품질이 더 좋고(실측: 같은 주제에서 문장은 mixed,
+  키워드 뭉치는 weak), 분류기가 bm25_weight를 자동 조정한다.
+- Wiki `[[링크]]`가 있으면 따라갈 것
+- hybrid_search는 한국어 자연어 질의 가능 (크로스 언어 검색)
+- 심볼명 검색은 BM25가 자동으로 가중치 올림 (자동 감지)
+- `file_pattern`으로 범위 좁히기 가능 (예: `*.ts`, `migrations/*.sql`)