Claude Code 결과물의 완성도를 높이는 프롬프트 6원칙

Claude Code와 같은 코딩 에이전트는 코드 한 조각만 생성하는 도구가 아니라 저장소를 탐색하고, 여러 파일을 수정하며, 테스트와 명령을 실행할 수 있는 작업 환경이다. 따라서 결과물의 품질은 문장이 얼마나 그럴듯한가보다 작업 범위와 검증 방법을 얼마나 명확히 정의했는가에 크게 좌우된다.

좋은 프롬프트는 긴 설명문이 아니라 실행 가능한 작업 명세다. 무엇을 만들지뿐 아니라 왜 필요한지, 어떤 조건을 지켜야 하는지, 실패를 어떻게 처리할지, 무엇을 통과하면 완료인지까지 전달해야 한다.

먼저 구분할 것: 프롬프트와 실행 환경

바이브 코딩은 자연어로 의도를 전달하고 AI 에이전트가 구현을 맡는 협업 방식이다. 그러나 자연어로 요청했다는 사실이 코드의 정확성이나 운영 안정성을 보장하지는 않는다.

Claude Code 작업에는 다음 요소가 함께 작용한다.

프롬프트만 잘 작성해도 모든 문제가 해결되는 것은 아니다. 예를 들어 Claude Code가 예약 실행 코드를 만들 수는 있지만, 컴퓨터가 꺼져 있을 때도 작업을 실행하려면 별도의 서버, CI 서비스 또는 운영체제 스케줄러가 필요하다. 이메일 전송 역시 실제 공급자의 인증 정보와 발송 권한이 없으면 완성할 수 없다.

원칙 1. 배경·목적·제약을 먼저 설명한다

뉴스 수집 에이전트 만들어 줘처럼 결과물 이름만 제시하면 에이전트는 사용자, 데이터 출처, 실행 환경과 성공 기준을 추측해야 한다. 같은 뉴스 수집기라도 사업 개발 담당자, 투자자, 대학 신문 편집자가 필요로 하는 출처와 분류 기준은 다르다.

불충분한 요청

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

개선한 요청

나는 IT 스타트업의 사업 개발 담당자다.
매일 업무 시작 전에 AI, 클라우드, 핀테크 분야에서
사업 제휴나 제품 전략에 영향을 줄 뉴스를 빠르게 확인하려고 한다.

목표:
- 지정한 키워드별로 최신 기사 후보를 수집한다.
- URL이 같은 기사와 제목이 유사한 중복 기사를 제거한다.
- 3개월 안에 제품 또는 제휴 의사결정이 필요한지를 기준으로
  영향도를 높음, 보통, 낮음으로 분류한다.
- 결과를 한국어 이메일 브리핑으로 만든다.

제약:
- 현재 저장소의 Python 버전과 패키지 관리 방식을 유지한다.
- 새 라이브러리를 추가하기 전 필요성과 대안을 설명한다.
- API 키와 이메일 비밀번호를 코드나 로그에 기록하지 않는다.
- 실제 메일 발송 전에는 미리보기 파일만 생성한다.

먼저 저장소 구조와 실행 방법을 조사한 뒤 구현 계획을 제안해 줘.
모르는 환경 정보는 추측하지 말고 질문 목록으로 정리해 줘.

좋은 배경 정보에는 다음 네 가지가 들어간다.

1. 사용자와 이용 상황: 누가, 언제, 어떤 의사결정에 사용하는가
2. 목표: 코드 작성 자체가 아니라 해결해야 할 문제는 무엇인가
3. 제약: 유지해야 할 기술, 보안 규칙, 비용 또는 시간 한도는 무엇인가
4. 비목표: 이번 변경에서 명시적으로 제외할 기능은 무엇인가

비목표를 적으면 범위가 무한히 커지는 것을 막을 수 있다. 예를 들어 이번 단계에서는 예약 실행과 실제 이메일 발송은 제외한다고 정하면 수집과 분류 로직부터 안정적으로 검증할 수 있다.

원칙 2. 원하는 출력 형식을 출력 계약으로 만든다

