AI 코딩 프롬프트 잘 쓰는 법 - 바이브코딩 실전 가이드 ✍️

안녕하세요! Mojangcam입니다 😎

지난번에 바이브 코딩(Vibe Coding)이란? 글에서 AI한테 말로 시켜서 코딩하는 흐름을 소개해드렸는데요. 오늘은 그 실전편이에요. 같은 Claude Code, 같은 Cursor를 쓰는데 어떤 사람은 한 번에 원하는 코드를 뽑아내고, 어떤 사람은 10번을 다시 시켜도 산으로 가죠. 그 차이의 8할은 프롬프트에 있어요.

오늘은 제가 디스코드 봇 시리즈 24편을 쓰면서 실제로 매일 쓰고 있는 프롬프트 원칙 5가지를, 나쁜 예 vs 좋은 예로 비교하면서 정리해볼게요. 도구는 뭘 써도 상관없어요. Claude Code, Cursor, 코파일럿 전부 똑같이 적용됩니다!

🧠 왜 프롬프트가 중요할까?

AI 코딩 도구는 마법사가 아니라 말귀 밝은 신입 개발자에 가까워요. 실력은 뛰어난데, 우리 프로젝트에 대해서는 우리가 말해준 것만 알아요. 파이썬 버전이 뭔지, discord.py를 쓰는지, 어떤 스타일을 원하는지 말 안 하면 전부 추측으로 채웁니다. 그 추측이 빗나가면? 그럴듯한데 안 돌아가는 코드가 나오는 거예요.

그래서 프롬프트의 핵심은 화려한 문장이 아니라 추측할 여지를 줄여주는 것이에요. 이것만 기억하고 아래 5가지 원칙을 보시면 됩니다!

📌 원칙 1 - "뭘 만들지"가 아니라 "뭘 원하는지"부터

텍스트

❌ 나쁜 예: 봇 코드 짜줘

텍스트

✅ 좋은 예: 디스코드 봇에 /청소 명령어를 추가하고 싶어.
실행하면 해당 채널의 최근 메시지를 지정한 개수만큼 삭제하고,
"N개 삭제 완료!"라고 본인에게만 보이는 메시지로 알려줘.
관리자 권한이 있는 사람만 쓸 수 있어야 해.

하나씩 뜯어볼게요 💡

목표 : 무엇을 위한 기능인지 (메시지 청소)
동작 : 실행하면 정확히 무슨 일이 일어나는지 (개수 지정 → 삭제 → 확인 메시지)
조건 : 제약사항 (관리자만, 본인에게만 보이게)

"봇 코드 짜줘"는 AI 입장에서 백지수표예요. 어떤 봇인지, 무슨 기능인지 전부 찍어야 하죠. 목표·동작·조건 세 가지만 넣어도 결과물이 완전히 달라집니다.

📌 원칙 2 - 환경·버전·기존 코드를 알려주세요

텍스트

✅ 예시: 파이썬 3.12, discord.py 2.x 환경이야.
지금 봇은 Cog 구조로 되어 있고, 명령어는 전부 슬래시 명령어로 만들고 있어.
토큰은 .env에서 python-dotenv로 불러와.
이 구조에 맞춰서 만들어줘.

버전을 안 알려주면 AI가 discord.py 1.x 시절 문법(옛날 자료가 인터넷에 많거든요)을 섞어 쓰는 일이 진짜 자주 일어나요. 라이브러리 버전, 파이썬 버전, 프로젝트 구조. 이 세 가지는 습관처럼 붙여주세요.

특히 Claude Code나 Cursor처럼 파일을 직접 읽는 도구라면 "기존 cogs/admin.py 스타일 참고해서"처럼 참고할 파일을 지목하는 게 최고예요. 백 마디 설명보다 코드 한 파일이 더 정확한 컨텍스트가 됩니다.

📌 원칙 3 - 한 번에 하나씩, 작게 쪼개기

텍스트

❌ 나쁜 예: 투표 기능이랑 경고 누적 제재랑 환영 메시지 전부 만들어줘

텍스트

✅ 좋은 예: 먼저 투표 기능만 만들자.
잘 돌아가는 거 확인하면 다음 기능으로 넘어갈게.

한 번에 여러 기능을 시키면 코드가 길어지고, 어딘가 하나 틀렸을 때 어디가 문제인지 찾는 비용이 확 올라가요. 기능 하나 → 실행해보고 → 다음 기능. 이 리듬이 바이브코딩의 정석입니다. 급할수록 돌아가세요!

📌 원칙 4 - 에러는 요약하지 말고 전문을 복붙

텍스트

❌ 나쁜 예: 실행하니까 인텐트 어쩌구 에러 나는데?

텍스트

✅ 좋은 예: 아래 에러가 나. 봇 실행 직후에 바로 죽어.

discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting
privileged intents that have not been explicitly enabled in the
developer portal.

개발자 포털 설정은 아직 안 건드렸어.

에러 메시지에는 원인을 특정할 단서(에러 종류, 파일, 줄 번호)가 다 들어 있어요. 요약하는 순간 그 단서가 날아갑니다. 전문 복붙 + 언제 발생하는지 + 내가 뭘 해봤는지 세 가지를 주면 해결 확률이 급상승해요.

📌 원칙 5 - 코드보다 계획을 먼저 시키기

텍스트

