Skip to content
BranchesTags

Repository files navigation

VIBE

바이브 코딩은 쉽게. 완료 판정은 기계가.

npm npm downloads Node.js License: MIT

English — Vibe is a verification harness for AI coding agents. It wraps Claude Code, Codex, and Antigravity CLI so that "done" is decided by deterministic gates — test exit codes, run-ledgers, regression memory — instead of the model's self-report. Models already plan and implement well; what's missing is a reason to trust "it's done." Vibe supplies that ground truth: vibe-code fast, but nothing unverified ships. Install with npm install -g @su-record/vibe && vibe init, then throw a natural-language requirement at /vibe — one SPEC approval, then an autonomous ANCHOR→ACT→JUDGE→RECORD loop until the gates pass. (Full docs below are in Korean; the CLI works in any language.)

Vibe는 AI 코딩을 위한 검증 하네스(verification harness) 입니다. 출처가 있는 컨텍스트로 SPEC을 고정하고, 완료 판정을 모델의 자기 보고가 아니라 결정론적 게이트(테스트 exit code, run-ledger, 회귀 기억)에 맡긴 뒤 실행별 Evidence Bundle을 남깁니다. Model Judge는 발견만 제안하고, Human Taste는 release에서만 판단합니다. 빠르게 바이브 코딩하되, 검증 안 된 코드가 나가지 않게.

npm install -g @su-record/vibe
vibe init

Codex CLI에서는 Vibe가 slash command가 아니라 skill로 노출됩니다. /vibe가 보이지 않으면 $vibe, $vibe.spec처럼 호출하거나 /skills에서 vibe를 선택하세요. Claude Code에서는 기존 /vibe.* slash command 흐름을 사용합니다.

철학: 지시하지 않고 검증한다

2026년의 모델에게 "어떻게 일하라"고 가르치는 스캐폴딩은 비용입니다. Vibe v3는 그 층을 걷어냈습니다 — 남긴 것은 모델이 스스로 증명할 수 없는 것들뿐입니다:

  • 테스트가 실제로 통과했는가 — PR 게이트가 테스트 스위트를 직접 실행
  • verify가 실제로 실행됐는가 — .vibe/metrics/run-ledger.json이 코드로 기록
  • 무엇으로 완료를 증명했는가 — .vibe/runs/{run-id}/evidence.json이 Judge 권한과 실행 증거를 기록
  • 리뷰 루프가 수렴하고 있는가 — discover-hash(2라운드 동일 → stuck)가 판정
  • 같은 실수가 반복되지 않는가 — verify 실패가 회귀 테스트로 자동 등록

똑똑한 모델일수록 "다 됐다"는 말이 그럴듯해집니다. 그래서 코드가 판정하는 ground truth는 모델이 강해질수록 더 가치 있습니다.

워크플로우

진입점 하나. 자연어 요구사항만 던지세요. SPEC 1패스 → 승인 1회 → 게이트 통과까지 자동 루프.

/vibe "커피 브랜드 랜딩 페이지" [+ 📎 figma URL / 이미지 / PDF / 파일]
     |
     v
  Intent 분류  ─── new feature? figma-driven? clone? resume? review? regress? ...
     |
     v
  Smart Resume ─── .vibe/{specs,features}/ 감지 ("이어서?")
     |
     v
  SPEC 1패스 ─── 모호할 때만 인라인 질문 → SPEC + BDD 시나리오 생성
     |
     v
  SPEC 확정 1회 승인 ─── 유일한 의무 개입 (Done의 정의 확정)
     |
     v
  루프 ─── ANCHOR→ACT→JUDGE→RECORD (결정론 게이트 통과까지 자동 반복)

예시:

/vibe "패럴랙스 웹사이트 만들어줘"
/vibe "https://figma.com/file/abc 로 로그인 페이지"
/vibe "로그인 회귀 테스트 다시 통과시켜줘"
/vibe "이 SPEC 리뷰만" + 📎 .vibe/specs/login.md

