vibe/
버전
v4.6.9
정본
vibe/
에이전트
Claude Code, Codex

vibe workflow harness

AI 코딩을
유닛으로 나누고,
끝까지 확인합니다.

vibe는 Claude Code와 Codex가 같은 규칙으로 일하도록 만든 재사용 워크플로우 하네스입니다. 로드맵을 작은 유닛으로 나누고, 한 유닛씩 구현과 검증과 기록을 마친 뒤 다음 세션에 넘깁니다.

30초 영상 보기 시작 명령 보기

유닛 루프 한 유닛은 계획, 구현, 검증, 기록, 커밋 순서로 한 바퀴를 돕니다. 계획 구현 검증 기록 커밋 unit-loop <ID>
(01.)

정본은 하나, 표면은 둘

vibe/            정본: 문서, 프롬프트, 규칙, 엔진
+-- scripts/     unit 명령이 호출하는 엔진
+-- ready/       준비 단계 프롬프트
+-- guides/      제어 계층과 실행 기준
.claude/         Claude Code 커맨드, 규칙, 스킬
.codex/          Codex 스킬, 규칙, 설정
unit             디스패처 CLI

문서, 프롬프트, 규칙, 실행 스크립트의 정본은 vibe/ 하나입니다. .claude/와 .codex/는 같은 정본을 각 에이전트가 읽는 형태로 노출합니다.

  • 루트의 unit 명령은 로직을 직접 담지 않고 vibe/scripts/ 엔진에 위임합니다.
  • 사람이 읽는 문서와 프롬프트는 한국어로, 에이전트가 읽는 커맨드와 스킬 본문은 영어로 씁니다.
  • bash unit adopt로 다른 저장소에 이식하고, 작업이 끝나면 하네스를 걷어낼 수 있습니다.
(02.)

시작점에 따라 세 가지 경로

  1. 신규 프로젝트

    빈 저장소에서 새 제품을 설계할 때

    bash unit init "<절대경로>"

    PRD에서 v0.1과 후속 Phase를 정하고, 첫 로드맵에는 v0.1 유닛만 둡니다. 준비 순서는 PRD -> 기술 스택 -> 아키텍처 -> 로드맵입니다.

  2. 패치

    잘 모르는 기존 저장소에 기능 묶음을 더할 때

    bash unit adopt "<절대경로>"

    요구사항은 FRD에 적습니다. 유닛은 패치 루트 브랜치에서 갈라져 먼저 그 브랜치로 머지되고, 마지막에 기준 브랜치로 통합됩니다.

  3. 핫픽스

    유닛 1-3개 규모의 단발성 수정

    /hotfix "<수정 요청>"

    U-9xx 유닛과 CP-HF 체크포인트를 미니 로드맵으로 등록하고, 워크트리 없이 현재 브랜치에서 같은 유닛 루프로 진행합니다.

유닛 종류: U(구현), RU(리팩터링), CP(체크포인트).

(03.)

unit-loop, 한 유닛을 끝까지

/unit-loop <ID>를 한 번 호출하면 현재 세션이 한 유닛의 구현, 필요한 검증, 완료 기록, 커밋까지 이어서 수행합니다. U, RU, CP가 모두 같은 진입점을 씁니다.

  • 모델은 유닛을 시작하기 전에 한 번 고릅니다. 루프 안에서 단계별로 모델을 바꾸지 않습니다.
  • 다음 유닛은 bash unit next가 의존성, 체크포인트 경계, 경로 충돌을 계산해 추천합니다.
사용 예
/unit-loop U-012
/unit-loop RU-004
/unit-loop CP-R01
/unit-loop U-012 --here
  1. begin다음 유닛인지 확인하고 맥락(commands.md)을 만들고 열린 질문을 점검합니다. 되돌릴 수 있는 구현 선택은 권장안을 채택하고, 제품 결정은 사용자 답을 기다립니다.
  2. 구현확인된 기준 상태에서 변경 하나를 적용하고, 바뀐 동작을 직접 확인한 뒤 다음으로 넘어갑니다.
  3. review-prep, final-review리스크 게이트로 리뷰가 필요한지 정하고, 필요한 리뷰와 검증만 실행합니다.
  4. finish리뷰와 테스트 판정을 확인하고 로드맵 체크, 진행률, 인계 점검, 커밋 메시지를 한 번에 처리합니다.
  5. 커밋Unit-Id trailer가 붙은 커밋으로 끝납니다. 머지와 push는 하지 않습니다.
(04.)

멈춰야 할 곳에서 멈춥니다

게이트를 통과하지 못하면 다음 단계로 가지 않습니다. 판단이 어려우면 멈추고 무엇이 빠졌는지 보고합니다(stop-and-report).

