로컬 의미 검색과 품질 확인
로컬 모델 준비, 실제 추론, 현재 코드의 검색 범위를 따로 확인합니다. 클라우드는 기본으로 사용하지 않습니다.
가이드 검토 기준: Holmes-Kit 0.40.0 · 2026-11-05 · 설치 대상: 실행 시점의 latest
CLI·OS·설치 방식을 선택하면 해당 명령만 표시합니다. 이 페이지는 컴퓨터를 검사하거나 명령을 실행하지 않습니다.
AGY CLI 일반 연동은 지원 대상입니다. 0.40.0의 AGY run start는 거절되므로 이 오케스트레이션 편에는 실행할 AGY 시작 절차가 없습니다. 다른 CLI를 직접 선택하거나 기본편을 확인하세요.
준비 사항·검증 범위·설치 방식 비교
시작하기 전에
- 기초 과정을 마친 내 작업 폴더와 연결된 MCP 세션. 이 터미널에서 설치 단계의 HOLMES_CLI 또는 PowerShell HolmesCli 경로를 정의하고 파일·버전을 확인합니다.
- 최초 공개 모델 다운로드를 위한 네트워크 또는 검증된 오프라인 캐시
사용 가능한 의미 계층과 검색 한계를 근거로 설명합니다.
0.40.0 문서 기준 · 2026-11-04 릴리스 계약 검토. 네이티브 실행 근거는 2026-11-01의 0.39.0 기록입니다. macOS 독립 작업 폴더에서 Codex·Claude의 읽기 전용 binding 일치를 관찰했습니다. Claude 훅 이벤트는 있으나 routing 미검증, Codex 훅은 미관찰입니다. 0.40.0 네이티브 재검증과 승인된 작은 변경의 RED/GREEN 검증은 미완료입니다. Windows/Linux는 문서 안내이며 네이티브 검증이 없습니다.
- 1. 별도 사용자 폴더
- 프로젝트 의존성과 전역 npm 설치를 유지하며 버전별로 관리합니다. 설치 경로·업데이트를 별도로 관리합니다. 연결한 프로젝트가 있으면 폴더를 보존해야 합니다.
- 2. 프로젝트 로컬
- 팀·프로젝트별 버전을 잠금 파일로 관리합니다. 공통 실습에 권장합니다. package.json과 잠금 파일을 변경합니다. 비 Node 프로젝트에는 npm 구성이 추가될 수 있습니다.
- 3. 전역 npm
- 여러 프로젝트에서 공통 설치를 사용하기 편리합니다. 쓰기 권한과 업데이트 영향을 확인합니다. 같은 설치를 공유한 프로젝트들에 영향을 줍니다.
패키지 설치 위치와 AI 도구 설정은 별개입니다. 프로젝트 로컬 설치도 Codex 연결 시 사용자 수준 설정을 변경할 수 있습니다.
단계 1 / 4
현재 계층과 범위를 확인한다
모델 다운로드와 로컬 리소스 사용 여부를 결정합니다.
내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-key status내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-key status내 작업 폴더의 터미널
node "$HolmesCli" semantic-key status내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent claude내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent codex내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent antigravity내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent claude내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent codex내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent antigravity내 작업 폴더의 터미널
node "$HolmesCli" doctor --target . --agent claude내 작업 폴더의 터미널
node "$HolmesCli" doctor --target . --agent codex내 작업 폴더의 터미널
node "$HolmesCli" doctor --target . --agent antigravity예상 결과 — 실제 출력을 직접 확인하세요
- unavailable/degraded/unverified 상태가 숨겨지지 않습니다.
예상과 다르거나 막혔다면
계층은 local인데 현재 문서 벡터가 없습니다.
추론 준비와 코드 인덱스 범위를 별개로 진단하고 검색 품질을 검증합니다.
에이전트가 할 일 · 용어 설명
doctor 결과에서 준비·검증·현재 문서 벡터 범위를 구분합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 2 / 4
로컬 모델을 준비한다
네트워크와 디스크 사용을 검토한 뒤 실행합니다.
내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-setup내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-setup내 작업 폴더의 터미널
node "$HolmesCli" semantic-setup예상 결과 — 실제 출력을 직접 확인하세요
- 준비 종료 코드와 검증 결과가 있고 실패 시 기본 그래프 기능은 별도로 확인합니다.
예상과 다르거나 막혔다면
네트워크 또는 sharp 네이티브 모듈 오류입니다.
doctor 원인을 확인합니다. 스크립트 차단이면 설치된 의존성 버전을 검토해 그 패키지만 승인·재빌드하고 다시 준비합니다.
에이전트가 할 일 · 용어 설명
semantic-setup 결과를 읽고 실패를 기록합니다. init에서도 준비가 시도될 수 있으므로 다운로드를 원치 않으면 설치와 init 양쪽에 HOLMES_SKIP_MODEL_INSTALL=1을 적용합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 3 / 4
오프라인 추론을 실행한다
명령이 끝날 때까지 기다리고 종료 상태를 확인합니다.
내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-check내 작업 폴더의 터미널
node "$HOLMES_CLI" semantic-check내 작업 폴더의 터미널
node "$HolmesCli" semantic-check예상 결과 — 실제 출력을 직접 확인하세요
- 실제 추론 성공 또는 구체적 실패가 기록됩니다.
예상과 다르거나 막혔다면
캐시가 변경되었거나 추론 시간이 초과됩니다.
semantic-setup으로 캐시를 검증·복구한 뒤 재검사합니다. 준비만 된 상태를 활성 계층으로 표시하지 않습니다.
에이전트가 할 일 · 용어 설명
유한하고 정규화된 1024차원 벡터 검증 결과를 확인합니다. 다른 환경의 성공을 내 머신 성공으로 옮기지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 4 / 4
실제 질문으로 검색을 점검한다
파일명을 말하지 않는 실제 유지보수 질문을 고릅니다.
에이전트에게 요청
파일명 없이 이 동작을 담당하는 코드를 찾아줘. lexical 후보와 semanticAlternates를 분리하고 실제 함수·호출 근거로 검증해. 클라우드 키는 설정하지 마.예상 결과 — 실제 출력을 직접 확인하세요
- 후보별 실제 근거와 검색 한계가 표시됩니다.
예상과 다르거나 막혔다면
의미적으로 비슷하지만 책임이 다른 파일이 상위에 나옵니다.
코드를 읽고 제외합니다. 클라우드가 필요하면 전송 내용·비용·요청 한도의 별도 동의를 먼저 받습니다.
에이전트가 할 일 · 용어 설명
semantic-key status에서 기존 cloud opt-in도 확인합니다. 로컬만 사용하려는 작업에 클라우드가 설정돼 있으면 전송 전에 선택을 확인하고 키를 자동 변경하지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
내 프로젝트에 적용
로컬 벡터 검증과 검색 품질은 별개입니다. 이 안내는 특정 recall 수치나 내 코드에서의 성능 향상을 주장하지 않으며 실제 질의로 확인하도록 합니다.
연결된 사례 ↗내 프로젝트에 적용하기
명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.