SPEC 1패스 — 구세대의 인터뷰→기획→SPEC→리뷰 4단계는 폐지됐습니다. 모델이 한 번에 SPEC을 만들고, 진짜 갈림길에서만 질문합니다. 승인 게이트는 SPEC 확정 단 하나.

Smart Resume — 아무 단계에서나 멈추고 나중에 돌아오세요. /vibe는 .vibe/ 디렉토리에서 진행 상황을 감지하고 "이어서?" 제안합니다.

루프 기본 실행 — 승인 후 게이트 통과까지 자동 루프. --interactive로 단계별 확인, --max-iter N으로 반복 상한. automationLevel: autonomous(.vibe/config.json)면 비대화형으로 완주합니다.

Advanced — 정확히 어느 phase 실행할지 알면 /vibe.spec, /vibe.figma, /vibe.run, /vibe.verify, /vibe.trace 등을 직접 호출할 수 있습니다.

빠른 시작

# 설치
npm install -g @su-record/vibe

# 프로젝트 초기화 (스택 자동 감지)
cd your-project
vibe init

# AI 코딩 도구 시작 (둘 중 하나)
claude
codex

# 워크플로우 실행
/vibe "사용자 인증 추가"

npm 12 를 쓴다면 — npm 12 는 allowScripts 정책으로 install 스크립트를 기본 차단한다. 그러면 설치는 성공하는데 better-sqlite3 네이티브 바인딩이 빌드되지 않아 메모리·RAG 가 죽는다. vibe upgrade 가 자동 복구하지만, 근본적으로 막으려면 한 번 승인해 두면 된다:

npm config set allow-scripts=@su-record/vibe,better-sqlite3 --location=user

상태는 vibe status 의 Native bindings 행으로 확인한다.

Figma ↔ 코드

양방향. Figma에서 디자인을 읽거나, 기획서에서 Figma에 디자인을 쓰거나.

# READ — 기존 프로젝트에 UI 추가 (프로젝트 컨벤션 준수)
/vibe.figma <figma-url> <figma-url>

# READ — 신규 독립 페이지 (독립 스타일)
/vibe.figma --new <figma-url>

# WRITE — 기획서에서 Figma 디자인 생성
/vibe.figma plan.md --create                 # Full (와이어 + 비주얼 디자인)
/vibe.figma plan.md --create-storyboard      # 와이어만
/vibe.figma plan.md --create-design          # 비주얼 디자인만

READ 동작: Figma REST API로 노드 트리 + 30개 CSS 속성 추출. Auto Layout → Flexbox 1:1 기계적 매핑. 스크린샷은 검증용 — 트리가 원천. 렌더링은 pixelmatch 시각 대조로 게이트.

WRITE 동작: 기획서의 Look & Feel, 레이아웃, 반응형 전략 섹션을 파싱하여 와이어프레임을 먼저 그리고 (구조 검토), 그 위에 디자인 시스템 컴포넌트로 비주얼 적용. 멱등성 보장 — 기획서 수정 후 재실행하면 변경된 섹션만 갱신.

DESIGN.md — 시각 품질 SSOT

CLAUDE.md(코드)·AGENTS.md(빌드) 에 이은 세 번째 SSOT. Google Stitch 9-섹션 표준으로 프로젝트 루트에 위치하며, 외부 AI 에이전트가 직접 읽을 수 있는 휴먼-리더블 시각 규약입니다. Figma 종속 X — Figma 는 4 입력 경로 중 하나일 뿐.

# 4 가지 init 경로 (Figma 없이도 시작 가능)
/vibe.design init                                  # 인터뷰 (디폴트)
/vibe.design init --from=code                      # 기존 코드 토큰 역추출 (Tailwind/CSS-vars/styled-components)
/vibe.design init --from=reference --reference=linear   # awesome-design-md 시드 12 종
/vibe.design init --from=figma --file=<key>        # /vibe.figma 위임 (옵션)

# 라이프사이클
/vibe.design lint                                  # Stitch 9-섹션 완전성 검증
/vibe.design verify                                # 구현 ↔ DESIGN.md hex 토큰 드리프트

