id: vhk-readme date: 2026-06-08 tags: [vhk, cli, readme, v2.14.1, mcp, proof, ai-coding]

VHK — Vibe Harness Kit

v2.14.1

모델·에이전트를 뭘로 바꿔도 안 무너지는 풀사이클 AI 코딩 하네스.

Claude Code든 Cursor든 그 위에 얹어 리뷰·검증·기억을 한 루프로 돌리고, 쓸수록 규칙이 쌓여 이 개발자에게 맞게 진화합니다. 한국어 우선.

30초 시작 · VHK vs 맨 에이전트 · 핵심 루프 · 명령 전체

[!NOTE] VHK는 새 코딩 에이전트가 아닙니다. 이미 쓰는 에이전트를 감싸 "무엇을 하기로 했는지 · 정말 끝났는지 · 다음 세션이 어디서 이어질지"를 repo 안의 파일과 CLI 게이트로 고정하는 하네스입니다. 모델이 바뀌어도 규칙·기억·게이트는 repo에 남습니다.

명령어를 외우지 않아도 됩니다. vhk만 실행하면 한국어 메뉴가 열리고, vhk 저장해줘·vhk 다음 목표·vhk 출고점검 같은 자연어도 라우팅합니다.

이렇게 돌아갑니다 — vhk doctor (실제 출력)

🩺 개발 환경 점검

  🟢 Node     v24.13.0 (shim-safe)
  🟢 pnpm     11.17.0
  🟢 git      2.53.0 (user configured)
  🟢 VHK      v2.14.1 (최신)
  🟢 MCP      35 tools 등록

  📁 프로젝트 파일 확인:
    ✅ RULES.md   ✅ COMMANDS.md   ✅ package.json   ✅ .gitignore

  🔀 설정 불일치(drift) 점검 (규칙·맥락 어긋남):
    ✅ 규칙 파일이 RULES.md와 일치
    ⚠️ .vhk/context.md 가 현재 코드보다 낡았어요 — vhk context 로 갱신하세요

  🎉 개발 환경 준비 완료!

━━━ 다음에 이것만 하세요 ━━━
  vhk work

• 왜 VHK인가
• 30초 시작
• VHK vs 맨 에이전트
• 핵심 루프
• 오토파일럿 /vhk-auto
• 명령 전체 (MCP 35 tools · 명령 표면)
• 자연어 예시
• 보안과 개인정보
• 요구 사항
• 개발 · 배포 · Pro · 라이선스

왜 VHK인가

VHK는 AI 코딩에서 반복되는 문제를 repo 안의 파일과 게이트로 고정합니다.

30초 시작

npm install -g @byh3071/vhk    # 또는 1회성: npx -y @byh3071/vhk
vhk --version

# 새 프로젝트: 기술 스택을 알면 바로 확정
vhk start --stack "Vite, React, TypeScript"

# 아직 모르면 후보로 시작하고 첫 세션에서 확정
vhk start

# 기존 프로젝트에 하네스와 PR 검사 얹기
vhk init -y --ci
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
vhk sync
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
vhk mcp-init

Node.js 22 이상이 필요합니다. vhk start --stack "..."은 지정한 기술 스택을 확정값으로 기록합니다. --stack을 생략하면 자동 감지·유형 프리셋은 후보로만 기록되고 기존 NEEDS_CUSTOMIZATION 첫 세션 인터뷰에서 먼저 확인합니다. 아이디어부터 검증하려면 vhk gate로 시작하세요.

vhk init --ci는 .github/workflows/vhk-gate.yml을 만들고 PR마다 검증·규칙·공개 경계 검사를 실행합니다. 기존 GitHub Actions 워크플로가 있으면 파일을 건드리지 않고 병합 방법을 안내합니다. GitHub에서 병합을 실제로 막으려면 저장소 Settings → Rules에서 상태 검사 VHK Gate를 필수로 지정하세요.

기존 프로젝트에서 vhk init을 실행하면 여러 규칙 파일의 같은 관리 구역은 한 번만 가져옵니다. 같은 이름인데 내용이 다르거나 BEGIN/END 표시가 깨진 구역은 자동으로 고르지 않고, 원본을 그대로 둔 채 복구 방법과 함께 중단합니다.

