vibe workflow harness
AI 코딩을
유닛으로 나누고,
끝까지 확인합니다.
vibe는 Claude Code와 Codex가 같은 규칙으로 일하도록 만든 재사용 워크플로우 하네스입니다. 로드맵을 작은 유닛으로 나누고, 한 유닛씩 구현과 검증과 기록을 마친 뒤 다음 세션에 넘깁니다.
정본은 하나, 표면은 둘
vibe/ 정본: 문서, 프롬프트, 규칙, 엔진 +-- scripts/ unit 명령이 호출하는 엔진 +-- ready/ 준비 단계 프롬프트 +-- guides/ 제어 계층과 실행 기준 .claude/ Claude Code 커맨드, 규칙, 스킬 .codex/ Codex 스킬, 규칙, 설정 unit 디스패처 CLI
문서, 프롬프트, 규칙, 실행 스크립트의 정본은 vibe/ 하나입니다. .claude/와 .codex/는 같은 정본을 각 에이전트가 읽는 형태로 노출합니다.
- 루트의
unit명령은 로직을 직접 담지 않고vibe/scripts/엔진에 위임합니다. - 사람이 읽는 문서와 프롬프트는 한국어로, 에이전트가 읽는 커맨드와 스킬 본문은 영어로 씁니다.
bash unit adopt로 다른 저장소에 이식하고, 작업이 끝나면 하네스를 걷어낼 수 있습니다.
시작점에 따라 세 가지 경로
-
신규 프로젝트
빈 저장소에서 새 제품을 설계할 때
bash unit init "<절대경로>"PRD에서 v0.1과 후속 Phase를 정하고, 첫 로드맵에는 v0.1 유닛만 둡니다. 준비 순서는 PRD -> 기술 스택 -> 아키텍처 -> 로드맵입니다.
-
패치
잘 모르는 기존 저장소에 기능 묶음을 더할 때
bash unit adopt "<절대경로>"요구사항은 FRD에 적습니다. 유닛은 패치 루트 브랜치에서 갈라져 먼저 그 브랜치로 머지되고, 마지막에 기준 브랜치로 통합됩니다.
-
핫픽스
유닛 1-3개 규모의 단발성 수정
/hotfix "<수정 요청>"U-9xx 유닛과 CP-HF 체크포인트를 미니 로드맵으로 등록하고, 워크트리 없이 현재 브랜치에서 같은 유닛 루프로 진행합니다.
유닛 종류: U(구현), RU(리팩터링), CP(체크포인트).
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
- begin다음 유닛인지 확인하고 맥락(
commands.md)을 만들고 열린 질문을 점검합니다. 되돌릴 수 있는 구현 선택은 권장안을 채택하고, 제품 결정은 사용자 답을 기다립니다. - 구현확인된 기준 상태에서 변경 하나를 적용하고, 바뀐 동작을 직접 확인한 뒤 다음으로 넘어갑니다.
- review-prep, final-review리스크 게이트로 리뷰가 필요한지 정하고, 필요한 리뷰와 검증만 실행합니다.
- finish리뷰와 테스트 판정을 확인하고 로드맵 체크, 진행률, 인계 점검, 커밋 메시지를 한 번에 처리합니다.
- 커밋
Unit-Idtrailer가 붙은 커밋으로 끝납니다. 머지와 push는 하지 않습니다.
멈춰야 할 곳에서 멈춥니다
게이트를 통과하지 못하면 다음 단계로 가지 않습니다. 판단이 어려우면 멈추고 무엇이 빠졌는지 보고합니다(stop-and-report).
명령 가드
PreToolUse 가드는 실행 전에 다음 명령을 막습니다.
git pushgit commit --no-verifygit -c core.hooksPath=....env비밀 파일 읽기- 저장소 루트 재귀 검색
push와 배포는 사용자가 직접 승인합니다. .env 작업은 Codex에 위임합니다.
- 계획 확정PRD, FRD, 로드맵을 만든 직후 사람이 검토합니다.
- 유닛 경계한 유닛을 마치면 결과와 진행률을 확인하고 다음 유닛으로 갑니다.
- 질문
[owner]표시가 붙은 제품 결정은 사용자 답을 기다립니다. - 머지 직전리뷰 판정 파일을 검증한 뒤에만 머지합니다.
- 선형성한 작업 공간에서는 의존성 순서대로 한 유닛씩 진행합니다.
실제 진입점에서 확인합니다
바뀐 동작은 사용자가 쓰는 경로에서 직접 확인합니다. 버그는 고치기 전에 같은 입력으로 재현합니다.
- CLI실제 명령을 정상 입력과 경계 입력으로 실행합니다.
- API개발 서버를 띄우고 실제 요청을 보냅니다.
- UIPlaywright CLI로 화면을 조작하고 스크린샷을 직접 봅니다.
| 시점 | 실행 |
|---|---|
| 문서만 변경 | 직접 검토와 해당 문서를 읽는 기존 검사기 |
| 평소 | 바뀐 동작의 대상 테스트, 바뀐 셸 스크립트의 bash -n, 필요하면 bash unit doctor --smoke |
| CP | 전체 스위트, full doctor, 배포와 채택 셀프테스트 |
| 릴리스 컷 | CP에서 확보한 검증 receipt를 소비 |
같은 입력에 대한 통과 증거는 단계 사이에서 재사용합니다. 새 테스트와 CI는 사용자가 요청할 때만 추가합니다.
다음 세션이 이어받습니다
유닛이 끝나면 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 브랜치 기준 집계입니다.
30초로 보는 흐름
소리 없는 모션 그래픽입니다. 화면의 글자로 내용을 전달하고, 아래에 장면 설명을 붙였습니다.
- 문제 큰 요청 하나가 큰 변경으로 돌아옵니다. 무엇이 끝났는지, 실제로 확인했는지, 다음 세션이 무엇을 이어받는지 알기 어렵습니다.
- 하네스 vibe/ 정본 하나를 Claude Code와 Codex가 함께 씁니다.
- 계획 로드맵을 U, RU, CP 유닛으로 나눕니다.
- 실행 /unit-loop 한 번으로 구현, 검증, 기록, 커밋까지 진행합니다.
- 게이트 확인한 것만 완료로 기록하고, push와 배포는 사람이 승인합니다.
- 기록 다음 세션이 결과와 진행률을 이어받습니다.
영상 속 터미널과 로드맵 화면은 흐름을 보여 주는 예시이며 실제 출력 형식과 다를 수 있습니다. MP4 파일 열기
시작하기
하네스 저장소는 비공개입니다. 접근 권한이 있는 팀원은 하네스 소스 체크아웃의 Git Bash에서 다음 명령으로 시작합니다. 처음 보는 용어는 vibe/glossary.md에 한 화면으로 정리돼 있습니다.
새 프로젝트를 시작합니다.
bash unit init "<절대경로>"기존 저장소에 하네스를 이식합니다.
bash unit adopt "<절대경로>"실행할 수 있는 다음 유닛을 확인합니다.
bash unit next에이전트 세션 안에서 유닛 하나를 실행합니다.
/unit-loop <ID>하네스 상태를 빠르게 점검합니다.
bash unit doctor --smoke