자동 통합:

  • /vibe.run — UI 작업 진입 시 DESIGN.md 없으면 1 회 권유 (autonomous silent skip, 절대 블록 X)
  • /vibe.verify — ### 3.2 Visual Drift Detection 으로 hex 하드코딩 P1 검출
  • /vibe.review — #### Visual P1 Baseline — DESIGN.md 우선, 없으면 WCAG AA 폴백
  • /vibe.figma — --emit-design-md 로 READ 산출물을 DESIGN.md 로 출력, WRITE 는 DESIGN.md 톤·팔레트 1 차 입력

v1 범위: hex 컬러 드리프트. spacing / font 드리프트는 Phase 2+

품질 게이트

탐지는 편집 시점에, 차단은 결정론적 게이트에서:

계층 동작
편집 훅 (Edit/Write) 오탐률 낮은 하드룰만 탐지 — any/@ts-ignore, console.log → 모델에 즉시 주입(additionalContext). 함수 길이·중첩 같은 휴리스틱은 없음 — 모델이 컨텍스트 안에서 더 정확히 판단
결정론 게이트 PR 테스트 게이트(PR 생성 전 테스트 스위트 직접 실행, gh pr create 포함) · auto-commit verify 게이트(verify 통과 전 커밋 거부) · Stop 훅 verify-skip 경고/차단 · scope-guard(opt-in, SPEC 범위 밖 편집 감시) · sentinel(파괴적 명령·하네스 자기 수정 차단)
노드 게이트 게이트를 파이프라인 끝에만 두지 않음 — SPEC Code Guard가 승인 전에 하류 요구사항(REQ-ID·Stakes·Done Criteria·미치환 placeholder)을 검사하고, 실패하면 SPEC 작성으로 되돌림(backward edge)
사람 게이트 게이트 객체 — 대기 중인 질문을 디스크(.vibe/gates/)에 남겨 세션이 끊겨도 무엇을 묻는지 살아남음. 비용 게이트 — 되돌릴 수 없는 지출(유료 생성)과 이상 규모 팬아웃 직전에만 승인 요청(평상시 규모는 통과)
리뷰 + 수렴 루프 code-reviewer를 관점(focus)별 병렬 인스턴스로 실행(correctness/architecture/performance/data-integrity/…) + security-reviewer. P1=0까지 루프하되 수렴은 discover-hash가 판정 — 2라운드 동일 findings면 stuck으로 확정하고 사람에게 질문. 절대 조용히 넘어가지 않음

주요 기능

7+ 에이전트 — 전역 7개(architect, implementer, tester, code-reviewer, security-reviewer 등) + 조건부 그룹 4개(UI/Event — 해당 스택 프로젝트에만 로컬 설치, 총 11개). 단계별 지시 스크립트가 아니라 목표+제약+Done 기준으로 위임하고, 탐색·계획·병렬 실행은 하네스의 네이티브 서브에이전트를 그대로 사용합니다.

52개 스킬 — 한 번에 다 로드되지 않음. 공개 스킬은 모두 vibe.* namespace를 사용하며, 내부 core 동작은 공개 스킬 본문에 통합됩니다:

티어 로드 시점 용도 예시
Entry 전역 설치 공개 워크플로 진입점 vibe.spec, vibe.test, vibe.docs
Standard 전역 설치 공통 워크플로 지원 vibe.handoff, vibe.agents-md
Optional/Local 명시 호출 또는 프로젝트별 설치 스택·capability 지원 vibe.chub-usage, vibe.design-review

스킬이 가르치는 것은 모델이 모르는 것(도메인 gotcha, 최신 API, 프로젝트 규약)뿐입니다. 디버깅하는 법 같은 기본기 재교육 스킬은 v3에서 전부 삭제됐습니다.

세컨드 오피니언 (opt-in) — 기본 실행은 세션 모델 단독. 원할 때만 gpt …/agy … 접두사로 외부 LLM에게 물어보거나 /vibe.review --race로 교차 검증합니다. 자동 라우팅으로 외부 모델이 끼어드는 일은 없습니다.