메일로 보기 좋게 보내 줘는 사람마다 다르게 해석된다. 출력 형식은 예시만 보여 주기보다 필수 필드, 허용 값, 누락 처리, 정렬 순서를 함께 정의해야 한다.

이메일 제목:
[뉴스 브리핑] {YYYY-MM-DD} 오늘의 핵심 뉴스

본문의 기사 형식:
1. {제목}
요약: {한국어 1~2문장}
영향도: {높음|보통|낮음}
판정 이유: {1문장}
출처: {매체명}
링크: {원문 URL}

정렬 규칙:
1. 영향도 높은 순서
2. 영향도가 같으면 게시 시각이 최신인 순서

하단 통계:
- 전체 기사 수
- 영향도별 기사 수
- 검색 결과가 없었던 키워드

제약:
- 요약에서 원문에 없는 수치나 주장을 만들지 않는다.
- 날짜를 확인할 수 없으면 날짜를 추정하지 않고 '확인 불가'로 표시한다.
- 링크가 없는 항목은 최종 브리핑에서 제외한다.

프로그램 간에 결과를 전달해야 한다면 사람이 읽는 예시와 함께 JSON 스키마 또는 타입 정의를 요구하는 것이 좋다.

{
  "title": "string",
  "summary": "string",
  "impact": "high | medium | low",
  "reason": "string",
  "source": "string",
  "url": "absolute URL",
  "published_at": "ISO 8601 string | null"
}

출력 계약에는 형식뿐 아니라 의미도 포함된다. impact: high가 무엇을 뜻하는지 판정 기준이 없다면 JSON 문법은 정확해도 분류 결과는 일관되지 않을 수 있다.

원칙 3. 예외 상황과 복구 정책을 명시한다

운영 코드의 완성도는 정상 경로보다 실패 경로에서 드러난다. 프롬프트에는 예상 가능한 실패, 재시도 가능 여부, 사용자에게 알릴 조건, 기록하면 안 되는 정보를 함께 적어야 한다.

다음처럼 정책을 구체적으로 요청할 수 있다.

네트워크 시간 초과는 재시도 가능한 오류로 처리해 줘.
재시도 사이에는 대기 시간을 두고, 최대 횟수를 넘으면 해당 출처만 실패 처리해 줘.
인증 오류와 잘못된 요청은 반복해도 해결되지 않으므로 즉시 중단해 줘.

모든 오류 로그에는 시각, 작업 단계, 출처, 오류 유형을 남기되
API 키, 이메일 주소 전체, 인증 헤더, 기사 본문 전문은 기록하지 마.
프로세스 종료 상태로 전체 성공, 부분 성공, 전체 실패를 구분해 줘.

세 번 재시도나 5초 대기 같은 값은 보편적인 정답이 아니다. 외부 서비스의 공식 제한, 작업의 긴급성, 중복 실행 위험에 따라 프로젝트에서 결정해야 한다. 결제나 메시지 발송처럼 부작용이 있는 작업은 멱등성 보장 없이 자동 재시도하면 중복 처리될 수 있다.

원칙 4. 계획·최소 구현·검증 순서로 점진 개발한다

여러 외부 서비스와 자동 실행을 한 번에 연결하면 오류 원인을 분리하기 어렵다. 구현을 작은 검증 단위로 나누면 각 단계의 입력과 출력을 확인할 수 있다.

권장 진행 순서

1. 저장소 구조, 관련 파일, 실행 명령을 조사한다.
2. 코드 변경 전에 계획과 영향을 받을 파일을 제시하게 한다.
3. 하나의 키워드와 고정된 샘플 데이터로 수집 기능을 구현한다.
4. 중복 제거와 영향도 분류를 각각 테스트한다.
5. 이메일은 실제 발송 대신 로컬 미리보기로 검증한다.
6. 테스트가 통과한 뒤 실제 공급자 연동과 예약 실행을 추가한다.

첫 요청은 다음과 같이 제한할 수 있다.

