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

바이브 코딩 프롬프트를 스펙처럼 쓰는 법. 컨텍스트·요구사항·완성 기준 3블록 템플릿과 부정 조건, 작업 분할로 재작업 줄이기.

- source: https://polroute.com/posts/vibe-coding-prompt/
- category: AI 워크플로우
- published: 2026-08-12

---

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

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

## 재작업은 세 곳에서 생긴다

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

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

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

## 프롬프트를 스펙처럼 쓰기

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

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

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

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

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

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

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

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

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

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

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

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

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

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

이런 건 안 됩니다.

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

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

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

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

혼자만의 요령인 줄 알았는데 Anthropic [공식 가이드](https://code.claude.com/docs/en/best-practices)가 같은 얘기를 훨씬 정확하게 적어 뒀습니다.

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

![Anthropic 공식 Claude Code 가이드의 Before/After 표 — 검증 기준 제시, UI 변경의 시각적 검증, 증상이 아닌 근본 원인 지목 세 가지 전략의 프롬프트 비교](/images/vibe-coding-prompt-1.webp)

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

## 큰 작업은 세 단계로 쪼갠다

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

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

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

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

[공식 문서](https://code.claude.com/docs/en/best-practices)는 이걸 **탐색 → 계획 → 구현 → 커밋** 네 단계로 정리합니다. 특히 계획 단계를 분리하는 이유가 제 경험과 정확히 같아요. 바로 코딩에 들어가면 "엉뚱한 문제를 푼 코드"가 나옵니다. 다만 문서도 단서를 답니다. 한 문장으로 diff를 설명할 수 있는 작업이면 계획 단계는 건너뛰라고요.

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

## 시안 없이 "예쁘게"를 시키지 마라

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

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

## 결과물은 읽고 넘어간다

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

최소한 두 개는 봅니다.

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

## 이미 어긋났을 때

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

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

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

## 템플릿

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

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

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

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

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

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