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

VHK — Vibe Harness Kit

Name: vhk
Author: byh3071-cpu

v2.9.0

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

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

node

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

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

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

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

🩺 개발 환경 점검

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

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

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

  🎉 개발 환경 준비 완료!

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

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

왜 VHK인가

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

AI 코딩에서 자주 생기는 문제	VHK가 고정하는 것	대표 명령
도구마다 규칙 파일이 따로 논다	`RULES.md` 한 벌을 여러 에이전트 규칙 파일로 동기화	`vhk sync`
세션이 끊기면 맥락이 사라진다	`.vhk/context.md`, `brief`, `work` 프롬프트로 이어받기	`vhk work`
AI가 "완료"라고 하지만 증거가 빈약하다	verify/review/preflight/testmap으로 증거와 게이트 확인	`vhk verify`
목표가 많아지면 무엇부터 할지 흐려진다	`goals/*.md`와 `docs/state/next-task.md`로 다음 목표 고정	`vhk goal next`
같은 실수가 반복된다	memory/pattern/evolve로 교훈과 룰 후보 축적	`vhk learn`
위험한 상태에서 계속 진행한다	blocker 3건 누적 시 `.vhk/HARD_STOP` 생성	`vhk blocker`
AI 비용이 새는지 모른다	cost 가드로 예산·사용량 추적 + 임계(80% 경고·100% 차단)	`vhk cost`
SEO·수익 확인이 콘솔 여러 개에 흩어져 있다	사이트 등록·자격증명 안전보관·오프라인 리포트로 한곳에 정리(실 제출·수집은 자격증명 연결 후 사람이 실행)	`vhk seo`

30초 시작

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

# 새 프로젝트: git init + 문서 + MCP + 컨텍스트를 한 번에
vhk start

# 기존 프로젝트에 하네스만 얹기
vhk init -y && vhk sync && vhk mcp-init

Node.js 22 이상이 필요합니다. vhk start는 마법사로 초기 셋업 비용을 한 번에 제거하고, 아이디어부터 검증하려면 vhk gate로 시작하세요.

VHK vs 맨 에이전트

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

	맨 에이전트 (Claude Code·Cursor 단독)	일반 CI·eslint	VHK
적대적 코드 리뷰	요청 시 1회·일관성 없음	정적 규칙만	반복 게이트
실행 기반 검증	부분(말로)	테스트만	verify 실행·증거 기록
모델·에이전트 교체 시 규칙·기억	세션과 함께 휘발	해당 없음	규칙 포터·기억 이관
쓸수록 규칙 자가축적	없음	수동 설정	세션마다 자동 적립
한국어 우선	영어 기본	해당 없음	한국어 SoT·자연어 라우팅
릴리스 게이트 강제	없음	통과/실패	preflight·goal 게이트 루프

핵심 루프

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   # 검사만 — 8개 타겟이 RULES.md 와 일치하는지 (drift 시 exit 1, 쓰기 0)

2. Goal과 HARD_STOP

