효율적인 Claude 프롬프트 엔지니어링

AI 도구의 출력 품질은 프롬프트 품질에 비례한다. 막연한 지시와 정교한 프롬프트의 차이는 여러 번의 수정과 한 번에 원하는 결과를 얻는 것의 차이다.

1. Claude의 특성 이해

최신 Claude 모델은 문자 그대로 지시를 따른다. 의도를 유추해서 확장하기보다 요청한 것만 정확히 수행한다.

모호한 요청 vs 명확한 요청

구분모호한 요청명확한 요청

해석 방식	최소한만 수행	명시된 것 모두 수행
추가 작업	자동으로 안 해줌	요청한 대로 처리
결과 품질	불확실	예측 가능

위반 사례

[Bad] "로그인 기능 만들어줘"
→ 최소한의 로그인만 구현, 유효성 검사나 에러 처리 없음

개선안

[Good] "로그인 기능을 만들어줘. 다음을 포함해:
- 이메일/비밀번호 유효성 검사
- 로딩 상태 표시
- 에러 메시지 처리
- 로그인 성공 시 홈으로 리다이렉트"

핵심 포인트:

• Claude는 요청한 것만 정확히 수행한다
• “알아서 해주겠지”라는 기대는 버려야 한다
• 원하는 동작을 명시적으로 나열해야 한다

2. 4블록 프롬프트 구조

구조화된 프롬프트는 AI가 컨텍스트를 정확히 파악하게 한다. Anthropic이 권장하는 4블록 패턴이 있다.

기본 구조

[INSTRUCTIONS] - 전체 지시사항
[CONTEXT] - 배경 정보, 제약조건
[TASK] - 구체적인 작업 내용
[OUTPUT FORMAT] - 출력 형식

실제 적용 예시

<instructions>
당신은 Android 시니어 개발자다.
Kotlin과 Jetpack Compose를 사용한 코드를 작성한다.
</instructions>

<context>
프로젝트: 쇼핑몰 앱
아키텍처: MVI + Clean Architecture
현재 작업: 상품 목록 화면 구현
</context>

<task>
상품 목록을 표시하는 ProductListScreen을 구현해줘.
- LazyColumn 사용
- 로딩/에러/성공 상태 처리
- 아이템 클릭 시 상세 화면으로 이동
</task>

<output_format>
- ProductListScreen.kt 파일 전체 코드
- 주요 함수에 한글 주석 추가
</output_format>

XML 태그를 사용하는 이유

Claude는 XML 태그에 특별히 주의를 기울이도록 학습되어 있다. 태그로 섹션을 명확히 구분하면:

• 지시사항과 컨텍스트가 뒤섞이지 않는다
• 각 부분의 역할이 명확해진다
• 복잡한 프롬프트도 구조적으로 전달된다

---

3. 시스템 프롬프트 작성법

시스템 프롬프트는 Claude의 전체 동작을 정의하는 “계약서”다. 명확하고 경계가 분명하며 검증 가능해야 한다.

좋은 시스템 프롬프트의 특징

특징설명

명확함	모호한 표현 없이 구체적으로
경계가 분명함	해야 할 것과 하지 말아야 할 것 구분
검증 가능함	지시를 따랐는지 확인할 수 있음

위반 사례

[Bad] "좋은 코드를 작성해줘"
→ "좋은"의 기준이 모호함

개선안

[Good] 다음 원칙을 따라 코드를 작성해:
- 함수는 20줄 이내로 유지
- 한 함수는 한 가지 일만 수행
- 변수명은 의도를 드러내도록 명명
- 에러 처리는 sealed class로 타입 안전하게

행동 제어 프롬프트

Claude의 적극성을 조절할 수 있다.

더 적극적으로 만들기:

기본적으로 제안만 하지 말고 직접 구현해라.
사용자의 의도가 불분명하면 가장 유용할 것 같은 방향으로 추론해서 진행해라.
누락된 정보는 추측하지 말고 도구를 사용해서 파악해라.

 

과잉 엔지니어링 방지:

과잉 엔지니어링을 피해라.
요청된 것만 구현하고 추가 기능을 넣지 마라.
단순하고 집중된 해결책을 유지해라.
요청하지 않은 리팩토링, 기능 추가, "개선"을 하지 마라.

 

4. Few-Shot 프롬프팅

예시를 제공하면 원하는 출력 형식을 정확히 전달할 수 있다.

기본 원칙

1. 1개 예시로 시작 (One-shot)
2. 출력이 원하는 형식이 아니면 예시 추가 (Few-shot)
3. 예시는 다양하고 대표적인 것으로 선별

위반 사례

