4단계 문서 하네스 (4-Document Harness)
바이브 코딩 성공률을 결정하는 사전 4문서 패턴: Plan → Design(설계서) → DESIGN.md(스타일) → AGENTS.md(시스템 가이드). 단일 명령 실행 전에 이 4개를 끝까지 깎는 것이 핵심.
정의
/PDCA <요구사항> 같은 단일 명령으로 끝까지 자율 빌드를 돌리려면, AI가 흔들리지 않도록 사전 가드레일 4개를 모두 갖춰야 한다. 이 4가지는 역할이 명확히 다르며 순서가 중요하다.
| 단계 | 파일 | 역할 | 분량 (예시) |
|---|---|---|---|
| 1 | docs/plan-{기능명}.md | 상위 기획서 (Plan) — 무엇을 만들 것인가, 왜 만드는가, 기능 범위 | ~143줄 |
| 2 | docs/design-{기능명}.md | 상세 기획서 (Design) — 데이터 모델·DB 구조·기술 스택·구현 디테일 | ~360줄 |
| 3 | DESIGN.md (루트) | 스타일 가이드 (DESIGN.md) — 타이포그래피·컬러·shape·버튼 등 시각 디자인 시스템 | 디자인 시스템에서 카피 |
| 4 | AGENTS.md (루트) | 시스템 가이드라인 — 프로젝트 맥락·반복 실수 방지·서브에이전트/스킬 사용 규칙 | 50~100줄 |
왜 4개로 분리하는가
- Plan ↔ Design 분리: Plan만 있으면 “데이터 모델”을 매 호출 다시 추론한다. Design을 별도로 두면 모델이 다시 생각할 필요 없이 참조만 한다.
- Design(설계서) ↔ DESIGN.md(스타일) 분리: 같은 .md 확장자라 혼동하지만 완전히 다른 문서. 설계서는 “어떻게 구현할까” / 스타일 .md는 “어떻게 보일까”.
- AGENTS.md 분리: 시스템 프롬프트 역할. Plan/Design은 한 번 작성하고 끝나지만 AGENTS.md는 계속 업데이트 되는 살아있는 문서.
이 4분리가 없으면 AI는 매 호출 컨텍스트를 재해석하면서 토큰·시간을 낭비하고 일관성이 무너진다.
시연 사례
yt-ZDfNfEGo7Fc-Codex-바이브코딩-2시간-라이브 에서 빌더 조쉬가 Codex + bkit 플러그인의 /PDCA 명령으로 회사 휴가 ERP를 4문서 세팅 후 단일 /do 명령으로 무에러 빌드 + Vercel 배포까지 시연.
권장 워크플로우
/PDCA <요구사항>— Plan + Design(설계서) 자동 생성 (bkit 등 PDCA 자동화 플러그인 필요)- getdesign.md / 오마이디자인에서 회사 톤에 맞는 .md 복사 →
DESIGN.md로 저장 에이전트.md 파일에 현재 프로젝트 맥락을 잘 넣어줘명령 →AGENTS.md자동 생성 후 “한글로 다시 써줘”로 재작성/PDCA-2(Do 단계) — 4문서를 모두 참조해 실제 구현 시작
관련 개념
- harness-engineering — 4단계 문서 하네스는 하네스 엔지니어링의 비개발자 친화 응용.
- vibe-coding — 바이브 코딩의 실전 성공률을 결정하는 패턴.
- PDCA-바이브코딩 — 이 4문서를 자동 생성하는 PDCA 사이클 자동화.
- AGENTS-md — 4번째 문서의 cross-tool 표준 측면.
- Thin-Harness-Fat-Skills — 비교: 얇은 하네스 + 두꺼운 스킬 vs 4문서 하네스 + 직접 명령.
- goal-mode-자율루프 — 4문서 하네스가 완비되면
/goal자율 루프의 성공률이 급상승.