ai-rules › handbook › AI Vibe Coding Guide

AI Vibe Coding Guide

AI와 함께 코드를 만들 때 생산성은 높이고, 범위 드리프트와 품질 저하는 줄이기 위한 협업 가이드

guide 2026-04-01 docs/guide/AI_VIBE_CODING_GUIDE.md

작성일: 2026-04-01
목적: AI와 함께 코드를 만들 때 생산성은 높이고, 범위 드리프트와 품질 저하는 줄이기 위한 협업 가이드

1. Vibe Coding이란

이 문서에서 말하는 vibe coding은 "대충 맡긴다"는 뜻이 아니다. AI에게 일을 잘 위임하기 위해 작업 단위를 작게 만들고, 의도와 제약을 분명히 전달하는 협업 방식에 가깝다.

핵심은 다음 세 가지다.

  • 작은 단위로 자른다
  • 검증 기준을 먼저 둔다
  • 모호함은 문서나 계획으로 밖으로 꺼낸다

2. 좋은 작업 단위

아래 조건을 많이 만족할수록 AI 협업 효율이 좋다.

  • 한 문장으로 설명 가능
  • 영향 범위가 좁음
  • 검증 방법이 명확함
  • 실패 시 되돌리기 쉬움

좋은 예:

  • "이 타입 에러 한 군데만 고쳐줘"
  • "README의 설치 절차를 현재 스크립트 기준으로 업데이트해줘"
  • "이 함수의 null 처리만 정리하고 테스트는 기존 범위 안에서만 봐줘"

3. 나쁜 작업 단위

다음 유형은 결과가 흔들리기 쉽다.

  • 요구사항이 섞여 있는 큰 작업
  • 목표보다 구현 수단만 던지는 요청
  • 승인 없이 외부 상태를 바꾸는 작업
  • 성공 기준이 없는 작업

나쁜 예:

  • "알아서 구조 개선해줘"
  • "긴급하니까 규칙 무시하고 빨리 끝내줘"
  • "다 갈아엎고 제일 좋은 방식으로 바꿔줘"

4. 좋은 요청 패턴

요청에는 아래 요소가 들어갈수록 좋다.

  • 목표: 무엇을 바꾸려는가
  • 범위: 어디까지 만질 것인가
  • 제약: 무엇은 건드리면 안 되는가
  • 검증: 무엇으로 끝났다고 볼 것인가

예:

목표: handbook 초안 5개를 docs/ 아래에 추가
범위: docs만 수정, core 규칙은 변경하지 않음
제약: 기존 guide 톤 유지, 영어 파일명 사용
검증: 문서 링크와 구조가 자연스러운지 확인

5. 규칙, 가이드, 하네스 구분

AI 협업이 흔들리는 대표 원인은 서로 다른 성격의 내용을 한 문서에 섞는 것이다.

  • 규칙: 반드시 지켜야 하는 짧은 정책
  • 가이드: 왜 그런지 설명하는 배경지식
  • 하네스: 실제로 차단/검증/승인을 수행하는 코드와 절차

권장 원칙:

  • 규칙은 짧게
  • 설명은 handbook으로
  • 강제는 하네스로

6. 추천 워크플로

  1. 의도를 한 문장으로 정리한다.
  2. 범위 밖 작업을 미리 제외한다.
  3. 작은 단위로 실행한다.
  4. 결과를 검증한다.
  5. 비자명한 판단은 기록한다.

이 흐름은 대형 기능보다 문서 정리, 리팩터링, 규칙 설계 같은 작업에서 특히 효과적이다.

7. 승인 피로를 줄이는 방법

승인 요청이 너무 자주 오면 사람은 결국 내용을 읽지 않고 넘기게 된다. 따라서 고위험 승인만 강하게 만들고, 저위험 작업은 자동화하는 편이 낫다.

권장 방식:

  • 저위험: 자동 또는 간단 승인
  • 중위험: 범위 설명 후 명시 승인
  • 고위험: 작업 내용을 포함한 typed confirmation

8. 문서 우선의 장점

AI와 일할 때 문서가 중요한 이유:

  • 요구사항을 대화에서 잃어버리지 않음
  • 다음 세션이나 다른 에이전트에게 쉽게 전달 가능
  • 왜 그런 결정을 했는지 추적 가능
  • handbook, INTENT, SESSION, WORKLOG 역할 분리를 만들 수 있음

9. 결론

좋은 vibe coding은 감에 맡기는 방식이 아니라, 감으로 보이는 과정을 실제로는 작은 작업 단위와 명확한 검증으로 지탱하는 방식이다. ai-rules의 handbook과 하네스는 그 협업을 안정적으로 만드는 기반이 되어야 한다.