명령 가드

PreToolUse 가드는 실행 전에 다음 명령을 막습니다.

  • git push
  • git commit --no-verify
  • git -c core.hooksPath=...
  • .env 비밀 파일 읽기
  • 저장소 루트 재귀 검색

push와 배포는 사용자가 직접 승인합니다. .env 작업은 Codex에 위임합니다.

  1. 계획 확정PRD, FRD, 로드맵을 만든 직후 사람이 검토합니다.
  2. 유닛 경계한 유닛을 마치면 결과와 진행률을 확인하고 다음 유닛으로 갑니다.
  3. 질문[owner] 표시가 붙은 제품 결정은 사용자 답을 기다립니다.
  4. 머지 직전리뷰 판정 파일을 검증한 뒤에만 머지합니다.
  5. 선형성한 작업 공간에서는 의존성 순서대로 한 유닛씩 진행합니다.
(05.)

실제 진입점에서 확인합니다

바뀐 동작은 사용자가 쓰는 경로에서 직접 확인합니다. 버그는 고치기 전에 같은 입력으로 재현합니다.

  • CLI실제 명령을 정상 입력과 경계 입력으로 실행합니다.
  • API개발 서버를 띄우고 실제 요청을 보냅니다.
  • UIPlaywright CLI로 화면을 조작하고 스크린샷을 직접 봅니다.
검증 시점
시점실행
문서만 변경직접 검토와 해당 문서를 읽는 기존 검사기
평소바뀐 동작의 대상 테스트, 바뀐 셸 스크립트의 bash -n, 필요하면 bash unit doctor --smoke
CP전체 스위트, full doctor, 배포와 채택 셀프테스트
릴리스 컷CP에서 확보한 검증 receipt를 소비

같은 입력에 대한 통과 증거는 단계 사이에서 재사용합니다. 새 테스트와 CI는 사용자가 요청할 때만 추가합니다.

(06.)

다음 세션이 이어받습니다

유닛이 끝나면 unit-result, progress-latest.json, Git 커밋 trailer가 인계 자료가 됩니다. 로드맵 체크와 진행률 카운터는 bash unit close가 결정론적으로 갱신하므로 손으로 고치지 않습니다.

  • 매 턴 다시 읽는 누적 문맥이 토큰 소비의 대부분이라서, 다음 유닛은 새 세션에서 시작하는 것이 기본입니다.
  • 한 세션에서 이어 갈 때는 /unit-continue가 유닛 경계에서 대화를 비웁니다.
  • 마지막 CP를 통과하면 다음 Phase용 roadmap-update 프롬프트를 받고, 완료한 로드맵은 보관합니다.
현재 버전
v4.6.9
커밋 (2026-03-17 이후)
892
Claude Code 커맨드
34
Codex 스킬
39

수치는 2026-11-22 main 브랜치 기준 집계입니다.

(07.)

30초로 보는 흐름

소리 없는 모션 그래픽입니다. 화면의 글자로 내용을 전달하고, 아래에 장면 설명을 붙였습니다.

  1. 문제 큰 요청 하나가 큰 변경으로 돌아옵니다. 무엇이 끝났는지, 실제로 확인했는지, 다음 세션이 무엇을 이어받는지 알기 어렵습니다.
  2. 하네스 vibe/ 정본 하나를 Claude Code와 Codex가 함께 씁니다.
  3. 계획 로드맵을 U, RU, CP 유닛으로 나눕니다.
  4. 실행 /unit-loop 한 번으로 구현, 검증, 기록, 커밋까지 진행합니다.
  5. 게이트 확인한 것만 완료로 기록하고, push와 배포는 사람이 승인합니다.
  6. 기록 다음 세션이 결과와 진행률을 이어받습니다.

영상 속 터미널과 로드맵 화면은 흐름을 보여 주는 예시이며 실제 출력 형식과 다를 수 있습니다. MP4 파일 열기

(08.)

시작하기

하네스 저장소는 비공개입니다. 접근 권한이 있는 팀원은 하네스 소스 체크아웃의 Git Bash에서 다음 명령으로 시작합니다. 처음 보는 용어는 vibe/glossary.md에 한 화면으로 정리돼 있습니다.

  1. 새 프로젝트를 시작합니다.

    bash unit init "<절대경로>"
  2. 기존 저장소에 하네스를 이식합니다.

    bash unit adopt "<절대경로>"
  3. 실행할 수 있는 다음 유닛을 확인합니다.

    bash unit next
  4. 에이전트 세션 안에서 유닛 하나를 실행합니다.

    /unit-loop <ID>
  5. 하네스 상태를 빠르게 점검합니다.

    bash unit doctor --smoke