스택 감지 — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙과 스킬 적용.

회귀 기억 — verify 실패가 /vibe.regress에 자동 등록되고, 반복 패턴은 예방 테스트로 승격. 결정·제약은 SQLite + FTS5로 세션 간 유지.

Smart Resume — .last-feature 포인터가 마지막 작업을 추적. 인자 없이 /vibe를 호출하면 중단된 위치를 보여주거나 진행 중 feature 목록을 제시.

루프 엔지니어링 — /vibe.loop로 자율 목표 루프를 설계·설치(트리아지 → run/verify 파이프라인). 완료 판정은 자기 보고가 아니라 결정론 게이트(run-ledger/테스트)가 내리고, 폭주 방어도 마찬가지 — 회전 수를 코드가 세고 전체 회전과 검증을 통과한 회전을 따로 집계해 헛도는 루프와 큰 작업을 구분합니다. 결과는 사람 리뷰 인박스로 — 루프는 push/release를 하지 않습니다.

플러그인으로 설치 (실험적)

npm 전역 설치의 대안 경로다. Claude Code · Codex · ChatGPT 세 곳에 같은 배포 트리(plugins/vibe)가 올라간다.

Claude Code — 저장소에서 바로 (npm 설치 불필요)

claude plugin marketplace add su-record/vibe
claude plugin install vibe@vibe
claude plugin details vibe               # Skills 52 · Agents 11 · Hooks 6

npm 으로 이미 설치한 경우

vibe plugin install                      # 배포 트리 조립 + 마켓플레이스 두 벌 등록
vibe plugin status                       # 조립·등록 상태 확인

claude plugin marketplace add ~/.vibe/plugin
claude plugin install vibe@vibe

codex plugin marketplace add ~
codex plugin add vibe@vibe

저장소를 클론한 경우 (개발·검증용)

npm run build:plugin                     # plugins/vibe/ 로 조립 (package.json files 기준)
claude plugin validate plugins/vibe
codex plugin marketplace add .
codex plugin add vibe@vibe-local

훅 이중 실행은 자동으로 막힌다. npm 설치본의 프로젝트 훅이 이미 있으면 플러그인 훅은 스스로 물러난다 (plugin-hook-entry.js). 그러지 않으면 같은 게이트가 2회 돌고 Stop 의 auto-commit 도 2회 돈다.

