Holmes LabAgentic Software Engineering Architect

역할과 검토가 있는 실행

독립 작업 트리에 실행을 열고 단계 전환과 검토 정책을 명시합니다.

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

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

시작하기 전에

  • 기초 과정을 마친 내 작업 폴더와 연결된 MCP 세션. 이 터미널에서 설치 단계의 HOLMES_CLI 또는 PowerShell HolmesCli 경로를 정의하고 파일·버전을 확인합니다.
  • 운영자가 준비한 작업 트리와 승인된 구현 범위

run의 빌드·단계·검토 상태를 확인하고 공식 stop 절차로 종료합니다.

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

하네스 지원과 작업 트리를 확인한다

독립 작업 트리와 허용 범위, 검토자를 준비하고 Codex는 main checkout 또는 작업 트리가 신뢰된 상태인지 확인합니다.

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

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

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

내 작업 폴더의 터미널

node "$HolmesCli" run --help
AI CLI에 전달할 프롬프트공통

에이전트에게 요청

0.40.0 run start --provision의 Claude/Codex 조건을 확인해. Codex의 신뢰된 checkout, 무시된 .codex/config.toml과 사용자 수준 훅을 각각 점검해. AGY run start는 미지원으로 표시하고 비밀값이나 전역 훅을 복사하지 마.

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

  • 지원 하네스, 신뢰, 설정 경로와 실제 진입점이 각각 확인됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

AGY, 추적되는 설정 파일, 신뢰 누락 또는 실행 배선이 거절됩니다.

거절을 우회하지 말고 운영자가 공식 설정과 네이티브 신뢰를 준비한 뒤 새 세션으로 확인합니다.

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

Codex provision은 Git에서 무시된 .codex/config.toml의 MCP 표만 씁니다. 게이트는 사용자 수준 훅에 남습니다. MCP와 PreToolUse/Stop이 실제 Holmes-Kit 패키지 진입점을 실행하는지 확인합니다.

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

단계 2 / 4

범위와 검토 정책으로 실행을 연다

실제 작업 트리와 A-SPEC ID, 검토 라운드 한도를 결정합니다.

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

에이전트에게 요청

설치된 run start 도움말에 따라 실제 worktree, 선택한 engine claude 또는 codex, 승인된 scope, --provision, --review-base에 작업 시작 기준 commit, --review-rounds 3, --strict-review로 실행 계획을 만들어 보여줘. 시작 후 실제 run ID와 stop key를 기록해.

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

  • 실제 run ID, 고정 빌드, 검토 정책이 출력에 있습니다. --review-base는 HEAD의 조상이어야 하며 해당 범위의 실패 라운드는 여러 run에 걸쳐 집계됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

일부 설정이나 빌드가 충돌합니다.

부분 준비를 성공으로 표시하지 말고 출력된 충돌을 해결한 뒤 상태를 확인합니다.

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

현재 도움말로 정확한 start 인자를 구성하여 검토받고, 출력의 실제 run ID와 stop key를 사용자에게 안전하게 전달합니다.

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

단계 3 / 4

단계에 맞게 작업한다

역할별 산출물과 독립 검토자를 확인합니다.

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

에이전트에게 요청

실제 run ID의 status를 확인하고 현재 단계의 허용 작업만 진행해. 다음 transition 전에 필요한 산출물·승인·독립 검토를 확인하고 거절 코드를 보존해.

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

  • 단계 전환과 산출물, 검토가 연결되어 있습니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

review.unresolved 또는 단계 위반으로 중단됩니다.

미해결 findings를 고치거나 운영자에게 보고합니다. 라운드 한도를 늘려 결함을 숨기지 않습니다.

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

현재 run status를 보고 공식 transition으로 이동합니다. 자기 검토나 임의 하위 에이전트 실행을 허가로 해석하지 않습니다.

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

단계 4 / 4

검토 결과를 묶고 실행을 닫는다

미해결 중요 항목과 변경 범위를 확인합니다.

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

에이전트에게 요청

현재 run의 독립 검토와 commit 범위가 맞는지 확인해. review gate와 merge-ready package의 미해결 항목을 보고하고 실제 stop key로 공식 종료 절차를 진행해. 키는 공개 로그에 남기지 마.

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

  • 실행 종료 상태와 검토의 남은 제한이 확인됩니다.
수동 학습 기록이며 실제 환경의 자동 검증 결과가 아닙니다.
예상과 다르거나 막혔다면

stop key가 없거나 검토 대상 커밋이 다릅니다.

운영자가 보관한 시작 기록과 실제 commit 범위를 확인합니다. 키나 검토 결과를 만들어내지 않습니다.

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

현재 설치의 review status/gate/mrp로 근거를 확인하고 run stop을 실제 stop key로 수행합니다.

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

내 프로젝트에 적용

이 가이드는 run 정책을 설명하는 개념 예시입니다. Holmes Lab 주요 메뉴 복원을 오케스트레이터로 실행했다거나 Codex provisioning을 검증했다고 주장하지 않습니다.

연결된 사례 ↗

내 프로젝트에 적용하기

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