Goal은 goals/*.md와 scripts/check-goal-<id>.mjs를 연결합니다. vhk goal done은 게이트를 다시 돌려 통과할 때만 DONE으로 전이합니다. 블로커가 반복되면(3건 누적) .vhk/HARD_STOP으로 진행을 멈춥니다.

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

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

vhk verify     # tsc/lint/test/build/secure 게이트 실행 → .vhk/reports/latest.json
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 출고 전 점검

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

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

vhk learn "비-TTY 명령은 프롬프트 없이 실패해야 한다"
vhk pattern detect      # 반복되는 실패/성공 신호 탐지
vhk evolve suggest      # 사람이 승인할 RULES.md 후보 생성 (자동 적용 아님 — diff·확인)
vhk stats               # 패스율/차단율/진화 적용율 집계 (읽기 전용)

🤖 오토파일럿 스킬 `/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 강제)이 결정론 코드로 추가됩니다.

명령 전체

MCP 35 tools — vhk mcp-init 후 MCP 클라이언트가 vhk mcp stdio 서버로 호출

그룹	도구
Git/세션	`save`, `undo`, `status`, `diff`, `ship`, `recap`
진단/품질	`doctor`, `check`, `secure`, `audit`, `harness`
환경/규칙	`env`, `env-check`, `sync`, `mcp-init`
컨텍스트/기억	`context`, `context-show`, `brief`, `loop-brief`, `remind`, `memory-list`, `learn`
풀사이클 뒷단	`content`, `launch`, `ops`, `sell`
배포/패키지 안내	`deploy`, `publish`, `migrate`, `update`
레퍼런스	`ref-list`
패턴/진화	`pattern-detect`, `pattern-list`, `evolve-suggest`, `evolve-list`

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

명령 표면 (CLI 전체)

영역	명령	용도
시작	`vhk`, `vhk gate`, `vhk start`, `vhk init`	메뉴, 아이디어 검증, 새 프로젝트 마법사, 하네스 초기화
규칙/맥락	`vhk sync`, `vhk context`, `vhk context-show`, `vhk brief`, `vhk loop-brief`, `vhk remind`, `vhk work`, `vhk work handoff`	규칙 동기화, 프로젝트 맥락 생성, 루프 1틱 의도 앵커, 치명 규칙 재주입, 세션 시작/인수인계
풀사이클 뒷단	`vhk content`, `vhk launch`, `vhk ops`, `vhk sell`	콘텐츠/런칭/운영/판매 초안 프롬프트 생성 (초안만, 게시·발송·결제는 사람이)
Goal	`vhk goal init/list/next/check/done/sync/drift`	단계별 목표, 게이트, 상태 드리프트 관리
Trust	`vhk verify`, `vhk review`, `vhk receipt`, `vhk preflight`, `vhk testmap`, `vhk mission set/show/check/clear`	증거 생성, 거짓완료 탐지, 증거 영수증, 출고 전 점검, 테스트 매핑, 작업 범위 계약
안전	`vhk blocker`, `vhk resume --confirm`, `vhk mode`, `vhk secure scan`	HARD_STOP, safety mode, 시크릿 스캔
Git	`vhk status`, `vhk diff`, `vhk save`, `vhk undo`, `vhk restore`, `vhk recap`	상태/변경 확인, 커밋/푸시, 되돌리기, 세션 로그
환경/품질	`vhk doctor`, `vhk check`, `vhk env`, `vhk env-check`, `vhk harness`, `vhk audit`, `vhk worktree check/add`	개발환경, RULES 린트, env, 통합 품질, 보안 감사, worktree 가드
배포/패키지	`vhk ship`, `vhk deploy`, `vhk publish`, `vhk update`, `vhk migrate`	배포 체크, 배포 실행, npm 릴리스 자동화, 셀프 업데이트, 패키지 매니저 전환
MCP/클라우드	`vhk mcp`, `vhk mcp-init`, `vhk cloud push/pull`	MCP stdio 서버, 클라이언트 설정, `.vhk/` secret gist 백업/복원
기억/학습	`vhk memory`, `vhk learn`, `vhk pattern`, `vhk evolve`, `vhk stats`, `vhk loop`	결정/실패/성공 기억, 교훈, 반복 패턴, 룰 후보, 통계, 자가진화 조율
디자인/레퍼런스	`vhk design`, `vhk design-palette`, `vhk theme`, `vhk ref add/list/open`	디자인 토큰, 테마, 참고 링크 관리
일일 리듬	`vhk standup`, `vhk today`	아침 브리핑, 저녁 회고

자연어 예시

입력	라우팅
`vhk 저장해줘`	`vhk save`
`vhk 뭐 바뀌었어`	`vhk diff`
`vhk 다음 목표`	`vhk goal next`
`vhk 출고점검`	`vhk preflight`
`vhk 보안 스캔`	`vhk secure scan`
`vhk 오늘 한 일 정리`	`vhk recap`
`vhk 인수인계`	`vhk work handoff`

보안과 개인정보

[!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 같은 개인/상태 파일은 기본 백업 제외 대상입니다.

요구 사항

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.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

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