클로드 코드 제대로 써먹는 프롬프트 작성 팁 6가지

바이브 코딩에서 좋은 결과물을 얻기 위해서는 프롬프트의 품질이 중요합니다. 같은 에이전트를 만들더라도 요청 방식에 따라 결과물의 완성도가 크게 달라질 수 있습니다. 이 글에서는 효과적인 프롬프트 작성법을 실제 예시와 함께 상세히 설명해보겠습니다.

프롬프트 원칙 1: 배경·목적·제약을 먼저 설명하라

가장 흔한 실수는 결과물만 요청하는 것입니다. “~ 만들어 줘.”라는 모호한 요청보다 배경과 목적을 설명해야 클로드 코드가 최적의 설계 과정을 거쳐 사용자의 상황에 맞는 가장 정확한 결과물을 만들어낼 수 있습니다.

나쁜 프롬프트 예시

뉴스 수집 에이전트 만들어 줘

좋은 프롬프트 예시

나는 IT 스타트업에서 사업 개발을 담당하고 있어. 
매일 아침 출근 전에 AI, 클라우드, 핀테크 분야 주요 뉴스를 
5분 안에 파악하고 싶어.

이를 위해 다음 기능을 하는 에이전트를 만들어 줘:
- 매일 오전 7시 자동 실행
- 키워드: AI 기술, 클라우드 서비스, 핀테크 규제
- 각 키워드당 최신 뉴스 3건 수집
- 각 뉴스의 비즈니스 영향도를 높음/보통/낮음으로 분류
- 영향도 높음 뉴스만 모아서 Gmail로 발송
- 메일 제목: ‘[일일 뉴스 브리핑] YYYY-MM-DD’

차이가 보이나요? 좋은 프롬프트는 ‘내가 누구인지’, ‘무엇을 달성하고 싶은지’, ‘구체적인 요구사항이 무엇인지’를 명확하게 담고 있습니다. 이 세 가지 정보가 있어야 클로드 코드가 내 상황에 맞는 최적의 에이전트를 설계할 수 있습니다.

목표(뉴스 수집)가 동일하지만 배경이 다른 프롬프트 예시

• 예시1 마케팅 담당자

경쟁사 마케팅 캠페인 동향을 매일 5건씩 모아서 분석하고 마케팅 팀 슬랙 채널에 공유하고 싶어.

→ 웹 검색 + 분석 + 슬랙 연동 에이전트)

• 예시2 주식 투자자

기술주 관련 뉴스와 실시간 주가 변동을 함께 보여 주고, 매도/매수 신호가 나타나면 즉시 알림을 받고 싶어.

→ 웹 검색 + 금융 데이터 API + 푸시 알림 에이전트)

• 예시3 대학 신문 편집자

캠퍼스 관련 뉴스를 자동으로 수집하고, 기사 가치도별로 분류한 후 구글 문서로 편집 대기 목록을 만들어 줘.

→ 웹 검색 + 분류 + 구글 문서 에이전트)

​

프롬프트 원칙 2: 출력 형식을 구체적으로 명시하라

에이전트 요청 시 출력 형식을 구체적으로 명시해야 의도에 맞는 완성도 높은 결과물을 얻을 수 있습니다. 이메일 본문에는 마크다운, PDF 보고서에는 표와 그래프, JSON 데이터 연동일 때는 구조화된 형식 등과 같이 매체나 용도에 맞춰 원하는 구조를 명확히 제시하는 것이 중요합니다.

나쁜 프롬프트 예시

분석 결과를 메일로 보내 줘.

좋은 프롬프트 예시

분석 결과를 메일로 보내 줘. 메일 형식은 다음과 같아: 

제목: [뉴스 브리핑] {날짜} 

오늘의 핵심 뉴스 ({영향도 높음 건수}건) 

1. {뉴스 제목} 
요약: {2-3줄 요약} 
영향도: 높음 
링크: {URL} 

---
전체 수집: {총 건수}건 | 높음: {건수} | 보통: {건수} | 낮음: {건수}

일반적인 출력 형식 선택 기준

