Holmes LabAgentic Software Engineering Architect

로컬 의미 검색과 품질 확인

로컬 모델 준비, 실제 추론, 현재 코드의 검색 범위를 따로 확인합니다. 클라우드는 기본으로 사용하지 않습니다.

가이드 검토 기준: Holmes-Kit 0.40.0 · 2026-11-05 · 설치 대상: 실행 시점의 latest

준비 사항·검증 범위·설치 방식 비교

시작하기 전에

  • 기초 과정을 마친 내 작업 폴더와 연결된 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

현재 계층과 범위를 확인한다

모델 다운로드와 로컬 리소스 사용 여부를 결정합니다.

확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-key status
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-key status
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

node "$HolmesCli" semantic-key status
확인한 프로젝트의 터미널Claude Code CLI · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent claude
확인한 프로젝트의 터미널Codex CLI · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent codex
확인한 프로젝트의 터미널AGY CLI · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent antigravity
확인한 프로젝트의 터미널Claude Code CLI · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent claude
확인한 프로젝트의 터미널Codex CLI · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent codex
확인한 프로젝트의 터미널AGY CLI · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" doctor --target . --agent antigravity
확인한 프로젝트의 터미널Claude Code CLI · windows

내 작업 폴더의 터미널

node "$HolmesCli" doctor --target . --agent claude
확인한 프로젝트의 터미널Codex CLI · windows

내 작업 폴더의 터미널

node "$HolmesCli" doctor --target . --agent codex
확인한 프로젝트의 터미널AGY CLI · windows

내 작업 폴더의 터미널

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

로컬 모델을 준비한다

네트워크와 디스크 사용을 검토한 뒤 실행합니다.

확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-setup
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-setup
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

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

오프라인 추론을 실행한다

명령이 끝날 때까지 기다리고 종료 상태를 확인합니다.

확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-check
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" semantic-check
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

node "$HolmesCli" semantic-check

예상 결과 — 실제 출력을 직접 확인하세요

  • 실제 추론 성공 또는 구체적 실패가 기록됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

캐시가 변경되었거나 추론 시간이 초과됩니다.

semantic-setup으로 캐시를 검증·복구한 뒤 재검사합니다. 준비만 된 상태를 활성 계층으로 표시하지 않습니다.

에이전트가 할 일 · 용어 설명

유한하고 정규화된 1024차원 벡터 검증 결과를 확인합니다. 다른 환경의 성공을 내 머신 성공으로 옮기지 않습니다.

MCP
AI가 Holmes 도구를 호출하는 연결입니다.
REQ → H-SPEC → A-SPEC → T-SPEC
요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
훅 / binding
실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.

단계 4 / 4

실제 질문으로 검색을 점검한다

파일명을 말하지 않는 실제 유지보수 질문을 고릅니다.

AI CLI에 전달할 프롬프트공통

에이전트에게 요청

파일명 없이 이 동작을 담당하는 코드를 찾아줘. lexical 후보와 semanticAlternates를 분리하고 실제 함수·호출 근거로 검증해. 클라우드 키는 설정하지 마.

예상 결과 — 실제 출력을 직접 확인하세요

  • 후보별 실제 근거와 검색 한계가 표시됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

의미적으로 비슷하지만 책임이 다른 파일이 상위에 나옵니다.

코드를 읽고 제외합니다. 클라우드가 필요하면 전송 내용·비용·요청 한도의 별도 동의를 먼저 받습니다.

에이전트가 할 일 · 용어 설명

semantic-key status에서 기존 cloud opt-in도 확인합니다. 로컬만 사용하려는 작업에 클라우드가 설정돼 있으면 전송 전에 선택을 확인하고 키를 자동 변경하지 않습니다.

MCP
AI가 Holmes 도구를 호출하는 연결입니다.
REQ → H-SPEC → A-SPEC → T-SPEC
요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
훅 / binding
실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.

내 프로젝트에 적용

로컬 벡터 검증과 검색 품질은 별개입니다. 이 안내는 특정 recall 수치나 내 코드에서의 성능 향상을 주장하지 않으며 실제 질의로 확인하도록 합니다.

연결된 사례 ↗

내 프로젝트에 적용하기

명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.