'알아서 예쁘게'가 재작업을 부른다 — 바이브 코딩 프롬프트 작성법과 완성 기준 체크리스트

AI한테 기능을 맡길 때 재작업이 생기는 지점은 대체로 비슷합니다. “대충 이런 느낌”으로 시작해서, 결과를 보고 나서야 내가 뭘 원했는지 깨닫는 패턴이요. 그때쯤이면 이미 300줄이 쓰여 있습니다.

몇 달 굴려보고 내린 결론은 좀 시시합니다. 재작업은 모델 성능 문제가 아니라 완성 기준이 없어서 생깁니다. 사람한테 일을 넘길 때랑 똑같아요. 언제 끝난 건지 서로 합의가 안 된 채로 시작하면 결과물은 항상 다르게 나옵니다.

재작업은 세 곳에서 생긴다

제 로그를 되짚어보면 원인이 거의 여기 셋 중 하나였습니다.

1. 기준 없이 시작. “로그인 붙여줘” 같은 거요. 어떤 방식인지, 세션은 어디 두는지, 실패했을 때 UI는 어떻게 되는지 안 정하고 시작합니다. 결과물을 보고서야 결정하게 되고, 그 결정이 앞에 만든 걸 뒤엎습니다.
2. 한 프롬프트에 큰 작업 두 개. 스캐폴딩이랑 디자인 이식을 같이 시키면 중간에 확인할 지점이 없습니다. 30분 뒤에 나온 게 절반만 맞으면 어느 절반을 살릴지 판단하는 데 또 시간이 듭니다.
3. 결과물 안 읽고 다음 지시. 제일 비쌉니다. 어긋난 전제 위에 지시를 세 개 더 쌓으면 되돌릴 때 세 개가 다 날아갑니다.

프롬프트를 스펙처럼 쓰면 이 셋이 꽤 줄어듭니다.

프롬프트를 스펙처럼 쓰기

제가 정착한 구조는 세 블록입니다.

1. 컨텍스트 — 무엇을 왜 만드는지, 기존 코드/시안 위치
2. 요구사항 — 기술 스택, 데이터 구조, 제거할 것까지 명시
3. 완성 기준 — [ ] 체크리스트. 빌드 통과, 동작 확인 항목

각 블록이 막는 재작업 종류가 다릅니다.

1. 컨텍스트 — 어디에 붙는 코드인가

제일 자주 빠지는 블록이고, 빠지면 기존 코드를 무시한 새 구현이 나옵니다. 이미 있는 유틸 놔두고 비슷한 걸 하나 더 만들어놓은 결과물, 다들 한 번씩 받아보셨을 겁니다.

파일 경로를 그냥 직접 짚어주는 게 제일 효율이 좋습니다.

