Claude Code에 같은 작업을 시켜도 어떤 날은 한 번에 끝나고 어떤 날은 한참 헤맨다면, 문제는 모델이 아니라 프롬프트일 가능성이 커요. Claude Code는 우리가 건넨 요청을 읽고, 의도를 추론한 뒤 코드를 고쳐요. 이 추론 단계에 빈틈이 많을수록 결과가 흔들려요. 다행히 결과를 망치는 패턴은 몇 가지로 정해져 있어서, 그 실수만 알면 바로 고칠 수 있어요.
아래는 초보자가 가장 자주 밟는 프롬프트 실수 7가지예요. 먼저 한눈에 보고, 이어서 잘못된 예시와 고친 예시를 하나씩 비교해 볼게요.
| 실수 | 핵심 문제 |
|---|
| 1. 모호하게 부탁하기 | 구체성 부족 |
| 2. 이유를 안 알려주기 | 맥락 부족 |
| 3. 손대지 말 곳을 안 정하기 | 범위 부족 |
| 4. 한 번에 큰 작업 시키기 | 작업 분할 없음 |
| 5. 계획 없이 바로 코드 시키기 | 계획 모드 미사용 |
| 6. 한 대화에서 모든 작업 하기 | 컨텍스트 관리 부재 |
| 7. 같은 설명을 매번 반복하기 | 프로젝트 메모 미사용 |
실수 1. 모호하게 부탁하기
가장 흔한 실수예요. "버튼 좀 예쁘게 해줘" 같은 요청은 사람마다 해석이 달라요. Claude도 마찬가지로 추측에 기댈 수밖에 없고, 그 추측이 빗나가면 엉뚱한 결과가 나와요.
Before · "로그인 화면 좀 손봐줘"
After · "로그인 화면의 입력칸 사이 간격을 넓히고, 로그인 버튼을 화면 너비에 꽉 차게 키워줘"
고치는 법은 간단해요. 색·크기·위치·동작처럼 눈에 보이고 확인 가능한 말로 바꾸면 돼요. 부탁을 보내기 전에 "이 문장을 다른 사람이 읽어도 똑같이 이해할까?"를 한 번 자문해 보세요.
실수 2. 이유를 안 알려주기
무엇을 원하는지는 적었는데 왜 그게 필요한지는 빼먹는 경우예요. 이유를 모르면 Claude는 표면적인 요청만 처리하고, 정작 중요한 의도는 놓쳐요.
Before · "글씨 크기를 키워줘"
After · "어르신 사용자가 많아서 글씨가 잘 안 보인다는 피드백이 있었어. 본문 글씨를 읽기 편한 크기로 키워줘"
맥락을 한 줄 덧붙이면 Claude의 판단이 의도에 정렬돼요. 단순히 크기만 키우는 게 아니라 가독성까지 함께 고려한 결과를 받게 돼요.
실수 3. 손대지 말 곳을 안 정하기
요청한 부분은 잘 고쳤는데 멀쩡하던 다른 부분이 같이 바뀌어 본 적 있나요? 범위를 정해주지 않아서 생기는 일이에요.
Before · "결제 기능 오류를 고쳐줘"
After · "결제 기능 오류를 고쳐줘. 결제 관련 파일만 수정하고, 장바구니나 상품 목록 코드는 건드리지 마"
경계를 한 문장으로 정해주면 예상 밖의 변경을 막을 수 있어요. 특히 작업이 익숙하지 않을수록 이 한 줄이 안전장치가 돼요.
지금까지의 실수 1~3은 결국 구체성·맥락·범위라는 세 가지가 빠진 경우예요. 좋은 프롬프트는 이 셋을 모두 담고 있어요.
실수 4. 한 번에 큰 작업 시키기
"쇼핑몰 만들어줘" 같은 거대한 요청은 추측할 여지가 너무 넓어 실패 확률이 높아요. 작업이 절반쯤 진행됐을 때 방향이 어긋난 걸 발견하면 처음부터 다시 해야 하죠.
큰 작업은 이렇게 쪼개세요.
- 전체 계획부터 요청해요 — "어떤 화면이 필요한지 계획만 먼저 알려줘"
- 계획에서 한 단계씩 맡겨요 — "그럼 상품 목록 화면부터 만들어줘"
- 한 단계가 끝나면 확인하고 다음으로 넘어가요
요청을 한 문장으로 다 설명하기 어렵다면, 그건 쪼개라는 신호예요. 작은 단계는 검증과 되돌리기가 쉬워서 전체적으로 더 빠르게 진행돼요.
실수 5. 계획 없이 바로 코드 시키기
Claude Code에는 코드를 고치기 전에 계획 모드로 "이렇게 진행하겠다"는 계획을 먼저 보여주는 기능이 있어요. 이걸 건너뛰고 곧장 코드를 시키면, 의도가 어긋났을 때 이미 만들어진 코드를 되돌려야 해요.
Before · "회원가입 기능 만들어줘"
After · "회원가입 기능을 만들 건데, 바로 작업하지 말고 어떤 순서로 진행할지 계획부터 보여줘"
계획 단계에서 방향을 잡으면 코드가 만들어지기 전에 바로잡을 수 있어요. 잘못된 결과를 받고 다시 하는 것보다 훨씬 빠르고 안전해요.
실수 6. 한 대화에서 모든 작업 하기
대화를 길게 이어갈수록 Claude가 내 프로젝트를 더 잘 안다고 생각하기 쉽지만, 어느 지점부터는 반대예요. 참고할 내용이 너무 많아지면 초점이 흐려지고, 앞서 정한 규칙을 놓치기 시작해요.
- 작업의 큰 묶음이 바뀌면 대화를 새로 시작하거나 정리해요
- 긴 대화는 핵심만 남기고 요약해 둬요
- 오래 유지돼야 할 규칙은 대화가 아니라 프로젝트 메모에 둬요
대화 하나에 두세 작업을 몰아넣으면 Claude가 이전 작업과 지금 작업을 뒤섞기 쉬워요. 작업이 바뀌면 대화도 끊어주는 게 품질을 지키는 길이에요.
실수 7. 같은 설명을 매번 반복하기
"한국어로 진행해줘", "이 폴더는 건드리지 마"처럼 매번 똑같이 적는 설명이 있다면, 그건 CLAUDE.md라는 프로젝트 메모에 한 번만 적어두면 돼요. 프로젝트 폴더에 이 파일을 두면 Claude가 모든 작업에서 자동으로 참고해요.
CLAUDE.md에 적어두면 좋은 것들이에요.
- 사용하는 언어·기술과 진행 규칙
- 지켜야 할 디자인 톤이나 코딩 방식
- 절대 손대면 안 되는 폴더나 파일
코드가 아니라 그냥 글이라 누구나 쓸 수 있어요. 한 번 적어두면 매 요청마다 같은 맥락을 반복할 필요가 없어요.
자주 묻는 질문
Q.한국어로 프롬프트를 써도 결과가 잘 나오나요?
A.네, 한국어 요청도 잘 처리해요. 결과를 가르는 건 언어가 아니라 구체성이에요. 한국어든 영어든 모호하면 흔들리고, 또렷하면 안정적이에요.
Q.실수를 다 피했는데도 결과가 이상하면 어떻게 하나요?
A.요청이 너무 컸을 가능성이 커요. 작업을 더 작은 단계로 쪼개고, 계획 모드로 방향을 먼저 확인한 뒤 한 단계씩 다시 진행해 보세요.
Q.CLAUDE.md는 꼭 만들어야 하나요?
A.필수는 아니지만, 같은 프로젝트를 여러 번 작업한다면 강력히 권해요. 반복 설명이 사라지고 결과의 일관성이 눈에 띄게 올라가요.
Q.Claude Code는 무료로도 쓸 수 있나요?
A.플랜에 따라 사용 범위가 달라요. 요금제와 제공 범위는 시기별로 바뀔 수 있으니, 사용 전 공식 안내에서 최신 정보를 확인하세요.
일곱 가지 실수를 한 줄로 줄이면, 결국 추측할 여지를 줄이는 것이 핵심이에요. 구체성·맥락·범위를 채우고, 큰 일은 쪼개고, 계획을 먼저 보고, 대화와 메모를 관리하세요. 다음 작업부터 이 중 하나만 바꿔도 결과가 달라지는 걸 느낄 수 있어요.
댓글
댓글 쓰기