plugins/vibe/ 는 커밋되는 생성물이다. Claude Code 마켓플레이스는 저장소를 클론해 읽는데 dist/ 는 gitignore 대상이고 agents/*.md 의 frontmatter 는 postinstall 이 만든다 — 즉 저장소를 그대로 가리키면 기능이 빠진 플러그인이 된다 (실측: 에이전트 11개 중 7개만, 그나마 description 없이 로드). 드리프트는 CI 의 validate:plugin-tree 가 막는다.

ChatGPT 데스크톱 앱에서는 앱을 재시작한 뒤 Plugins Directory 에서 "Vibe (local)" → vibe 를 설치한다.

마켓플레이스 파일만 만들어두면 잡히지 않는다 — marketplace add 로 등록해야 한다. source.path 는 저장소 루트가 아니라 빌드 산출물(./plugins/vibe)을 가리킨다. 루트를 가리키면 워킹트리가 통째로 캐시에 복사된다 (실측 655MB, 그중 620MB 가 node_modules).

번들 Claude Code Codex CLI ChatGPT 앱
skills (52) ✅ ✅ ✅
agents (11) ✅ — —
hooks (6 이벤트) ✅ ✅ (trust 승인 후) 미확인 — 훅 문서가 Codex 아래에만 있다

⚠️ Codex 에서 훅은 설치·활성화만으로 신뢰되지 않는다 — Codex 가 정의를 검토·승인할 때까지 건너뛴다. vibe init 이 만드는 프로젝트 로컬 설정과 vibe upgrade 의 자기복구는 플러그인이 대체하지 못한다 — 그 둘이 필요하면 npm 설치를 함께 쓴다.

지원 도구

CLI 상태
Claude Code 전체 지원
Codex 전체 지원 (~/.codex/, AGENTS.md, native hooks.json, config.toml notify, codex exec agent fallback)
Antigravity CLI (agy) 에이전트 + 스킬

명령어

/vibe 하나로 시작하면 나머지는 vibe 가 라우팅한다. 아래는 특정 단계를 직접 부르고 싶을 때의 목록이다.

핵심 흐름

명령어 용도
/vibe 메인 진입점 — 자연어 요구사항 → SPEC 1패스 → 1회 승인 → 게이트 통과까지 루프
/vibe.spec SPEC 1패스 명시적 호출 — 인라인 질문 → SPEC + BDD → 승인
/vibe.run SPEC 기반 구현
/vibe.verify 구현이 SPEC Done 기준에 맞는지 검증 — 결과는 run-ledger 에 기록
/vibe.continue 세션 복원 — 85%+ 컨텍스트에서 save_memory → /new 후 이어서

CLI

명령 용도
vibe status 하네스 상태 — 하네스별 훅, 네이티브 바인딩, LLM 인증
vibe upgrade 업그레이드 + 자기복구 (전역 자산 · 프로젝트 훅 · 네이티브 바인딩)
vibe plugin install 플러그인 배포 트리 조립 + 마켓플레이스 등록

검증 · 품질

명령어 용도
/vibe.review 관점별 병렬 리뷰 (correctness / security / performance …) — P1=0 까지 수렴
/vibe.regress 회귀 테스트 자동 진화 — verify 실패 자동 등록, 반복 패턴 승격
/vibe.contract SPEC API 계약 ↔ 구현 drift 탐지 — P1 drift 는 regress 로 전파
/vibe.trace 요구사항 추적 매트릭스 (RTM)
/vibe.loop 자율 목표 루프 설계·설치 — 완료는 결정론 게이트가 판정
/vibe.test vibe 설치 자가검진 (CC ↔ Codex 동등성) — 릴리즈 전 권장
/vibe.harness 프로젝트 하네스 품질 6축 진단 (N/100)

설계 · UI

명령어 용도
/vibe.figma Figma ↔ 코드 (읽기 또는 쓰기, 3가지 모드)
/vibe.design DESIGN.md 시각 품질 SSOT — init / lint / verify / sync / preview
/vibe.clone 참조 사이트 URL → 현재 스택으로 마크업 재현 (픽셀 검증 루프)
/vibe.image 이미지 생성 (Antigravity) — 아이콘 / 배너 / 목업

분석 · 문서 · 운영

명령어 용도
/vibe.analyze 코드·문서·웹·Figma 분석 → 근거 있는 리포트
/vibe.reason 복잡한 문제의 가설·근거·트레이드오프 구조화
/vibe.docs README·가이드·아키텍처·릴리즈 노트·다이어그램을 코드와 동기화
/vibe.scaffold 새 프로젝트 구조 생성 / 기존 구조 감사
/vibe.llm provider 별 사용 가능 모델 목록 갱신

위는 자주 쓰는 것들이다. 설치된 전체 스킬 목록은 SKILL-CATALOG.md 에 있고, 표에 없는 요구사항도 /vibe 가 description 기반 Catch-all 라우팅으로 처리한다.

문서

상세 가이드, 스킬 레퍼런스, 설정 방법은 Wiki를 참고하세요.

요구사항

  • Node.js >= 20.12.0 (better-sqlite3 는 Node 20+, @clack/prompts 는 20.12+ 요구)
  • Claude Code 또는 Codex CLI 중 하나
  • GPT, Antigravity (선택 — 세컨드 오피니언 전용)

라이선스

MIT — Copyright (c) 2025 Su

About

Verification harness for AI coding agents — completion judged by deterministic gates (tests, run-ledger, regression memory), not the model's self-report. Wraps Claude Code, Codex, Cursor.

Topics

ai-agentsclaude-codeclicodexdeveloper-toolsllmverification

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages