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 / 6

요청 ID로 승인하고 잔여 권한을 확인한다

approve --list --target .에서 대상과 subject를 읽고 운영자 터미널에서 공식 승인 경로로 결정합니다. 에이전트가 grant를 발급하지 않습니다.

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

내 작업 폴더의 터미널

node "$HOLMES_CLI" approve --list --target .
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" approve --list --target .
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

node "$HolmesCli" approve --list --target .
확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

node "$HolmesCli" approve --status --target .
AI CLI에 전달할 프롬프트공통

에이전트에게 요청

목록 번호가 아닌 실제 요청 ID와 subject를 확인해 사람에게 전달해. 승인 명령을 대신 실행하지 말고, 거절·보류·만료·소비 상태를 구분해. 회수 후 status에서 잔여 grant가 없는지 확인해.

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

  • 현재 요청과 결정 대상이 일치하고 단일 사용·만료·회수 상태가 구분됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

접두사가 모호하거나 개발 빌드의 요청으로 표시됩니다.

전체 ID로 대상을 다시 읽습니다. 개발 빌드 요청은 원래 공식 동작을 다시 시도해 현재 버전으로 제출하며 세대 ID를 만들어 붙이지 않습니다.

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

grant는 single-use(단일 사용)이며 허용한 동작이 실패해도 소비됩니다. --deny는 살아 있는 grant를 회수하지 않습니다. 회수에는 --revoke를 사용하고 --status에서 남은 권한을 확인합니다.

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

단계 2 / 6

보호 파일을 명시적으로 검토한다

파일별 변경과 원장 소유자를 확인합니다. full 프로필에서도 변경된 spec 파일은 사람이 정확한 경로로 먼저 stage합니다.

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

에이전트에게 요청

stage 전에 spec·evidence·provenance 파일과 소유 replica를 나눠 보여줘. 사람 승인이 필요한 정확한 경로를 제시하고 포괄 stage나 우회 스크립트를 실행하지 마.

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

  • 보호 파일과 제품 파일의 stage 상태 및 필요한 사람 결정이 구분됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

포괄 stage가 보호 경로나 다른 replica 원장에 도달해 거절됩니다.

원장이나 봉인 내용을 직접 고치지 않습니다. 사람이 spec 경로를 먼저 stage한 뒤 남은 범위를 재확인합니다.

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

git add -A, git add . 또는 git commit -a로 다른 replica 원장까지 쓸어 담지 않습니다. .ax 경로를 실행 중 조합하는 명령도 판정 대상입니다. 거절이 나면 출력된 코드와 공식 복구 경로를 따릅니다.

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

단계 3 / 6

무엇이 실행 중인지 기록한다

이번 운영 대상 프로젝트와 하네스를 정합니다.

확인한 프로젝트의 터미널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
확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" runtime-binding status --workspace .
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" runtime-binding status --workspace .
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

node "$HolmesCli" runtime-binding status --workspace .
AI CLI에 전달할 프롬프트공통

에이전트에게 요청

현재 workspace_preflight와 doctor를 비교해 설치 버전·실행 빌드·root·spec store·stale를 나눠 보고해.

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

  • 설치와 실행 상태가 각각 기록됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

설치 후에도 오래된 서버가 응답합니다.

업그레이드 후 모든 해당 MCP 서버를 재시작하고 새 preflight와 basis_detail에서 loadedBuild와 diskBuild를 비교합니다. runtime-binding status 후 공식 setup --dry-run으로만 미리보고, 사용자 설정 적용은 별도 검토합니다.

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

doctor와 workspace_preflight를 비교해 root, spec store, 버전, serverStale를 기록합니다.

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

단계 4 / 6

운영 지침을 안전하게 갱신한다

미리보기에서 프로젝트 고유 규칙이 보존되는지 확인합니다.

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

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

node "$HolmesCli" guidance check --target .
확인한 프로젝트의 터미널공통 · macos

내 작업 폴더의 터미널

node "$HOLMES_CLI" guidance refresh --target . --dry-run
확인한 프로젝트의 터미널공통 · linux

내 작업 폴더의 터미널

node "$HOLMES_CLI" guidance refresh --target . --dry-run
확인한 프로젝트의 터미널공통 · windows

내 작업 폴더의 터미널

node "$HolmesCli" guidance refresh --target . --dry-run

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

  • 현재 또는 변경 필요 상태가 명확하고 실제 적용 후 새 세션에서 지침을 읽습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

알 수 없는 수정 또는 marker 충돌입니다.

기존 사용자 규칙을 보존하여 수동 검토한 뒤 재시도합니다. --force로 충돌을 숨기지 않습니다.

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

guidance check와 refresh --dry-run을 실행하고 검토 후 공식 refresh를 적용합니다.

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

단계 5 / 6

오류 원인에 맞게 복구한다

오류와 대상 경로를 읽고 필요한 변경만 허용합니다.

확인한 프로젝트의 터미널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
AI CLI에 전달할 프롬프트공통

에이전트에게 요청

doctor의 실제 원인에 맞는 복구만 제안해. 설치 스크립트는 설치된 정확한 버전을 확인해 필요한 의존성만 승인하고, 전역 allow-all 설정은 사용하지 마.

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

  • 수정한 원인과 복구 후 재검사 결과가 연결됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

같은 오류가 반복되거나 다른 패키지 경로를 고쳤습니다.

npx가 선택한 실제 설치와 실행 빌드를 다시 확인합니다. 승인 거절이면 공식 refusal 안내를 따르고 우회 스크립트를 만들지 않습니다.

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

EPERM, scripts-blocked, abi-mismatch, build-failed를 구분합니다. Windows의 실행 정책 오류는 npm.cmd/npx.cmd를 사용합니다.

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

단계 6 / 6

원래 작업을 다시 검증한다

원래 목표와 남은 제한을 확인합니다.

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

에이전트에게 요청

복구 후 새 preflight로 경로를 확인하고 원래 실패한 작업을 다시 수행해. 설정 준비·MCP binding·실제 훅 관찰·작업 결과를 구분해 보고하고 미검증 항목을 남겨.

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

  • 원래 실패가 해결되었는지 실제 결과로 판단할 수 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

binding은 matched지만 훅 실행은 관찰되지 않습니다.

runtime enforcement를 미확인으로 유지하고 지원되는 네이티브 세션 검증을 별도로 수행합니다.

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

새 세션에서 원래 작업을 재개하고 허용·거절·공식 복구·정상 종료 관찰을 구분해 기록합니다.

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

Holmes Lab의 실제 변경 기록

A-SPEC-101.21은 홈에서 숨겨져 있던 기술 여정·작업·실천의 세 주요 메뉴를 복원하고, 그래프 fallback의 JSON 링크를 제거하며 실천 내용을 확장한 변경입니다. docs/evidence/engineering-perspective의 RED·회귀·빌드 기록이 과거 근거입니다. 아래 명령을 내 프로젝트에서 실행하는 것은 재현이며 그 과거 실행 기록이 아닙니다.

연결된 사례 ↗

내 프로젝트에 적용하기

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