처음 설치부터 검증된 첫 변경까지
세 가지 설치 방식의 영향을 비교하고 공통 실습에서 승인된 명세와 RED/GREEN을 따라갑니다.
가이드 검토 기준: Holmes-Kit 0.40.0 · 2026-11-05 · 설치 대상: 실행 시점의 latest
CLI·OS·설치 방식을 선택하면 해당 명령만 표시합니다. 이 페이지는 컴퓨터를 검사하거나 명령을 실행하지 않습니다.
AGY CLI 일반 연동은 지원 대상입니다. 0.40.0의 AGY run start는 거절되므로 이 오케스트레이션 편에는 실행할 AGY 시작 절차가 없습니다. 다른 CLI를 직접 선택하거나 기본편을 확인하세요.
준비 사항·검증 범위·설치 방식 비교
시작하기 전에
- Node.js 20 이상·npm·Git과 Claude Code CLI / Codex CLI / AGY CLI 중 하나. 새 연습 폴더를 사용합니다.
요구·설계·테스트·코드와 실행 결과를 함께 검토할 수 있습니다.
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 연결 시 사용자 수준 설정을 변경할 수 있습니다.
공통 실습 시작 파일 ZIP 받기 ↓ · AI에게 설치를 맡기려면 ↗
단계 1 / 10
준비 도구와 연습 폴더 확인
공통 실습 ZIP을 새 폴더에 풀고 package.json이 있는 폴더에서 터미널을 엽니다. 기존 프로젝트에 덮어쓰지 않습니다. Node.js 20 이상·npm·Git과 사용할 Claude Code CLI, Codex CLI 또는 AGY CLI가 필요합니다. CLI가 없으면 공식 설치 문서를 먼저 확인합니다. 이 새 연습 폴더에서 npm install과 npm test로 기존 테스트 1개 PASS를 확인한 뒤 git init과 명시된 네 파일만 git add하여 변경 비교 기준을 준비합니다. 커밋은 필요하지 않습니다. npm 설치나 테스트가 실패하면 여기서 중단합니다.
내 작업 폴더의 터미널
pwd
node --version
npm --version
git --version
npm install
npm test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md내 작업 폴더의 터미널
Get-Location
node --version
npm.cmd --version
git --version
npm.cmd install
npm.cmd test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md내 작업 폴더의 터미널
pwd
node --version
npm --version
git --version
npm install
npm test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md예상 결과 — 실제 출력을 직접 확인하세요
- 현재 위치가 새 연습 폴더이며 도구 버전이 출력됩니다. 초기 파일은 기존 이름 인사 동작을 담습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
경로가 다르거나 파일이 이미 있으면 중단하고 다른 빈 폴더를 사용합니다. ARM Linux는 공개 패키지의 지원 Node 버전을 확인합니다.
에이전트가 할 일 · 용어 설명
현재 절대경로와 기존 파일을 읽고, 준비되지 않은 항목을 구분합니다. 아직 기존 프로젝트를 수정하지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 2 / 10
설치 방식을 선택한다
아래에서 선택한 설치 방식만 실행하고 latest 조회 버전과 실제 설치 버전이 같은지 확인하세요. 한 줄씩 결과를 읽으며 진행합니다.
보조 선택지 · 별도 사용자 폴더
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"2. 프로젝트 로컬
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"3. 전역 npm
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"보조 선택지 · 별도 사용자 폴더
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
npm.cmd install --prefix "$env:USERPROFILE/holmes-tools/$HolmesVersion" "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path $env:USERPROFILE "holmes-tools/$HolmesVersion/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"2. 프로젝트 로컬
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
npm.cmd install --save-dev --save-exact "@holmes-lab/holmes-kit@$HolmesVersion"
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (Get-Location) "node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"3. 전역 npm
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
npm.cmd config get prefix
# Continue only if the prefix is writable by your user.
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
npm.cmd install --global "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (npm.cmd root --global) "@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"보조 선택지 · 별도 사용자 폴더
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"2. 프로젝트 로컬
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"3. 전역 npm
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"예상 결과 — 실제 출력을 직접 확인하세요
- Resolved latest와 Verified installed의 버전이 같습니다. 0.40.0은 문서 기준이며 설치 버전 고정이 아닙니다.
예상과 다르거나 막혔다면
EPERM, ETARGET 또는 네이티브 모듈 오류가 발생합니다.
EPERM은 사용자 소유 로컬 경로를 사용합니다. ETARGET은 --prefer-online으로 메타데이터를 갱신합니다. 네이티브 오류는 doctor 진단 후 해당 의존성만 복구합니다.
에이전트가 할 일 · 용어 설명
설치 명령은 HOLMES_SKIP_MODEL_INSTALL=1을 명령 범위에만 적용하고 원래 환경을 복원합니다. 모델 준비는 심화편으로 미룹니다. 설치 위치와 AI 도구의 사용자 수준 설정 변경은 별개입니다.
이 문서는 0.40.0 기준으로 검토했습니다. 아래 직접 설치 경로는 latest입니다. 가이드 기준 버전 사용과 도구별 변경 여부를 먼저 상담하려면 AI용 설치 가이드를 사용하세요. 실제 설치는 실행 시점의 npm latest를 조회하여 확인한 버전을 사용하고 그 값을 기록합니다. 최신 공식 문서의 Node·플랫폼·모델 다운로드 정책을 먼저 확인하세요. 각 작업 폴더(each workspace)의 설치 방식은 직접 선택하며 전역 설치의 공유 영향을 검토합니다. Windows Program Files 등 관리자(administrator) 권한 경로는 쓰기 권한을 먼저 확인하고 권한 상승 대신 선택한 사용자 경로를 사용합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 3 / 10
선택한 AI CLI 연결
설치한 CLI의 init --help·doctor --help와 해당 버전의 공식 README를 먼저 읽습니다. 0.40.0 기준 예제와 옵션·모드·모델 정책·설정 범위가 다르거나 확인되지 않으면 설정 적용 전에 멈춥니다. 미리보기로 변경 파일을 검토한 뒤 적용합니다. 새 프로젝트는 guardrail 모드와 자율 승인 없음으로 시작합니다. Codex의 사용자 수준 설정 등 다른 프로젝트에 미치는 영향도 확인합니다.
미리보기 · 파일 변경 없음 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy미리보기 · 파일 변경 없음 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy미리보기 · 파일 변경 없음 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy미리보기 · 파일 변경 없음 · Claude Code CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · Claude Code CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent claude --mode guardrail --no-autonomy
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · Codex CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · Codex CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent codex --mode guardrail --no-autonomy
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · AGY CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · AGY CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent antigravity --mode guardrail --no-autonomy
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy미리보기 · 파일 변경 없음 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy미리보기 · 파일 변경 없음 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run적용 · 미리보기 검토 후 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy예상 결과 — 실제 출력을 직접 확인하세요
- 설정 변경을 검토했고 선택한 CLI의 새 세션을 열었습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
기존 wiring이나 승인이 필요한 변경이면 공식 거절 안내를 따릅니다. --force를 임의로 추가하거나 신뢰를 자동 승인하지 않습니다.
에이전트가 할 일 · 용어 설명
기존 설정을 보존합니다. 연결 후 이 폴더에서 선택한 CLI를 새로 엽니다. Codex는 /hooks에서 신뢰를 직접 검토합니다. 적용 없이 미리보기만 했으면 연결 완료로 보고하지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 4 / 10
설치와 실제 연결을 따로 확인
선택한 CLI의 doctor 결과를 읽습니다. doctor는 준비 진단이며 현재 대화의 연결 증거는 아닙니다.
내 작업 폴더의 터미널
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내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent claude내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent codex내 작업 폴더의 터미널
node "$HOLMES_CLI" doctor --target . --agent antigravity에이전트에게 요청
내 연습 프로젝트의 실제 절대경로와 harness claude로 workspace_preflight를 호출해. root·spec store·빌드 일치와 실제 훅 관찰을 구분해. 미확인은 미확인으로 보고해.에이전트에게 요청
내 연습 프로젝트의 실제 절대경로와 harness codex로 workspace_preflight를 호출해. root·spec store·빌드 일치와 실제 훅 관찰을 구분해. 미확인은 미확인으로 보고해.에이전트에게 요청
내 연습 프로젝트의 실제 절대경로와 harness antigravity로 workspace_preflight를 호출해. root·spec store·빌드 일치와 실제 훅 관찰을 구분해. 미확인은 미확인으로 보고해.예상 결과 — 실제 출력을 직접 확인하세요
- 현재 root·명세 저장소·빌드가 일치합니다. 훅 관찰 여부는 별도로 표시됩니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
mismatch나 오래된 서버이면 편집하지 말고 올바른 프로젝트에서 재연결합니다. doctor의 별도 프로세스를 현재 세션으로 표시하지 않습니다.
에이전트가 할 일 · 용어 설명
새 세션에서 실제 root와 harness로 workspace_preflight를 호출합니다. AGY의 값은 antigravity입니다. 현재 세션에 도구가 없으면 재시작 필요로 남깁니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 5 / 10
공통 예제의 변경 요구 정하기
greet 함수는 Ada에 Hello, Ada!를 반환합니다. 이 동작을 유지하고 이름 앞뒤 공백을 제거하며 빈 문자열·공백 이름에는 Hello, World!를 반환하도록 요청합니다.
에이전트에게 요청
이 연습 프로젝트의 greet가 이름 앞뒤 공백을 제거하고 빈 문자열·공백이면 World를 쓰게 해줘. Ada의 기존 Hello, Ada!는 유지해. 먼저 requirement_triage를 persist:true로 실행하고 분류와 계보, 최신 근거를 보여줘. 아직 코드는 수정하지 마.예상 결과 — 실제 출력을 직접 확인하세요
- 관찰 가능한 성공 조건과 현재 요구의 분류가 있습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
ambiguous나 오래된 결과이면 원인을 해결하고 새로 분류합니다. 실제 반환되지 않은 ID를 만들지 않습니다.
에이전트가 할 일 · 용어 설명
정확한 요청으로 requirement_triage를 persist:true로 실행하고 계보와 최신 근거를 설명합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 6 / 10
요구와 설계 작성·승인
범위·입출력·성공 조건을 읽고 실제 승인 요청을 결정합니다.
에이전트에게 요청
분류에 맞는 명세 계보를 공식 도구로 준비해. greet의 기존 이름 처리 유지, 공백 정리, 빈 이름의 World와 바꿀 파일을 작성하고 승인 전에 보여줘. 반환된 실제 ID만 사용해.예상 결과 — 실제 출력을 직접 확인하세요
- 현재 내용으로 승인된 A-SPEC과 실제 ID가 있습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
spec_next 또는 spec_remediate로 순서를 확인합니다. 세션 승인 미지원이면 실제 요청 ID·대상을 운영자에게 보여주고 공식 승인 경로를 따릅니다.
에이전트가 할 일 · 용어 설명
분류에 맞는 REQ→H-SPEC→A-SPEC을 공식 도구로 만들고 TODO를 작성한 뒤 봉인합니다. 아직 구현하지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 7 / 10
승인된 설계로 코드 검사 활성화
guardrail은 기본 모드이며 명세 기반 코드 검사와 다릅니다. 승인된 A-SPEC을 확인한 뒤 전환 미리보기·요구된 운영자 승인·적용·재연결을 진행합니다.
미리보기 · 파일 변경 없음 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force미리보기 · 파일 변경 없음 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force미리보기 · 파일 변경 없음 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force미리보기 · 파일 변경 없음 · Claude Code CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent claude --mode governed --no-autonomy --force --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · Claude Code CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent claude --mode governed --no-autonomy --force
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · Codex CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent codex --mode governed --no-autonomy --force --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · Codex CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent codex --mode governed --no-autonomy --force
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · AGY CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}적용 · 미리보기 검토 후 · AGY CLI
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
$env:HOLMES_SKIP_MODEL_INSTALL = "1"
node "$HolmesCli" init --target . --agent antigravity --mode governed --no-autonomy --force
if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
$env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}미리보기 · 파일 변경 없음 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force미리보기 · 파일 변경 없음 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force미리보기 · 파일 변경 없음 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run적용 · 미리보기 검토 후 · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force예상 결과 — 실제 출력을 직접 확인하세요
- 선택한 CLI의 governed 설정과 재연결 결과가 확인됩니다. 실제 차단 미관찰은 그대로 표시합니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
승인된 A-SPEC이 없으면 전환하지 않습니다. 승인 거절을 우회하거나 다른 하네스로 바꾸지 않습니다.
에이전트가 할 일 · 용어 설명
기존 연결 변경에 --force가 필요하며 공식 승인을 대신 발급하지 않습니다. 선택한 CLI를 재시작하고 설정 상태와 실제 enforcement 관찰을 따로 보고합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 8 / 10
테스트에서 먼저 실패 확인
기존 Ada 동작과 공백·빈 이름을 검증할 테스트를 읽습니다.
에이전트에게 요청
승인된 greet 변경의 maintenance_analyze를 persist:true로 저장해. 실제 A-SPEC ID의 @implements를 테스트 첫 줄에 넣어 Ada·공백이 있는 Ada·빈 문자열·공백 문자열을 검증해. test_run으로 assertion RED를 기록하고 수집 오류와 구분해. 소스는 아직 바꾸지 마.예상 결과 — 실제 출력을 직접 확인하세요
- 수집 성공 후 새 동작 assertion이 실패하며 공식 RED 근거가 있습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
import·문법 오류는 RED가 아닙니다. 환경을 고치고 같은 동작 assertion을 실행합니다.
에이전트가 할 일 · 용어 설명
maintenance_analyze를 persist:true로 저장합니다. 테스트 첫 줄에 실제 A-SPEC ID의 // @implements 앵커를 넣고 공식 test_run으로 assertion RED를 기록합니다. 이 단계에서 원래 greet 소스는 바꾸지 않습니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 9 / 10
테스트 명세 승인 후 최소 구현
실패 근거와 대응 T-SPEC을 검토하고 공식 승인 요청을 결정합니다.
에이전트에게 요청
RED를 재현한 대응 T-SPEC을 공식 승인한 후, greet 소스 첫 줄에 실제 A-SPEC ID의 @implements를 넣고 공백 정리와 World 기본값을 최소 구현해. 같은 test_run으로 GREEN과 기존 Ada 회귀를 기록해. 승인이나 성공 로그를 만들어내지 마.예상 결과 — 실제 출력을 직접 확인하세요
- 같은 테스트가 통과하고 기존 이름 동작을 유지합니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
assertion을 약하게 하여 통과시키지 않습니다. 요구와 실제 실패 원인을 다시 확인합니다.
에이전트가 할 일 · 용어 설명
T-SPEC 승인 후 소스 첫 줄에도 실제 A-SPEC ID 앵커를 넣고 greet를 최소 수정합니다. 같은 test_run으로 GREEN과 회귀를 기록합니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
단계 10 / 10
근거 확인 후 내 프로젝트에 적용
git status의 새 파일과 git diff의 변경, 실제 테스트 로그를 함께 확인합니다. untracked 파일은 diff에 나오지 않으므로 에이전트에게 개별 내용을 검토하도록 요청하고 node_modules나 비밀 파일을 stage하지 않습니다.
내 작업 폴더의 터미널
git status --short
git diff --stat
git diff --check
git diff -- src/greet.js tests/greet.test.js에이전트에게 요청
greet의 실제 RED/GREEN·회귀·diff와 미검증 범위를 정리해. 문법 오류를 RED로, 준비 진단을 실제 enforcement로 표시하지 마. 내 기존 프로젝트 적용은 별도 범위로 제안하고 배포하지 마.예상 결과 — 실제 출력을 직접 확인하세요
- 요구·명세·테스트·구현 근거를 설명하고 다음 적용 경로를 선택할 수 있습니다.
예상과 다르거나 막혔다면
예상 결과와 다르거나 공식 거절이 나옵니다.
미해결 중요 항목은 남겨 두고 완료로 포장하지 않습니다.
에이전트가 할 일 · 용어 설명
검토 묶음을 만들고 독립 검토와 자기 검토를 구분합니다. 기존 코드에 명세가 없다면 도입 편, 이미 명세가 있으면 요구 관리 편으로 연결합니다. 배포·push는 별도 결정입니다.
- MCP
- AI가 Holmes 도구를 호출하는 연결입니다.
- REQ → H-SPEC → A-SPEC → T-SPEC
- 요구 → 상위 설계 → 구현 설계 → 테스트 명세입니다. 실제 반환된 ID를 사용합니다.
- 훅 / binding
- 실행 전후 검사 / 현재 세션이 의도한 프로젝트·서버와 연결됐는지 확인하는 것입니다.
공통 실습: greet 함수
이 ZIP은 기존 이름 인사 동작을 담은 재현용 시작 파일입니다. 명세나 승인 ID는 포함하지 않습니다. 빈 이름 처리 요구를 내 환경에서 RED/GREEN으로 검증하며, 화면의 예상 결과는 실제 실행 기록이 아닙니다.
실습 시작 파일 받기 ↗내 프로젝트에 적용하기
명세 없는 기존 코드는 도입 편으로, 명세가 있는 프로젝트의 새 변경은 요구 관리 편으로 이어가세요. 다른 심화편은 각 선행 조건을 확인합니다.