설치가 끝나면 규칙 파일 연결 수와 함께 핵심 규칙의 출처·버전을 따로 보여줍니다. VHK 내장 기본 규칙으로 대신한 경우에는 사용자 규칙 파일이 연결된 상태가 아님을 마지막 설치 점검에서 다시 경고합니다.

선택: 사용자 규칙 YAML 연결

VHK는 다른 저장소 없이 독립 실행됩니다. 별도 규칙이 필요하면 YAML 파일을 직접 연결하세요.

vhk config set-rules-file C:\rules\team-rules.yaml
# 또는 현재 프로세스 시작 전에 VHK_RULES_FILE 환경변수로 지정

VHK vs 맨 에이전트

VHK는 에이전트를 대체하지 않습니다 — 에이전트가 못 하는 반복·기억·게이트를 담당해 그 위를 채웁니다.

핵심 루프

1. 규칙 포터빌리티 — 에이전트를 갈아타도 규칙은 그대로

RULES.md 한 벌을 원천으로 두고 8개 타겟을 생성·갱신합니다: .cursorrules, CLAUDE.md, .windsurfrules, .github/copilot-instructions.md, .agents/rules/vhk-rules.md, AGENTS.md, GEMINI.md, .clinerules/vhk-rules.md.

vhk sync
vhk sync --check   # 검사만 — 재생성 결과 차이와 필수 섹션 누락을 따로 확인 (문제 시 exit 1, 쓰기 0)

모든 도구가 반드시 읽어야 하는 안전 절은 제목에 표시합니다. 목록은 코드에 따로 적지 않고 RULES.md의 이 표시에서 가져옵니다. 파생 파일 하나에서 절이 빠지면 sync --check가 누락으로 잡습니다.

## 안전 규칙 <!-- vhk:sync=all -->

vhk sync --check에서 미연결 섹션이 나오면 출력에 표시된 표준 말을 제목에 넣거나, 위처럼 제목 뒤에 <!-- vhk:sync=all -->을 붙이세요. 검사 결과가 실제 미연결 섹션명과 VHK가 인식하는 표준 제목을 함께 보여줍니다.

규칙 줄에 짧은 검사 ID를 붙이면 vhk check가 대응하는 스크립트를 실행하고 검사 비율을 보여줍니다. ID는 영문 소문자·숫자·하이픈만 사용합니다. .mjs가 있으면 먼저 실행하고, 없을 때 .sh를 찾습니다.

- execSync 신규 사용 금지 <!-- vhk:check=no-exec-sync -->

scripts/check-rule-no-exec-sync.mjs

vhk check
vhk check --json   # declaredRules·checkedRules·uncheckedRules·coveragePercent 포함

2. Goal과 HARD_STOP