• HTML 이메일:웹처럼 배경색, 이미지, 테이블 등 풍부한 스타일링이 필요할 때 사용하지만, 메일 클라이언트마다 렌더링된 화면이 다를 수 있음을 고려해야 합니다.
• 순수 텍스트 메일:스팸 필터에 걸릴 확률이 낮고 모든 기기에서 동일하게 보이며, 가장 높은 신뢰도와 호환성을 보장합니다.
• 마크다운 형식: 구조적이면서도 가독성이 높아, 깃허브(GitHub)나 슬랙(Slack)처럼 마크다운을 지원하는 플랫폼에 정보를 보낼 때 최적입니다.
• PDF 첨부: 보고서나 공식 문서처럼 고정된 레이아웃이 필요하거나, 파일을 다운로드하여 오프라인에서 읽어야 하는 경우에 적합합니다.
• JSON 데이터:사람이 읽기보다는 다른 시스템이나 프로그램과 연동하여 데이터를 자동으로 파싱하고 처리해야 할 때 가장 효율적입니다.

​

프롬프트 원칙 3: 예외 케이스와 오류 처리를 미리 말하라

예외 처리 없이 만든 에이전트는 예상 밖의 상황이 오면 그냥 중단되거나 이상한 결과를 만들지만, 예외 처리를 미리 정의하면 어떤 상황이 와도 에이전트가 적절히 처리하고 사용자에게 알려주므로 에이전트의 신뢰도가 달라집니다.

일반적인 예외 케이스

• 검색 결과 부재 시:메일을 발송하지 않거나, 검색 결과가 없음을 알리는 요약 메시지를 전송하여 불필요한 빈 메일 확인을 방지합니다.
• 메일 발송 실패 시:자동 재시도를 수행하거나, 즉각적인 조치가 가능하도록 텔레그램 등 다른 채널로 오류 알림을 보냅니다.
• 파일 부재 시:유사한 파일명을 제안하거나 사용자에게 알림을 보내어, 경로 설정이나 파일 생성 상태를 즉시 점검하게 합니다.
• API 한도 초과 시:작업을 다음 날로 미루거나 중요도가 높은 일부 데이터만 우선 처리하여 시스템의 연속성을 유지합니다.
• 네트워크 타임아웃 발생 시:일정 시간 후 재시도 로직을 가동하거나, 수집된 부분 결과라도 반환하여 전체 작업이 멈추지 않게 합니다.
• 인증 토큰 만료 시:오류 발생 사실과 함께 갱신 필요 알림을 보내거나, 사전에 등록된 자격 증명을 통해 자동으로 재인증을 시도합니다.

좋은 프롬프트 예시

예외 처리 예시:

웹 검색 결과가 없는 키워드는 건너뛰고 나머지는 진행해 줘.

Gmail 발송 실패 시 3번까지 재시도하고, 그래도 실패하면 텔레그램으로 알림 보내 줘.

네트워크 오류 발생 시 최대 5초 대기 후 1회 재시도

모든 오류는 ./logs/error.log 파일에 타임스탬프와 함께 저장

5개 이상의 오류가 쌓이면 알림 메일 발송

프롬프트 원칙 4: 단계별로 나누어 요청하라

복잡한 에이전트를 만들 때는 한 번에 처리하기보다 단계별로 나누어 요청하는 것이 훨씬 안정적입니다. 이는 ① 컨텍스트 창(Context Window)의 한계로 인한 중요 정보 누락을 방지하고, ② 문제 발생 시 오류 원인을 쉽게 격리(Error Isolation)하여 수정할 수 있도록 도와줍니다.

뉴스 수집 에이전트를 단계별로 만든다면 다음과 같습니다.

1단계: 뉴스 수집 에이전트 생성 및 테스트

• 요청 내용

뉴스 수집 에이전트 하나만 만들고 테스트해 줘.

• 확인 포인트: 실제로 뉴스가 수집되는지, 데이터 구조가 올바른지 확인

2단계: 영향도 분류 기능 추가

• 요청 내용

수집된 뉴스에 영향도 분류 기능 추가해 줘.

• 확인 포인트: 분류 기준이 적절한지, 결과가 기대에 맞는지 확인

3단계: 메일 발송 기능 추가

• 요청 내용

분류 완료된 결과를 메일로 보내는 기능 추가해 줘.

• 확인 포인트: 메일 형식 및 실제 수신 여부 확인

4단계: 자동 실행 스케줄 등록

• 요청 내용

이 전체를 매일 오전 7시에 자동 실행하도록 스케줄 등록해 줘.

