AI 코딩 효율 — 프롬프트 계약서(Prompt Contracts)

AI Coding · Prompt Engineering · 2026

AI한테 코딩 맡겼다가
2,400줄 전부 버린 이유

프롬프트를 잘 쓰는 게 아니라, 계약서처럼 설계해야 한다.
바이브 코딩의 함정과 Prompt Contracts의 등장.

📖 원문: Medium @rentierdigital ⏱ 읽기 약 5분

Episode

새벽 2시의 실수

Claude Code에게 Supabase 인증 플로우를 만들어달라고 했다. 돌아온 건 완벽하게 작동하는 Firebase 인증 시스템이었다.

코드는 컴파일됐다. 실행됐다. 심지어 깔끔해 보였다.
하지만 틀린 문제를 풀고 있었다.

피자를 주문했는데 완벽하게 조리된 리조또가 왔다. 기술적으로는 훌륭하다. 근본적으로는 틀렸다.

"나는 Claude Code로 코딩을 한 게 아니라, 도박을 하고 있었다."

---

Problem

바이브 코딩이란?

자연어로 AI에게 요청하고 결과를 기대하는 방식이다. AI는 컨텍스트 없이도 자신감 200%로 뭔가를 만들어낸다.

# 바이브 코딩의 전형적인 패턴

> "SaaS 대시보드 만들어줘"
→ 14개 파일, 3,000줄 생성 / 원하는 게 아닌 코드
→ 다시 요청 → 또 다시 → 무한 반복

> "로그인 폼 React로 만들어줘"
→ Tailwind + Lucide 아이콘까지 붙은 복잡한 폼 생성
→ 나는 일반 CSS를 원했지만, AI는 알 방법이 없다

AI는 그럴듯해 보이는 코드를 만든다. 그럴듯한 것이 올바른 것과 같지 않을 뿐이다.

Root Cause

바이브 코딩의 3가지 실질적 문제

⚠️

품질 보증 부재

표면적으로는 작동하지만 에러 핸들링 · 보안 검사 · 엣지 케이스 처리가 빠져있는 경우가 많다. 프로덕션에 그대로 올리면 사고난다.

🔄

프롬프트 드리프트

기능을 추가하거나 수정할수록 AI가 일관성 없는 스타일, 중복 로직, 호환되지 않는 구조를 만들어낸다. 코드베이스가 점점 망가진다.

🧩

시스템 컨텍스트 무시

기존 인증 미들웨어가 어떻게 작동하는지, 세션 관리는 어디에 있는지를 모르는 채로 요청하면 완전히 잘못된 방향이 나온다.

---

Solution

프롬프트 계약서(Prompt Contracts)란?

코드를 한 줄 쓰기 전에 작성하는 구조화된 명세서.
AI에게 무엇을 만들지, 어떻게 만들지, 무엇을 하면 안 되는지, 결과를 어떻게 검증할지를 사전에 명시한 문서.

핵심 개념은 "프롬프트를 API처럼 다루는 것"이다. 소프트웨어에서 함수를 호출할 때 입력값과 반환값을 모르고 쓰지 않는 것처럼, AI 프롬프트도 명시적인 입력 / 출력 / 실패 조건을 정의해야 한다.

새로운 도구나 소프트웨어가 아니다. AI에게 작업을 넘기기 전에 작성하는 구조화된 텍스트 문서다.

Template

프롬프트 계약서 구조

## ── PROMPT CONTRACT TEMPLATE ──────────────────

## GOAL
무엇을 만드는가 (한 줄로 명확하게)
  예: Supabase RLS 기반 사용자 인증 플로우 구현

## STACK
사용할 기술 스택 명시
  예: Next.js 14, Supabase, Clerk, Convex

## CONSTRAINTS
하면 안 되는 것 (명시적으로 금지)
  예: No Firebase. No Prisma. No Tailwind.
      기존 /lib/auth.ts 패턴을 반드시 따를 것.

## FORMAT
출력 형식 정의
  예: 파일 단위로 분리. 함수마다 JSDoc 주석 포함.
      index.ts → handler.ts → types.ts 순서로 작성.

## FAILURE CONDITIONS
이 결과가 나오면 실패로 간주
  예: - Firebase import 시 실패
      - RLS 정책 없이 직접 쿼리하면 실패
      - 에러 핸들링이 없으면 실패

## ──────────────────────────────────────────────

이 5가지 섹션이 전부다. 10분 작성으로 반복 수정에 드는 몇 시간을 아낄 수 있다.

Comparison

Before vs After

── BEFORE (바이브 코딩) ──────────────────────────

> "Supabase 인증 만들어줘"
결과: Firebase로 완성된 인증 시스템
      → 2,400줄 전부 삭제 → 처음부터 다시


── AFTER (프롬프트 계약서) ───────────────────────

## GOAL: Supabase RLS 기반 인증 플로우
## STACK: Next.js 14, Supabase
## CONSTRAINTS: No Firebase. No 외부 인증 라이브러리.
## FORMAT: 파일 단위 분리, 에러 핸들링 필수
## FAILURE CONDITIONS: Firebase import 시 실패

결과: 첫 번째 시도에 프로덕션 수준 코드 생성
      → 검토 → 배포

항목	❌ 바이브 코딩	✅ 프롬프트 계약서
방식	자연어로 대충 요청	구조화된 명세 사전 합의
결과 예측	불가능	예측 가능
문제 발생 시	전부 다시	조건 수정 후 재실행
AI 역할	도박사	계약 이행자
시간 비용	무한 반복 수정	첫 시도에 근접

---

Practice

실전 적용 3원칙

1

4가지 질문에 먼저 답하라

무엇을 바꿔야 하는가 / 어디에서 / 왜 (제약 조건) / 어떻게 검증할 것인가. 이 4가지가 명확하지 않으면 프롬프트를 보내지 마라.

2

작게 쪼개서 요청하라

데이터 모델 → 핸들러 → 비즈니스 레이어 순으로. "전체 앱 만들어줘"는 도박이다. 기능 단위로 나누면 검증이 가능해진다.

3

제약 조건은 앞에 넣어라

컨텍스트가 길어질수록 AI는 프롬프트 끝부분을 덜 주목한다. 금지 사항과 핵심 조건은 반드시 프롬프트 앞부분에 배치하라.

Caveat

그래도 알아야 할 한계

⚠ 중요한 경고

프롬프트 계약서도 버그가 될 수 있다.

계약서 자체가 잘못 작성되면, AI는 그 잘못된 명세를 완벽하게 따른다. 계약서가 틀리면 코드도 정확하게 틀린 방향으로 나온다.

결국 계약서를 잘 쓰려면 내가 뭘 원하는지 정확히 알아야 한다. AI는 도구다. 판단은 여전히 사람의 몫이다.

프롬프트 계약서는 새로운 마법이 아니다. 기존 프롬프트 엔지니어링을 더 체계화한 방법론에 가깝다. 하지만 이 사소한 구조화가 결과물의 질을 완전히 바꾼다.

"AI는 도구다.
도구에게 명세서를 주면,
도박이 아니라 납품이 된다."

Prompt Contracts — vibe coding의 종료 선언