지금은 1단계만 수행해 줘.
저장소를 조사하고 다음 내용을 보고해 줘.
- 현재 애플리케이션의 진입점
- 관련 모듈과 테스트 파일
- 사용하는 패키지 관리 및 테스트 명령
- 변경이 필요할 것으로 예상되는 파일
- 구현 전에 결정해야 할 질문

아직 파일은 수정하지 마.

계획을 검토한 다음에는 변경 범위를 좁혀 구현한다.

승인한 계획 중 뉴스 수집과 중복 제거만 구현해 줘.
분류, 이메일 발송, 예약 실행은 추가하지 마.
고정된 테스트 데이터로 실행할 수 있게 하고,
수정한 파일과 실행한 테스트 결과를 마지막에 요약해 줘.

Claude Code 환경에서 계획 전용 모드를 사용할 수 있다면 탐색과 설계 단계에서 활용할 수 있다. 다만 계획이 그럴듯하다는 사실은 구현이 정확하다는 뜻이 아니므로 실제 테스트와 코드 검토가 뒤따라야 한다.

원칙 5. 피드백을 실패 사례와 수치로 전달한다

결과가 별로다, 성능이 느리다, 분류가 틀렸다는 수정 방향을 결정하기 어렵다. 현재 상태, 기대 상태, 재현 입력, 허용 가능한 변화 범위를 전달해야 한다.

길이 수정 요청

현재 이메일 본문은 약 3,000자로 생성된다.
모바일에서 빠르게 읽을 수 있도록 500자 이내로 줄이고 싶다.
각 기사 요약을 1~2문장으로 제한하고 판정 이유는 유지해 줘.
원문 URL은 제목에 연결하고 별도 링크 줄은 제거해 줘.
하단 통계는 유지해 줘.

분류 기준 수정 요청

테스트 데이터 10건 중 8건이 '높음'으로 분류됐다.
장기적인 기술 전망이나 일반 제품 소개는 '낮음'으로 분류해 줘.
3개월 안에 가격, 제품 로드맵, 규제 대응 또는 제휴 결정을 바꿔야 하는
구체적인 근거가 있을 때만 '높음'으로 분류해 줘.

첨부한 사례에서 A와 B는 높음, C는 낮음이 정답이다.
분류 규칙을 수정하고 이 사례들을 회귀 테스트로 추가해 줘.

성능 수정 요청

동일한 샘플 입력의 평균 실행 시간이 현재 약 45초다.
목표는 같은 환경에서 30초 이내다.
먼저 단계별 시간을 측정해 병목을 보여 줘.
결과의 정확도와 오류 처리를 제거하지 말고,
개선 대안의 효과와 위험을 비교한 뒤 가장 작은 변경부터 적용해 줘.

성능 수치는 측정 환경과 입력 데이터가 같을 때만 비교할 수 있다. 한 번의 실행 결과만으로 개선됐다고 판단하지 말고 측정 방법, 표본, 캐시 상태를 함께 고정해야 한다.

원칙 6. 작업 유형별 프롬프트 템플릿을 사용한다

새 에이전트 생성 템플릿

[역할과 상황]
나는 {직업/역할}이며 {문제 상황}을 해결하려고 한다.
이 결과는 {사용자 또는 후속 시스템}이 사용한다.

[목표]
{달성해야 할 결과와 성공 기준}

[실행 트리거]
{수동 실행, 이벤트, 예약 시각 등}

[입력]
- 데이터 출처: {파일/API/데이터베이스}
- 필수 필드: {필드 목록}
- 인증 방식: {환경 변수 또는 비밀 관리 방식}

[처리 로직]
1. {단계 1}
2. {단계 2}
3. {단계 3}

[출력 계약]
{파일 형식, 스키마, 템플릿, 정렬과 누락 규칙}

[예외 처리]
{빈 결과, 시간 초과, 인증 오류, 부분 실패 정책}

[제약과 비목표]
- 유지해야 할 기술: {항목}
- 금지 사항: {항목}
- 이번 작업에서 제외할 기능: {항목}

[검증]
- 통과해야 할 테스트: {항목}
- 완료 보고에 포함할 내용: 변경 파일, 실행 명령, 테스트 결과, 남은 위험

먼저 저장소를 조사하고 구현 계획을 제시해 줘.
모르는 정보는 추측하지 말고 질문해 줘.

기존 기능 추가 템플릿

기존 {에이전트 또는 모듈 이름}에 {새 기능}을 추가해 줘.
새 기능은 {기존 단계 A} 다음, {기존 단계 B} 전에 실행돼야 한다.

세부 로직:
- {조건과 처리 규칙}
- {입출력 형식}
- {실패 시 동작}

유지 조건:
- 기존 공개 인터페이스와 설정 형식을 바꾸지 않는다.
- 기존 테스트를 모두 유지한다.
- 관련 없는 파일은 수정하지 않는다.

먼저 영향 범위와 회귀 위험을 설명하고,
기존 동작을 보존하는 테스트를 추가한 뒤 구현해 줘.

오류 수정 템플릿

다음 오류를 재현하고 근본 원인을 수정해 줘.

오류 메시지 전체:
{비밀 정보와 개인정보를 제거한 오류 메시지 및 스택 추적}

발생 조건:
- 실행 명령: {명령}
- 입력: {최소 재현 입력}
- 환경: {운영체제, 런타임, 관련 버전}
- 발생 시점: {어떤 단계인지}

기대 동작:
{정상이라면 나타나야 할 결과}

실제 동작:
{현재 관찰되는 결과}

요청:
1. 먼저 오류를 재현한다.
2. 증거를 바탕으로 원인을 설명한다.
3. 가장 작은 범위로 수정한다.
4. 같은 오류를 막는 회귀 테스트를 추가한다.
5. 실행한 테스트와 남은 위험을 보고한다.

오류 메시지를 붙여 넣을 때는 API 키, 세션 토큰, 고객 데이터, 내부 주소와 같은 민감 정보를 제거해야 한다.

완성 예시: 뉴스 브리핑 에이전트 요청

다음 예시는 여섯 원칙을 하나의 요청에 결합한 형태다.

나는 SaaS 스타트업의 사업 개발 담당자다.
AI, 클라우드, 핀테크 시장 변화 중 3개월 안에 제품이나 제휴 결정을
바꿀 수 있는 뉴스만 매일 확인하고 싶다.

현재 저장소를 조사해 뉴스 브리핑 도구를 설계해 줘.
첫 단계에서는 샘플 JSON을 읽어 중복을 제거하고 영향도를 분류한 뒤
HTML 미리보기 파일을 만드는 기능까지만 구현한다.
웹 검색, 실제 메일 발송, 예약 실행은 이번 단계에서 제외한다.

입력 필드:
- title, url, source, published_at, body

처리 규칙:
- 정규화한 URL이 같으면 중복으로 본다.
- URL이 다르더라도 제목이 유사한 경우 중복 후보로 표시한다.
- 3개월 안에 가격, 규제 대응, 제품 로드맵 또는 제휴 판단에
  구체적인 변화가 필요한 기사만 영향도 '높음'으로 분류한다.
- 근거가 부족하면 높은 등급을 추측하지 않는다.

출력:
- 제목, 1~2문장 요약, 영향도, 판정 이유, 출처, URL을 표시한다.
- 영향도 높은 순서로 정렬한다.
- 전체 건수, 중복 제거 건수, 등급별 건수를 하단에 표시한다.

예외 처리:
- 필수 필드가 없는 항목은 제외하지 말고 별도 오류 목록에 기록한다.
- 잘못된 날짜는 추정하지 않고 null로 유지한다.
- 로그에 기사 본문 전체나 인증 정보를 남기지 않는다.

검증:
- 정상 입력, 빈 입력, 중복 URL, 잘못된 날짜, 필수 필드 누락을 테스트한다.
- 기존 테스트가 있다면 모두 통과해야 한다.

작업 순서:
1. 저장소 구조와 관련 파일을 조사한다.
2. 수정할 파일과 테스트 계획을 제시한다.
3. 내가 계획을 확인하기 전에는 코드를 변경하지 않는다.
4. 승인 후 최소 기능을 구현하고 테스트 결과를 보고한다.

