바이브 코딩 교육: 좋은 프롬프트로 Python 샘플 프로젝트 설계하기

바이브 코딩 교육: 좋은 프롬프트로 Python 샘플 프로젝트 설계하기

2026. 8. 4. 12:14ㆍAI

바이브 코딩이란

**바이브 코딩(Vibe Coding)**은 개발자가 코드를 한 줄씩 직접 작성하는 대신, AI에게 목적과 요구사항을 자연어로 전달하고 AI가 실제 동작하는 코드를 생성하도록 하는 개발 방식입니다.

바이브 코딩에서 결과물의 품질은 대부분 프롬프트의 완성도에서 결정됩니다. AI는 프롬프트에 없는 내용을 마음대로 추측하기 때문에, 프롬프트가 모호하면 결과물도 모호해집니다.

이번 글에서는 "공공데이터 API 연동 샘플" 프로젝트를 요청한 실제 프롬프트를 예시로, 좋은 바이브 코딩 프롬프트가 어떤 요소로 구성되는지 살펴봅니다.

왜 이 프롬프트가 좋은 예시인가

아래 프롬프트는 실제로 AI에게 전달된 요청입니다.

너는 소프트웨어 개발 보조자야.
다음 목표로 Python 샘플 프로젝트를 만들어줘.
프로젝트 이름:
공공데이터 API 연동 샘플
목적:
공공데이터 API를 처음 사용하는 사람이 샘플 소스를 통해 API 호출, 결과 저장, 이메일 공유 흐름을 이해할 수 있게 한다.
대상 API:
기상청_단기예보 조회서비스
Endpoint:
https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getVilageFcst
기술 스택:
- Python 3.12 이상
- requests
- python-dotenv
- APScheduler
- pytest
- smtplib
- email.message
구현 요구사항:
1. `.env.example`을 만들고 실제 인증키는 `.env`에서만 읽게 해줘.
2. `.env`에는 다음 항목을 사용해줘.
   - PUBLIC_DATA_SERVICE_KEY
   - WEATHER_NX=60
   - WEATHER_NY=127
   - WEATHER_NUM_OF_ROWS=1000
   - WEATHER_PAGE_NO=1
   - WEATHER_DATA_TYPE=JSON
   - WEATHER_TIMEOUT_SECONDS=10
   - MONITOR_INTERVAL_SECONDS=3600
   - OUTPUT_DIR=data
   - GMAIL_SMTP_HOST=smtp.gmail.com
   - GMAIL_SMTP_PORT=587
   - GMAIL_USERNAME
   - GMAIL_APP_PASSWORD
   - EMAIL_FROM
   - EMAIL_TO
   - EMAIL_SUBJECT=기상청 단기예보 조회 결과
   - EMAIL_ATTACH_JSON=false
3. 단기예보 API 조회 기본값:
   - pageNo=1
   - numOfRows=1000
   - dataType=JSON
   - nx=60
   - ny=127
   - base_date는 실행일 기준 YYYYMMDD
   - base_time은 최신 사용 가능 발표시각을 자동 선택
   - base_time 후보는 0200, 0500, 0800, 1100, 1400, 1700, 2000, 2300
   - 각 발표시각 10분 이후부터 사용 가능하다고 보고, 당일 첫 발표 전이면 전날 2300을 사용
4. API 응답은 JSON으로 파싱하고, 결과를 `data/forecast_YYYYMMDD_HHMMSS.json` 파일로 저장해줘.
5. CLI를 만들어줘.
   - 단발 실행: `python -m open_data_sample.cli`
   - 이메일 전송: `python -m open_data_sample.cli --send-email`
   - 주기 실행: `python -m open_data_sample.cli --monitor`
6. 이메일 전송:
   - Gmail SMTP를 사용해줘.
   - 기본은 HTML 요약 본문만 보내줘.
   - 메일 본문에는 발표일자/시각, 조회 격자, 항목 수, 저장 시각, 가까운 예보 시간별 주요 항목 표를 포함해줘.
   - `EMAIL_ATTACH_JSON=true`일 때만 원본 JSON 파일을 첨부해줘.
   - 일반 Gmail 비밀번호가 아니라 Gmail 앱 비밀번호를 사용한다는 설명을 README에 넣어줘.
7. 오류 처리를 구분해줘.
   - API_AUTH_ERROR
   - API_REQUEST_ERROR
   - API_EMPTY_RESULT
   - API_TIMEOUT
   - API_SCHEMA_CHANGED
   - FILE_WRITE_ERROR
   - EMAIL_SEND_ERROR
8. 테스트를 작성해줘.
   - base_time 자동 선택 테스트
   - API 응답 파싱 테스트
   - 빈 결과/오류 응답 테스트
   - JSON 파일 저장 테스트
   - HTML 이메일 본문 생성 테스트
   - EMAIL_ATTACH_JSON=false일 때 첨부 없음 테스트
   - EMAIL_ATTACH_JSON=true일 때 JSON 첨부 테스트