[Bad] 모든 엣지 케이스를 예시로 나열
→ 프롬프트가 장황해지고 핵심이 흐려짐

개선안

<example>
입력: "사용자가 로그인 버튼을 클릭한다"
출력:
sealed interface LoginIntent {
    data object ClickLogin : LoginIntent
}
</example>

<example>
입력: "이메일 입력값이 변경된다"
출력:
sealed interface LoginIntent {
    data class ChangeEmail(val email: String) : LoginIntent
}
</example>

이제 "비밀번호 입력값이 변경된다"에 대한 Intent를 작성해줘.

위 예시처럼 입력-출력 쌍을 <example> 태그로 감싸면 Claude가 패턴을 정확히 파악한다.

5. 환각(Hallucination) 방지

Claude가 모르는 것을 추측하지 않도록 명시적으로 허용해야 한다.

위반 사례

[Bad] "이 라이브러리 사용법 알려줘"
→ 존재하지 않는 API를 만들어낼 수 있음

개선안

[Good] "이 라이브러리 사용법을 알려줘.
확실하지 않은 부분은 '확인 필요'라고 표시해줘.
모르는 건 추측하지 말고 모른다고 말해줘."

실무 적용

<instructions>
- 확실한 정보만 제공해라
- 불확실한 부분은 "확인 필요: [이유]"로 표시해라
- 공식 문서에서 확인되지 않은 내용은 추측이라고 명시해라
</instructions>

---

6. Claude Code 전용 팁

Claude Code를 사용할 때 효과적인 프롬프트 패턴이 있다.

CLAUDE.md 활용

프로젝트 루트에 .claude/CLAUDE.md 파일을 만들면 매번 반복할 필요 없이 컨텍스트를 유지할 수 있다.

# 프로젝트 컨텍스트

## 기술 스택
- Kotlin, Jetpack Compose
- MVI + Clean Architecture
- Hilt, Retrofit, Room

## 코딩 컨벤션
- 함수명: camelCase
- 클래스명: PascalCase
- 패키지: feature 기반 구조

## 금지 사항
- Java 코드 사용 금지
- LiveData 대신 StateFlow 사용
- 하드코딩된 문자열 금지

슬래시 명령어 커스텀

.claude/commands/ 디렉토리에 반복 작업을 명령어로 등록할 수 있다.

# /feature 명령어
새로운 feature 모듈을 생성한다.

## 작업
1. feature-[name] 디렉토리 생성
2. 기본 패키지 구조 생성 (ui, domain, data)
3. Screen, ViewModel, State, Intent 파일 생성
4. Hilt 모듈 설정

 

7. 실전 프롬프트 템플릿

코드 리뷰 요청

<task>
아래 코드를 리뷰해줘.
</task>

<review_criteria>
- 버그 가능성
- 성능 이슈
- 가독성
- 테스트 용이성
</review_criteria>

<output_format>
| 라인 | 문제 | 심각도 | 개선안 |
형식으로 정리해줘.
</output_format>

<code>
[코드]
</code>

기능 구현 요청

<context>
프로젝트: [프로젝트명]
현재 파일: [파일 경로]
관련 파일: [참고할 파일들]
</context>

<task>
[구현할 기능 설명]
</task>

<constraints>
- 기존 아키텍처 패턴 유지
- [특정 라이브러리] 사용
- 에러 처리 포함
</constraints>

<output>
- 전체 코드 제공
- 주요 로직에 주석 추가
- 테스트 코드 포함
</output>

버그 수정 요청

<problem>
[현상 설명]
</problem>

<expected>
[기대 동작]
</expected>

<actual>
[실제 동작]
</actual>

<code>
[관련 코드]
</code>

<task>
원인을 분석하고 수정해줘.
수정 전/후 코드를 모두 보여줘.
</task>

---

정리

• Claude는 지시를 문자 그대로 수행한다. 원하는 것을 명시적으로 나열해야 한다
• 4블록 구조(INSTRUCTIONS/CONTEXT/TASK/OUTPUT)로 프롬프트를 구조화한다
• XML 태그로 섹션을 구분하면 Claude가 더 정확히 이해한다
• 시스템 프롬프트는 명확하고 경계가 분명하게 작성한다
• Few-shot은 1개부터 시작해서 필요하면 추가한다
• 불확실한 정보는 추측하지 말라고 명시한다
• CLAUDE.md와 커스텀 명령어로 반복을 줄인다

참고:

• Anthropic - Prompt Engineering Best Practices
• Claude Docs - Prompting Best Practices
• Anthropic - Effective Context Engineering
• Anthropic Prompt Engineering Tutorial (GitHub)