바이브 코딩 작업 규칙: shrinkto.app을 3일 만에 만들며 지킨 8가지

AI 코딩 도구에게 큰 기능을 한 번에 맡기면 속도는 나지만 결과를 믿기 어려워진다. shrinkto.app은 3일 동안 74개 커밋으로 만들었는데, 그동안 프로젝트의 지침 파일(CLAUDE.md)에 규칙을 적어 두고 지켰다. 이 글은 그 규칙 중 실제로 실수를 막아 준 것을 골라 이유와 함께 적는다. 도구별 사용법과 컨텍스트 수집 원리는 바이브 코딩 도구 가이드에 정리했다.

1. 단계마다 승인받고, 승인한 단계만 만든다

지침 첫 줄이 “구현 계획을 단계별로 제시하고 승인을 받는다. 승인한 단계의 코드만 작성한다”이다. 한꺼번에 만들면 어디서 틀어졌는지 알 수 없다. 단계 단위로 끊으면 각 단계 끝에서 빌드와 테스트가 통과한 상태를 확인할 수 있어서, 문제가 생겨도 마지막 정상 지점으로 돌아갈 수 있다.

2. 단계는 항상 build와 test가 통과한 상태로 끝낸다

“거의 됐다”는 상태로 다음 단계로 넘어가지 않는다. 이 프로젝트의 기록에서 3단계 UI를 만들 때 e2e가 버그 세 가지를 잡았는데, 취소 뒤 시작 버튼이 먹통이 되는 문제처럼 직접 눌러 보지 않으면 놓칠 것들이었다.

3. 라이브러리 API는 추측하지 않는다

지침에 “mediabunny와 ffmpeg API는 추측 금지. 설치된 패키지의 타입 정의와 공식 문서를 확인한 뒤 사용”이라고 적었다. AI는 그럴듯한 옵션 이름을 만들어 낼 수 있다. 옵션명을 타입 정의에서 확인하게 하면 존재하지 않는 옵션을 쓰는 코드를 줄인다. 같은 이유로 “래퍼 패키지가 npm에 실제로 존재하는지 확인한 뒤 쓴다”는 조건도 달았다.

4. 불확실한 동작은 작은 스파이크로 먼저 확인한다

본 코드에 넣기 전에 작은 코드로 먼저 돌려 보고 결과를 보고받는다. 이 방식으로 frameRate 미지정 시 출력이 정확히 2배(8.0Mbps, 목표 4Mbps)가 되는 문제를 찾았다. 문서에서는 알기 어려운 동작이었고, 값을 명시하자 1.000배로 맞았다. 큰 구현 뒤에 발견했다면 원인을 찾기 훨씬 어려웠을 것이다.

5. 쓰면 안 되는 것을 지침에 못 박는다

이 프로젝트에서는 교차 출처 격리 헤더(COOP/COEP)와 SharedArrayBuffer, 멀티스레드 ffmpeg 코어를 금지했다. 광고 스크립트와 충돌할 수 있기 때문이다. 금지 목록이 없으면 AI는 성능에 유리한 쪽을 자연스럽게 골라 넣는다. 제약은 코드가 아니라 지침 파일에 남겨야 다음 세션에도 유지된다.

6. 출력 파일의 내용을 검사하는 테스트를 만든다

화면이 뜨는지만 보는 테스트는 부족하다. 이 프로젝트의 e2e는 출력 MP4의 박스 순서(ftyp → moov → mdat), 가림 처리된 화소, GIF의 프레임 같은 결과 파일의 실제 내용을 본다. 작업 기록의 규칙으로는 “프라이버시 기능은 조용히 실패하지 않는다”, “시각 문제는 캡처 이미지를 직접 확인한다”가 있다. 가림이 켜졌는데 실제 화소는 그대로인 상태처럼, 화면만 봐서는 구별되지 않는 실패를 잡으려는 규칙이다.

7. 검증하지 못한 범위를 문서에 그대로 적는다

“지원 범위: 데스크톱 Chrome만 보장. 다른 브라우저는 감지와 폴백이 있지만 검증하지 않았다”처럼 적는다. 아이폰 사파리는 실기기가 없어 확인하지 못했다는 것도 현황 문서에 남겼다. 확인하지 않은 것을 확인한 것처럼 쓰는 일은 AI도 사람도 자주 한다. 문서에 “미검증”을 명시하면 다음 작업자가 그 부분부터 확인할 수 있다.

8. 작업하며 알게 된 사실을 지침 파일에 누적한다

지침 파일 안에 “구현하며 확인된 사실” 항목을 두고 발견한 것을 적는다. 예를 들어 프로덕션 빌드에서는 클래스 이름이 압축되므로 취소 오류를 이름으로 비교하면 안 된다는 것, ffmpeg 코어 wasm이 32MB라 Cloudflare Pages 한도 25MiB를 넘는다는 것이 거기 있다. 새 세션이 같은 함정에 빠지지 않게 하는 기록이다.

규칙을 지켜도 남는 문제

• 규칙은 실수를 줄일 뿐 없애지는 못한다. 시험에 쓴 영상이 대부분 합성이어서, 실제 촬영 영상에서는 결과가 다를 수 있다는 점이 아직 남아 있다.
• 승인 단위를 잘게 나눌수록 속도는 느려진다. 3일에 74개 커밋이라는 속도는 나왔지만, 규칙이 없었다면 더 빨랐을지 느렸을지는 비교하지 않았다.
• 이 규칙들은 한 프로젝트의 경험이다. 다른 규모와 팀에서는 맞지 않을 수 있다.

---

같이 보면 좋은 글

• 혼자 만들고 배포할 때 체크리스트