9. README에 설치, 실행, 이메일 전송, 테스트 방법을 정리해줘.
주의사항:
- 실제 API 키, Gmail 계정, 앱 비밀번호, 수신자 이메일은 코드나 문서에 쓰지 마.
- `.env`는 `.gitignore`에 넣어줘.
- `.env.example`에는 placeholder만 넣어줘.
- UI는 만들지 마. 소스 코드와 CLI 실행 흐름으로 보여주는 샘플이면 된다.
완료 후에는 파일 구조, 주요 구현 내용, 실행 방법, 테스트 방법을 요약해줘.

이 프롬프트가 좋은 이유는 다음과 같습니다.

역할(Role)을 먼저 지정했다 → "너는 소프트웨어 개발 보조자야"
목적(Why)을 명확히 밝혔다 → 누구를 위한 것이고 무엇을 이해시키려는지
대상 기술(What)을 구체적으로 지정했다 → API, 라이브러리, 버전
구현 요구사항을 번호로 나열했다 → AI가 빠뜨리지 않고 순서대로 처리 가능
결과물의 형태(파일 경로, 실행 명령어)를 예시로 제시했다 → 결과가 예측 가능해짐
하지 말아야 할 것(주의사항)을 명시했다 → 보안 사고나 불필요한 작업을 방지
완료 후 산출물(요약 보고)을 요구했다 → 결과를 검증할 수 있는 형태로 받음

즉, 이 프롬프트는 "무엇을 만들어줘"에서 끝나지 않고 목적 → 대상 → 기술 → 요구사항 → 제약조건 → 검증 방법까지 하나의 완결된 스펙 문서 형태를 갖추고 있습니다.

프롬프트 구조 분석

이 프롬프트를 분해하면 다음과 같은 7개 블록으로 나눌 수 있습니다.

블록 내용 역할

1. 역할 지정	"너는 소프트웨어 개발 보조자야"	AI가 어떤 관점으로 답할지 설정
2. 목표/목적	프로젝트 이름, 목적 설명	무엇을, 왜 만드는지 정의
3. 대상 시스템	대상 API, Endpoint	연동할 외부 시스템을 명확히 지정
4. 기술 스택	사용할 언어와 라이브러리 목록	구현 방식의 범위를 제한
5. 구현 요구사항	번호로 나열된 상세 스펙	실제로 코드에 들어갈 기능 목록
6. 주의사항	하지 말아야 할 것	보안, 범위 제한
7. 완료 후 요청	요약 보고 요청	결과를 검증 가능하게 함

바이브 코딩을 처음 접하는 사람이 흔히 하는 실수는 2번(목적)과 5번(구현 요구사항)만 쓰고 나머지를 생략하는 것입니다. 이 경우 AI는 스스로 기술 스택을 고르거나, 보안이 필요한 값을 예시 코드에 그대로 적어버리는 등 원하지 않는 결과를 만들 수 있습니다.

항목별 핵심 포인트

1) 인증키·비밀값 분리 요구

`.env.example`을 만들고 실제 인증키는 `.env`에서만 읽게 해줘.

바이브 코딩에서 가장 자주 발생하는 사고 중 하나는 AI가 예시 코드에 실제 값처럼 보이는 값을 그대로 하드코딩하는 것입니다. 이를 막기 위해 "실제 값은 .env에서만 읽는다"는 규칙을 프롬프트에 명시적으로 넣었습니다.

2) 기본값을 표나 목록으로 고정

- WEATHER_NX=60
- WEATHER_NY=127
- WEATHER_NUM_OF_ROWS=1000
...

값을 문장으로 설명하는 대신 키=값 형태로 나열하면, AI가 변수명과 기본값을 그대로 코드에 반영하기 쉬워집니다. 값이 애매하면 AI가 임의의 값을 채우게 되므로, 확정된 값은 프롬프트에서 직접 지정하는 것이 안전합니다.

3) 비즈니스 로직을 조건문 형태로 설명

각 발표시각 10분 이후부터 사용 가능하다고 보고,
당일 첫 발표 전이면 전날 2300을 사용

"자동으로 최신 발표시각을 선택해줘"라고만 하면 AI가 판단 기준을 스스로 정하게 됩니다. 여기서는 판단 기준(10분 이후, 첫 발표 전이면 전날 사용)을 구체적인 조건문 형태로 미리 정의해서 결과가 예측 가능하도록 만들었습니다.

4) CLI 명령어를 실행 예시로 제시

- 단발 실행: `python -m open_data_sample.cli`
- 이메일 전송: `python -m open_data_sample.cli --send-email`
- 주기 실행: `python -m open_data_sample.cli --monitor`

기능을 설명("이메일도 보낼 수 있게 해줘")하는 대신 실제 실행 명령어 형태로 제시하면, AI가 옵션 이름(--send-email, --monitor)까지 그대로 구현하게 되어 결과물의 일관성이 높아집니다.

5) 오류를 종류별로 미리 정의

- API_AUTH_ERROR
- API_REQUEST_ERROR
- API_EMPTY_RESULT
...