✅ 예시: 아직 코드 쓰지 마.
이 기능을 구현하려면 어떤 파일을 어떻게 고쳐야 하는지 계획부터 보여줘.
계획 확인하고 나서 시작할게.

조금 규모가 있는 작업이라면 이 한 줄이 정말 큰 차이를 만들어요. 계획 단계에서 "어? DB 구조를 바꾸려고 하네, 그건 아닌데" 하고 미리 잡으면, 다 만들어진 코드를 갈아엎는 것보다 훨씬 싸게 먹히거든요. Claude Code에는 아예 플랜 모드(Plan Mode)가 있어서 Shift+Tab으로 켤 수 있어요. 코드 수정 없이 계획만 세워주는 모드라 이 원칙과 찰떡입니다.

🛠️ 실전 - 프롬프트 흐름 그대로 따라가기

실제로 봇에 기능 하나를 추가할 때 제 대화 흐름은 이래요.

환경 설명 + 목표 : "discord.py 2.x, Cog 구조. /추첨 명령어를 만들 거야. 참여 버튼 누른 사람 중 1명 뽑는 기능이야."
계획 요청 : "코드 쓰기 전에 구현 계획부터 보여줘."
계획 수정 : "참여자 저장은 DB 말고 일단 메모리로 충분해. 단순하게 가자."
구현 : "좋아, 그 계획대로 만들어줘."
에러 왕복 : 에러 나면 전문 복붙 → 고침 → 재실행
마무리 손질 : "임베드 색은 초록으로, 당첨자 멘션 넣어줘."

포인트는 4번에서 끝나는 게 아니라 5~6번 왕복까지가 한 세트라는 거예요. 첫 결과물이 80점이면 성공이에요. 나머지 20점은 대화로 채우면 됩니다!

💡 반복 지시는 규칙 파일에 저장하세요 (CLAUDE.md)

매번 "토큰은 .env로, 주석은 한국어로..."를 반복하기 귀찮죠? Claude Code는 프로젝트 폴더에 CLAUDE.md 파일을 만들어두면 매 세션 자동으로 읽어요. Cursor도 Rules 기능이 같은 역할을 합니다.

Markdown

# CLAUDE.md 예시
- 파이썬 3.12 / discord.py 2.x / 슬래시 명령어만 사용
- 토큰·API 키는 .env + python-dotenv로 로딩 (하드코딩 금지)
- 새 기능은 Cog로 분리해서 cogs/ 폴더에
- 주석과 설명은 한국어로

이렇게 4~5줄만 적어둬도 매 대화의 품질이 일정해져요. 프롬프트 원칙 2번(환경 알려주기)을 자동화하는 셈이죠.

💡 보너스 - Claude Code 8월 업데이트 한 줄 정리

프롬프트 얘기가 나온 김에, 이번 달 Claude Code에 바뀐 것들도 짚고 갈게요 (8월 말 기준 v2.1.251).

오토 모드(Auto Mode) 기본화 (8/14) : 새 세션이 이제 매번 허락을 묻지 않는 오토 모드로 시작해요. 별도 분류 모델이 위험한 행동을 걸러주는 방식인데, 예전 방식이 좋다면 Shift+Tab으로 언제든 바꿀 수 있어요. 자세한 내용은 오토 모드 총정리 글에서 다뤘어요.
/design 스킬 프리뷰 (8/17) : UI 디자인 관련 작업을 도와주는 스킬이 프리뷰로 추가됐어요.
Concise 출력 스타일 : 설명을 짧게 해주는 출력 스타일이 생겨서, 답변이 길어서 답답했던 분들에게 유용해요.

오토 모드 기본화는 작업 흐름이 꽤 달라지는 변화라, 처음 켰을 때 당황하지 마시고 전환 안내 문구를 잘 읽어보세요!

📌 자주 하는 실수 모음

"알아서 잘 해줘" → AI는 '알아서'를 못 해요 → 목표·동작·조건을 말해주기 (원칙 1)
버전 생략 → 구버전 문법이 섞여 나옴 → 파이썬·라이브러리 버전 명시 (원칙 2)
한 번에 왕창 시키기 → 디버깅 지옥 → 기능 하나씩 확인하며 진행 (원칙 3)
에러 요약해서 전달 → 단서 소실 → 에러 전문 복붙 (원칙 4)
결과물 검증 생략 → 그럴듯한 버그 코드가 그대로 남음 → 반드시 직접 실행해보고, 이해 안 되는 코드는 "이 부분 설명해줘"라고 물어보기

특히 5번이 중요해요. 바이브코딩이라고 해서 코드를 안 읽어도 된다는 뜻은 아니에요. 돌려보고, 물어보고, 이해하고 넘어가기. 이게 실력도 같이 느는 바이브코딩입니다.

📌 마무리

오늘 배운 내용을 요약하면:

프롬프트는 화려한 문장이 아니라 추측을 줄이는 정보 (목표·동작·조건)
환경·버전·참고 파일을 알려주면 정확도 급상승
작게 쪼개고, 에러는 전문 복붙, 큰 작업은 계획부터
반복 지시는 CLAUDE.md / Rules에 저장

이 5가지 원칙만 몸에 붙여도 AI 코딩 결과물이 눈에 띄게 달라질 거예요. 다음에도 실전에서 바로 써먹을 수 있는 팁으로 돌아올게요. 기대해주세요 🙌