## 컨텍스트
- Astro 정적 블로그. 글은 src/content/posts/*.md 로 관리한다.
- 날짜/읽는시간 유틸은 이미 src/lib/posts.ts 에 있다. 새로 만들지 말고 재사용.
- 시안은 devlog_intro_terminal.html 한 장. 여기 색/여백/타이포를 기준으로 삼는다.

“이미 있다, 새로 만들지 마라” 한 줄이 중복 구현을 거의 다 막습니다.

2. 요구사항 — 만들 것보다 안 만들 것

요구사항 블록에서 사람들이 잘 안 쓰는 게 부정 조건입니다. AI는 기본적으로 후하게 만듭니다. 안 시킨 다크모드 토글, 안 시킨 로딩 스켈레톤, 안 시킨 설정 파일이 딸려옵니다. 하나씩 지우는 게 재작업이죠.

## 요구사항
- Astro + 마크다운. 상태 관리 라이브러리, UI 프레임워크 추가 금지.
- 라이트 단일 테마. 다크모드 토글 만들지 말 것.
- 페이지네이션 없음. 글 목록은 전부 한 페이지에 렌더한다.
- 클라이언트 JS는 코드블록 Copy 버튼과 검색 필터 두 개만.

금지, 만들지 말 것, 없음. 이런 말을 명시적으로 쓰세요. 안 쓰면 허가로 읽힙니다.

3. 완성 기준 — 검증 가능한 문장으로

핵심은 3번인데 조건이 하나 있습니다. 기계나 눈으로 참/거짓을 판정할 수 있는 문장이어야 합니다.

이런 건 안 됩니다.

- [ ] 디자인이 깔끔하다
- [ ] 성능이 괜찮다
- [ ] 코드가 깨끗하다

셋 다 판정이 안 되니까 AI는 자기가 통과했다고 선언하고 끝냅니다. 이렇게 바꿉니다.

- [ ] npm run build 가 경고 없이 통과한다
- [ ] /posts/ 에서 검색어를 입력하면 제목·설명 기준으로 목록이 필터된다
- [ ] 코드블록 Copy 버튼을 누르면 클립보드에 본문이 들어가고 버튼이 Copied!로 바뀐다
- [ ] 홈의 카테고리 카운트가 실제 마크다운 파일 수와 일치한다
- [ ] 사이드바가 1024px 이하에서 본문 아래로 내려온다

이렇게 쓰면 AI가 알아서 확인하고 끝냅니다. 빌드 돌리고, 실패하면 고치고, 다시 돌립니다. 확인 비용을 제가 아니라 AI가 내는 셈이라 받아보는 시점의 품질이 달라집니다.

혼자만의 요령인 줄 알았는데 Anthropic 공식 가이드가 같은 얘기를 훨씬 정확하게 적어 뒀습니다.

클로드는 작업이 끝난 것처럼 보이면 멈춥니다. 실행할 수 있는 검증 수단이 없으면 “끝난 것 같다”가 유일한 신호이고, 그때부터 검증 루프는 당신이 됩니다. 모든 실수가 당신이 발견할 때까지 기다리게 되죠.

문서가 드는 예시도 제 체크리스트와 같은 구조입니다. “이메일 검증 함수를 만들어줘”가 아니라 “validateEmail 함수를 만들어라. 테스트 케이스는 user@example.com은 참, invalid는 거짓, user@.com은 거짓. 구현 후 테스트를 실행해라”로 쓰라고요. 판정 가능한 문장을 주는 것과 안 주는 것의 차이입니다.

큰 작업은 세 단계로 쪼갠다

이 블로그도 한 프롬프트로 만들지 않았습니다. 세 단계로 나눴고 각 단계 끝에 눈으로 확인할 수 있는 산출물을 뒀습니다.

1단계 — 스캐폴딩:  Astro 프로젝트 + 콘텐츠 컬렉션 스키마 + 더미 글 3개
        확인: npm run dev 에서 목록/상세가 뜬다

2단계 — 시안 이식:  HTML 시안의 색·여백·타이포를 Base.astro 글로벌 CSS로
        확인: 시안과 나란히 놓고 히어로/카드/피드가 같아 보인다

3단계 — 데이터 연결: 카테고리 카운트, 최근 커밋 날짜, 조회수 위젯
        확인: 마크다운 하나 추가하면 홈 숫자가 따라 움직인다

공식 문서는 이걸 탐색 → 계획 → 구현 → 커밋 네 단계로 정리합니다. 특히 계획 단계를 분리하는 이유가 제 경험과 정확히 같아요. 바로 코딩에 들어가면 “엉뚱한 문제를 푼 코드”가 나옵니다. 다만 문서도 단서를 답니다. 한 문장으로 diff를 설명할 수 있는 작업이면 계획 단계는 건너뛰라고요.

나누는 기준은 하나입니다. 여기서 잘못돼도 다음 단계가 안 날아가는가. 시안 이식이 틀리면 CSS만 다시 하면 되고 스키마는 살아남습니다. 두 개를 한꺼번에 시키면 되돌릴 때 둘 다 날아가고요.

시안 없이 “예쁘게”를 시키지 마라

“알아서 예쁘게”는 취향 복권입니다. 열 번 돌리면 열 개가 나오고, 마음에 드는 게 나올 때까지 돌리는 게 제일 비쌉니다.

HTML 한 장이면 충분합니다. 이 블로그도 devlog_intro_terminal.html 한 파일에서 시작했고, 그 뒤로는 “이 시안 기준으로”라는 한 줄이 디자인 프롬프트의 절반을 대체했습니다. 시안을 Figma로 관리한다면 MCP로 직접 물릴 수도 있고, 아예 취향 자체를 규칙으로 주입하는 디자인 스킬이라는 방법도 있습니다. 시안이 있으면 완성 기준도 자동으로 검증 가능해집니다. 시안과 같아 보이는지는 판정할 수 있는 문장이니까요.

결과물은 읽고 넘어간다

제일 안 지켜지는 규칙입니다. 잘 돌아가는 것 같으면 그냥 넘어가고 싶어지죠.

최소한 두 개는 봅니다.

• 변경된 파일 목록. 시키지 않은 파일이 건드려졌으면 거기서 멈춥니다. 대개 그게 재작업의 씨앗입니다.
• 새로 추가된 의존성. package.json에 뭔가 늘었으면 왜 필요했는지 물어봅니다. 몇 줄이면 되는 걸 라이브러리로 해결한 경우가 생각보다 자주 나옵니다.

이미 어긋났을 때

판단 기준은 하나로 씁니다. 전제가 틀렸으면 되돌리고, 구현이 틀렸으면 이어서 고칩니다.

데이터 구조나 파일 배치 같은 전제가 어긋난 상태에서 “여기만 고쳐줘”를 반복하면 틀린 구조 위에 패치가 쌓입니다. 이럴 땐 커밋을 되돌리고 요구사항 블록을 다시 쓰는 게 훨씬 쌉니다. 구조는 맞는데 동작이 틀린 거면 그냥 버그니까 이어서 고치면 되고요.

횟수로 기준을 잡아두면 편합니다. 공식 가이드는 같은 문제로 두 번 고쳤는데도 안 되면 대화를 비우고 프롬프트를 다시 쓰라고 권합니다. 실패한 시도들이 컨텍스트에 쌓여서 오히려 방해가 되기 때문인데, 저도 세 번째 수정부터는 대체로 시간 낭비였습니다.

템플릿

매번 처음부터 쓰기 귀찮아서 이 형태를 그대로 씁니다.

## 컨텍스트
- 무엇을, 왜
- 기존 코드 위치 (재사용할 것 지목)
- 시안/참고 파일 경로

## 요구사항
- 스택과 제약
- 데이터 구조
- 만들지 말 것 (부정 조건)

## 완성 기준
- [ ] 빌드/테스트가 통과한다
- [ ] (동작) 하면 (결과) 가 된다
- [ ] 시키지 않은 파일과 의존성이 추가되지 않았다

완성 기준 쓰는 데 5분쯤 듭니다. 그 5분이 재작업 한 사이클을 통째로 지웁니다. 사실 이건 AI를 위한 시간도 아니에요. 내가 뭘 원하는지 내가 먼저 알아내는 시간입니다. 같은 원리가 모델에게 툴을 넘길 때도 그대로 적용됩니다. 호출 조건을 안 적어 주면 툴이 에러 없이 조용히 안 불리는데, 그 진단 순서는 Claude API 툴 호출 진단에 정리해 뒀습니다.

여기까지가 프롬프트 한 번을 잘 쓰는 이야기인데, 같은 규칙을 매번 손으로 쓰는 대신 작업 환경에 아예 박아두는 방향도 있습니다. 그쪽은 하네스 엔지니어링에 따로 정리했습니다.