이 요청은 필요한 기능을 모두 한 번에 운영 환경에 배포하라고 요구하지 않는다. 범위가 제한되어 있고, 출력 의미와 실패 처리, 테스트 항목이 함께 정의되어 있어 결과를 판정하기 쉽다.

프롬프트만으로 놓치기 쉬운 완성도 기준

많은 바이브 코딩 안내는 더 자세한 지시를 작성하는 데 집중한다. 하지만 실제 완성도를 좌우하는 추가 요소는 검증 가능성, 변경 통제, 관찰 가능성, 보안 경계다.

1. 인수 조건을 테스트로 바꾼다

잘 작동하게 해 줘 대신 입력과 기대 출력을 짝으로 제공한다. 중요한 분류 사례는 회귀 테스트로 남겨 다음 변경에서도 결과가 유지되는지 확인한다.

2. 에이전트의 자기평가를 최종 증거로 사용하지 않는다

에이전트가 완료했다고 말하는 것과 테스트가 통과한 것은 다르다. 실행한 명령, 테스트 결과, 변경 파일, 미해결 위험을 보고하게 하고 사람이 diff를 검토해야 한다.

3. 권한과 비밀 정보를 최소화한다

필요하지 않은 디렉터리, 운영 데이터베이스, 배포 자격 증명까지 한꺼번에 제공하지 않는다. API 키는 프롬프트나 저장소에 직접 넣지 말고 환경 변수나 승인된 비밀 관리 시스템을 사용한다. 출처를 알 수 없는 MCP 서버나 스크립트에는 민감한 저장소 접근 권한을 주지 않는다.

4. 관찰 가능한 코드를 요구한다

자동화 작업에는 단계별 상태, 구조화된 오류, 실행 시간, 처리 건수처럼 장애 원인을 찾는 데 필요한 정보를 남긴다. 반면 인증 정보와 개인정보는 로그에서 제거한다.

5. 변경을 되돌릴 수 있게 만든다

관련 없는 리팩터링과 기능 추가를 한 변경에 섞지 않는다. 작은 단위로 diff를 검토하고 버전 관리에 기록하면 잘못된 변경을 분리해 되돌리기 쉽다.

Claude Code 프로젝트 운영 팁

• 반복되는 프로젝트 규칙은 CLAUDE.md에 짧고 구체적으로 기록한다.
• 빌드, 테스트, 린트 명령은 실제로 실행 가능한 형태로 제공한다.
• 비밀 정보, 일회성 오류 로그, 긴 참고 문서를 CLAUDE.md에 넣지 않는다.
• 대규모 변경 전에는 관련 파일과 의존 관계를 먼저 조사하게 한다.
• 새 패키지를 추가할 때는 필요성, 라이선스, 유지보수 위험을 검토한다.
• 위험한 삭제, 배포, 데이터 변경 명령은 자동 승인하지 않는다.
• 외부 API나 MCP를 연결하기 전 데이터가 어디로 전송되는지 확인한다.
• 완료 시 변경 파일, 실행 명령, 테스트 결과와 남은 제한을 요약하게 한다.

제출 전 체크리스트

• 사용자와 사용 상황이 설명되어 있는가
• 목표와 비목표가 분리되어 있는가
• 기존 기술과 변경 금지 범위가 명시되어 있는가
• 입력 데이터와 출력 형식이 정의되어 있는가
• 분류 값과 상태 값의 의미가 설명되어 있는가
• 빈 결과, 인증 실패, 시간 초과, 부분 실패 정책이 있는가
• 계획과 구현이 단계별로 분리되어 있는가
• 정상·경계·실패 사례의 테스트가 있는가
• 비밀 정보와 개인정보가 프롬프트 및 로그에서 제외되는가
• 사람이 검토할 diff와 실행 증거를 요청했는가

좋은 Claude Code 프롬프트의 핵심은 명령을 길게 쓰는 것이 아니다. 에이전트가 추측해야 하는 부분을 줄이고, 결과가 맞는지 제3자도 재현해 판정할 수 있도록 만드는 것이다.