"오류 처리를 잘 해줘"라는 요청은 모호합니다. 오류 종류를 코드명으로 미리 나열하면 AI가 각 오류에 대응하는 예외 처리 분기를 빠짐없이 만들 수 있습니다.

6) 테스트 항목을 기능 단위로 명시

- base_time 자동 선택 테스트
- API 응답 파싱 테스트
- 빈 결과/오류 응답 테스트
...

테스트를 "알아서 작성해줘"라고 하면 커버리지가 들쭉날쭉해집니다. 검증하고 싶은 시나리오를 목록으로 주면, AI가 각 항목에 대응하는 테스트 함수를 하나씩 만들게 되어 결과를 검증하기 쉬워집니다.

7) 명확한 금지 사항

실제 API 키, Gmail 계정, 앱 비밀번호, 수신자 이메일은
코드나 문서에 쓰지 마.

바이브 코딩에서는 "하지 마"라는 지시가 "해줘"라는 지시만큼 중요합니다. 특히 보안과 관련된 항목은 명시적으로 금지하지 않으면 AI가 예시를 만들기 위해 실제처럼 보이는 값을 채워 넣는 경우가 있습니다.

이 프롬프트를 실제로 사용하면 생기는 일

이 프롬프트를 AI에게 전달하면, 아래와 같은 결과물이 생성됩니다.

src/open_data_sample/
  cli.py             # 실행 진입점
  config.py          # .env 설정 로딩
  forecast_time.py   # base_date/base_time 자동 계산
  weather_client.py  # API 호출과 응답 파싱
  presenter.py       # 콘솔 요약과 HTML 메일 본문 생성
  repository.py      # JSON 파일 저장
  email_share.py     # Gmail SMTP 전송
  service.py         # 전체 실행 흐름 조립
  errors.py          # 오류 코드와 안내 메시지
tests/
.env.example
.gitignore
README.md

프롬프트에서 요구한 7가지 구현 요구사항이 각각 하나의 모듈(.py 파일)로 대응되는 것을 확인할 수 있습니다. 이는 우연이 아니라, 프롬프트를 기능 단위로 나눠서 작성했기 때문에 생기는 결과입니다.

💡 학습 포인트: 프롬프트의 항목 구성이 곧 결과 코드의 모듈 구성으로 이어지는 경우가 많습니다. 프롬프트를 작성할 때 이미 "이 요구사항은 하나의 파일/함수로 분리될 수 있는가?"를 생각하면서 항목을 나누면, AI가 더 깔끔한 구조로 코드를 생성합니다.

나만의 프롬프트로 응용하기

이 프롬프트 구조를 그대로 템플릿으로 재사용할 수 있습니다.

너는 [역할]이야.
다음 목표로 [프로젝트 종류]를 만들어줘.

프로젝트 이름: [이름]
목적: [누가, 무엇을 위해 사용하는지]

대상 시스템/API: [연동 대상]
Endpoint 또는 접속 정보: [주소]

기술 스택:
- [언어/버전]
- [라이브러리 목록]

구현 요구사항:
1. [기능 1]
2. [기능 2]
...

오류 처리:
- [오류 종류 나열]

테스트:
- [검증할 시나리오 나열]

주의사항:
- [보안/제약 조건]

완료 후에는 [원하는 요약 보고 형식]을 알려줘.

이 템플릿에서 가장 중요한 것은 "구현 요구사항"을 문장이 아니라 번호가 있는 목록으로 쓰는 것입니다. 문장으로 길게 설명하면 AI가 일부 조건을 놓치기 쉽지만, 번호로 나누면 각 항목을 하나씩 처리하도록 유도할 수 있습니다.

정리

바이브 코딩에서 좋은 결과를 얻으려면 다음 3가지를 기억하면 됩니다.

목적과 대상을 먼저 명확히 한다 — 누구를 위한 것이고, 무엇과 연동하는지
요구사항을 번호로 쪼갠다 — 문장이 아니라 목록으로, 값은 키=값 형태로
하지 말아야 할 것을 명시한다 — 특히 보안, 실제 값 노출과 관련된 항목

이번 예시로 살펴본 "공공데이터 API 연동 샘플" 프롬프트는 이 3가지 원칙을 모두 지키고 있어, 실제로 AI에게 전달했을 때 목적에 맞는 프로젝트 구조와 코드가 그대로 생성되는 것을 확인할 수 있었습니다.

vibe_coding_education.md.pdf

0.34MB

'AI' 카테고리의 다른 글

AI 시대의 소프트웨어 개발 방법론: 요구사항 정의 편 (0)	2026.08.04
바이브 코딩 교육 2편: 사용자의 한 마디가 어떻게 구체적인 스펙이 되는가 (0)	2026.08.04
Claude.ai /honest 명령어 관련 정리 (1)	2026.08.03
AI 개발에서 뒤늦게 깨달은 것들: 코딩보다 먼저 정해야 하는 것들 (0)	2026.08.01
AI 시대의 소프트웨어 개발 방법론: 사람 주도 AI 개발 (1)	2026.08.01

취미생활