• 확인 포인트: 스케줄러의 정상 동작 여부 확인

프롬프트 원칙 5: 수정 요청은 구체적으로

결과가 마음에 들지 않을 때는 ‘무엇이 문제인지’, ‘왜 문제인지’, ‘어떻게 바뀌어야 하는지’ 세 가지를 함께 담아 수정을 요청해야 가장 효과적으로 원하는 방향에 도달할 수 있습니다.

막연한 수정 요청

결과가 별로야. 다시 만들어 줘.

구체적인 수정 요청

두 가지를 수정해 줘: 

1. 현재 메일에 뉴스가 제목만 있는데, 
각 뉴스 아래에 2-3문장 요약을 추가해 줘. 

2. 영향도 '높음'으로 분류된 기준이 너무 느슨한 것 같아.
현재 10건 중 8건이 높음으로 나오는데,
실제로 즉각적인 비즈니스 행동이 필요한 뉴스만 높음으로

분류되도록 기준을 강화해 줘.

‘나쁜 요청’에는 클로드 코드가 스스로 채워야 할 질문들이 숨어 있는데, 아래 예시에서는 그 숨은 질문들을 괄호로 나타내 보았습니다. ‘좋은 요청’은 이미 요청 안에 그 질문들의 답이 들어 있는 요청입니다.

나쁜 수정 요청

메일이 너무 길어

 → (어느 부분이? 몇 줄까지가 적당한지?)

뉴스 분류가 잘못 되었어 

→ (어떤 뉴스? 왜 잘못된 것인지?)

성능이 안 좋아 

→ (어디가 느린지? 목표는?)

좋은 수정 요청

메일이 현재 3000자인데 500자 이내로 줄여 줘. 각 뉴스의 요약 문장을 1-2줄로 단축하고 링크는 제거해 줘.

AI 관련 뉴스 3개를 실행해 본 결과 2개는 '높음'으로 분류되었는데, 둘 다 장기 기술 뉴스라서 낮음이 맞아. 높음 기준을 '3개월 내 즉시 행동이 필요한 경우'로 더 엄격하게 조정해 줘.

지난 3회 실행에서 평균 45초가 걸렸는데, 30초 이내로 줄이고 싶어. 어디가 병목일까? 병목을 제거하는 방식을 제안해 줄 수 있어?

프롬프트 원칙 6: 유형별 프롬프트 템플릿

유형별 프롬프트 템플릿입니다. 그대로 사용하거나 원하는 내용으로 채워서 사용하세요.

새 에이전트 생성

나는 [직업/역할]이야. 
[문제 상황]을 자동화하고 싶어. 

다음 기능을 하는 에이전트를 만들어 줘:
- 트리거: [언제 실행되는가? 매일 몇 시? 특정 이벤트?]
- 입력: [어떤 데이터를 사용하는가?]
- 처리: [어떤 작업을 수행하는가?]
- 출력: [결과를 어떻게 전달하는가?]

예외 처리:
- [예외 상황 1]: [처리 방법]
- [예외 상황 2]: [처리 방법]

기존 에이전트 기능 추가 

기존 [에이전트 이름]에 [새 기능]을 추가해 줘.


추가 기능 상세:
- [기능 설명]
- 기존 [특정 부분] 다음에 실행되어야 해.
- 이미 있는 [기존 기능]은 유지해야 해.

오류 수정 요청

아래 오류가 발생했어. 원인 분석하고 수정해 줘.

[오류 메시지 전체 붙여 넣기]

이 오류는 [어떤 상황에서] 발생했어.
기대했던 동작은 [기대 동작]이야.

결과 형식 수정

[현재 출력 형식의 문제점]이 마음에 안 들어.
​
다음과 같은 형식으로 변경해 줘:
[원하는 출력 형식 예시를 직접 작성]

프롬프트 작성에서 가장 중요한 것은 ‘내가 원하는 것’을 구체적으로 아는 것입니다. 에이전트를 만들기 전에 잠깐 시간을 들여 정확히 무엇을 자동화하고 싶은가를 정리하면 훨씬 좋은 결과가 나옵니다.

• 이 글은 길벗에서 출간된 책 <클로드 코드 & 오픈클로> 에서 발췌·편집한 글입니다. 원문은 [여기]에서 볼 수 있습니다.

ⓒ요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.