Goal은 goals/*.md와 scripts/check-goal-<id>.mjs를 연결합니다. vhk goal done은 게이트를 다시 돌려 통과할 때만 DONE으로 전이합니다. 선택 필드 depends_on: 1,2를 쓰면 두 Goal이 모두 DONE이 되기 전에는 다음 작업이나 완료 대상으로 선택되지 않습니다. 블로커가 반복되면(3건 누적) .vhk/HARD_STOP으로 진행을 멈춥니다.

vhk goal next
vhk goal done --id 42
vhk blocker "테스트가 같은 원인으로 계속 실패"

Goal Phase/Task를 읽기 전용으로 보기

Goal 본문을 아래 정확한 문법으로 나누면 vhk context --json이 상태와 Phase 장벽을 JSON으로 투영합니다. Phase와 Goal 전체의 Task 번호는 각각 양수·고유·오름차순이면 되고 결번을 허용합니다. Phase/Task는 선택 사항이라 Phase가 없는 legacy Goal도 계속 읽습니다.

### Phase 10
- [x] **Task 100** 구현 / 증거: sample-evidence
- [ ] **Task 105** `(na)` 제외 이유

### Phase 30
- [ ] **Task 220** 검증 / evidence: sample-report

(na)는 Task 라벨 직후의 정확한 backticked 토큰만 인정하며 [x]/[X]와 함께 쓰면 구조 오류입니다. / 증거:와 / evidence:는 같은 선택적 hint일 뿐 완료 증명이 아닙니다. malformed Phase와 유효한 Phase 밖의 Task는 구조 오류입니다. Phase가 없는 legacy Goal은 valid: true, activeGoal.phases: [], activeGoal.tasks: []로 투영하고 NO_PHASES warning을 담아 exit 0으로 끝납니다. completed와 notApplicable은 terminal, 첫 Phase의 pending Task는 ready입니다. 이후 Phase의 pending Task는 직전 Phase의 모든 Task가 terminal이면 ready, 아니면 waiting입니다. 첫 Phase의 dependsOn은 비어 있고 이후 각 Task는 직전 Phase의 모든 goal:N/task:N string ID를 가집니다. 같은 Phase의 Task는 서로 의존하지 않아 함께 ready일 수 있지만 자동 병렬 실행을 보장하지 않습니다.

이 명령은 성공·실패 모두 파일을 쓰지 않습니다. 구조·flag·공개 경계 오류는 원문·절대경로·stack을 노출하지 않고 valid: false, activeGoal: null, 안정적인 errors JSON과 exit 1로 끝납니다. vhk context --compact --json도 같은 안전한 오류 계약을 따릅니다. 공개 경계가 차단하는 입력은 시크릿·토큰·키, 홈 절대경로, 개인 이메일·실명·저장소명, 실제 외부 객체 ID입니다. 차단된 입력 원문은 오류에 다시 노출하지 않으며, 예시는 sample-*, <HOME>, 명백히 가짜 ID만 사용합니다. --compact --json 충돌은 valid: false와 exit 1인 flag 구조 오류입니다.

3. 증거와 자기검증 — "실행했다"와 "완료됐다"를 분리

vhk verify     # 게이트 실행 → 확인이 필요한 항목의 경과 시간·숨긴 횟수 표시 + .vhk/reports/latest.json
vhk verify --dismiss lint-gate  # 현재 알림 숨기기(같은 문제가 다시 발생하면 다시 표시)
vhk review     # 최신 증거와 goal 완료조건 교차검증
vhk receipt    # 4대 기계증거(tsc/test/build 종료코드·git dirty·stale SHA·diff-cover)로 완료 보고 검증 (LLM 0)
vhk preflight  # 2FA·shim·env·lint·type·test·git·branch·docs freshness 출고 전 점검

허위 완료 보고 적발 데모 — 실제 출력

AI가 "구현 완료했습니다!"라고 말했지만 실제로는 테스트가 깨져 있고 커밋도 안 한 상황. vhk receipt 한 번이면 기계증거로 잡힙니다 (2026-07-18 실캡처):

🧾 검증 리포트 (receipt)
────────────────────────────────────────────
  판정: 🔴 BLOCK
  HEAD: adb79f9  ·  작업시작: adb79f9  ·  게이트: FAIL

   • 게이트 실패(실종료코드 ≠ 0): test — red
   • working tree 가 dirty — 미커밋/untracked 변경 있음(자기파일 제외 후에도)

  📄 영수증: .vhk\receipts\2026-07-18-block-025956.json

  🔴 기계증거가 "됐어요"와 모순 — 아직 완료 아님.

30초 재현: 아무 프로젝트에서 vhk receipt --mark-start → 코드 수정(커밋 X, 테스트 깨진 채) → vhk receipt. 판정은 종료코드·git dirty·SHA 같은 기계증거 기반이며 LLM 추론이 아닙니다 — 그래서 "그럴듯한 말"에 안 속습니다. (한계도 정직하게: 게으른 허위 완료 보고를 잡는 도구지, 그럴듯하게 틀린 코드까지 잡지는 못합니다.)

4. 기억·패턴·자가진화 — 쓸수록 이 개발자에게 최적화

세션마다 도메인·맥락·의도·교훈이 .vhk/memory.json(repo-local)에 쌓이고, 그게 다시 규칙으로 승격돼 에이전트에 주입됩니다. 어떤 에이전트를 써도 프로젝트 맥락을 점점 더 정확히 이해하게 됩니다.

vhk learn "비-TTY 명령은 프롬프트 없이 실패해야 한다"
vhk pattern detect      # 반복되는 실패/성공 신호와 새 규칙 후보를 바로 표시
vhk evolve suggest      # 현재 7일 후보 계산(저장 안 함) — apply는 사람 확인 필수
vhk stats               # 패스율/차단율/진화 적용율/자율 완주율/병목 계측 (읽기 전용, 병목은 gh 필요)

규칙 후보는 별도 큐에 쌓이지 않습니다. 패턴이 생긴 뒤 7일 동안만 표시되고, apply·reject·undo로 결정하거나 되돌린 결과만 로컬 로그에 남습니다. 조회·JSON·MCP 경로는 RULES.md를 자동으로 바꾸지 않습니다.

🤖 오토파일럿 스킬 /vhk-auto (1단계 MVP)

VHK 프로젝트에서 active goal 1개를 혼자 한 바퀴 돌리고 멈춰 보고하는 클로드 코드 스킬입니다.

• 하는 일: 앵커 재주입(loop-brief+remind) → 개발(TDD) → vhk verify 결정론 게이트 → /code-review 적대검증 → 합격 시 작은 commit → 끝나면 핵심 보고.
• 안전(1단계 한계): 외부 발송·이슈 등록·gh 호출을 하지 않습니다. commit만 자동(push·PR·publish 금지). 문제는 "이슈 초안 텍스트"로만 보고합니다.

2단계 로드맵: CLI vhk auto + MCP vhk_auto로 승격 시 이슈 자동등록(safeExecFile gh·dedupe·undo 승인 패턴·secure 강제)이 결정론 코드로 추가됩니다.

명령 전체

처음에는 vhk --help 또는 vhk help로 기본 명령만 보세요. 마케팅·커머스 명령까지 포함한 전체 명령은 vhk help --all에서 볼 수 있습니다. 기본 목록에서 숨긴 명령도 삭제되지 않아 이름을 직접 입력하면 그대로 실행됩니다.

대화형 본질이 강하거나 상태 전이가 큰 명령은 CLI 전용입니다: gate, start, init, goal, mission set, design, theme, evolve apply/reject/undo.

자연어 예시

보안과 개인정보

[!TIP] VHK에서 LLM은 결정 경로가 아니라 검토·요약 보조입니다. verify/receipt 같은 게이트 판정은 tsc·test·build 종료코드 등 기계 증거로 내리고, 되돌릴 수 없는 작업(발송·결제·publish)은 사람이 실행합니다.

• VHK는 기본 local-first입니다. 로그·맥락·기억은 repo와 .vhk/에 남습니다.
• .env와 민감 파일은 .gitignore·secure scan·preflight에서 계속 확인합니다.
• vhk cloud push는 GitHub secret gist를 사용하며 토큰은 코드나 설정에 저장하지 않습니다.
• memory.json·refs.json·HARD_STOP 같은 개인/상태 파일은 기본 백업 제외 대상입니다.
• 취약점은 공개 이슈에 세부 정보를 올리지 말고 SECURITY.md의 비공개 제보 절차를 이용하세요.

요구 사항

• Node.js >= 22, Git
• 선택: gh CLI (vhk cloud push/pull 사용 시), pnpm/yarn/npm 중 프로젝트 패키지 매니저

Windows PowerShell에서 실행 정책 때문에 pnpm이 막히면 pnpm.cmd를 사용하세요.

개발

pnpm.cmd install
pnpm.cmd run build
pnpm.cmd run test:run

prepublishOnly는 publish 전에 빌드·테스트·npm 공개 경계 검사·High 이상 의존성 감사를 모두 실행합니다.

npm.cmd login
pnpm.cmd run prepublishOnly
npm.cmd publish --access public

일반 개발 중에는 vhk publish나 npm publish를 실행하지 마세요. 릴리스 담당자가 version, changelog, tag, npm dist를 확인한 뒤 실행합니다.

Pro (관심 실측 중)

VHK 코어는 MIT로 영구 무료입니다. 아래는 팀/다중 프로젝트용 Pro 후보이며, 수요를 먼저 확인하고 만듭니다.

• 팀 규칙 레지스트리 — RULES.md를 여러 사람·레포에 클라우드 동기화
• 패턴/교훈 클라우드 — 여러 레포의 memory/pattern을 통합
• 비용 가드 대시보드 — 다중 프로젝트 예산·사용량 집계

필요하면 이슈에 pro 라벨로 남겨주세요. 관심 3건이면 만듭니다.

라이선스

MIT - LICENSE

Repository: https://github.com/byh3071-cpu/vhk · Site: https://yohanstudio.co/vhk