# Gemini 프롬프트 설계 원칙

**작성일**: 2025-12-25
**참고**: [Google AI Gemini API 프롬프트 설계 전략](https://ai.google.dev/docs/prompt_design_strategy)
**관련 문서**: [[311_FastAPI_구조_원칙]], [[312_문서_작성_원칙]], [[plans/251225_프롬프트_동적관리_계획]]

---

## 1. 명확하고 구체적인 요청

### 핵심 원칙
- 질문/작업/항목 입력을 명확히 구분
- 제약조건(길이, 형식) 명시
- 출력 형식 구체적으로 지정

### 예시
```
❌ 나쁜 예: "요약해줘"
✅ 좋은 예: "다음 텍스트를 한 문장으로 요약해주세요: [텍스트]"

❌ 나쁜 예: "분류해줘"
✅ 좋은 예: "다음 항목을 [large, small] 중 하나로 분류해주세요. JSON 형식으로 응답하세요."
```

---

## 2. 퓨샷 예시 활용 (Few-shot Prompting)

### 핵심 원칙
- 제로샷보다 퓨샷이 효과적
- **긍정적 패턴(해야 할 것)을 보여주는 것이 부정적 패턴(하지 말 것)보다 효과적**
- 예시 형식 일관성 유지 (XML 태그, 공백, 줄바꿈 통일)

### 예시
```
✅ 좋은 예 (긍정적 패턴):
Always end haikus with an assertion:
Haiku are fun
A short and simple poem
A joy to write

❌ 나쁜 예 (부정적 패턴):
Don't end haikus with a question:
Haiku are fun
A short and simple poem
Don't you enjoy them?
```

### 최적 예시 수
- 몇 가지 예시로 패턴 학습 가능
- 너무 많은 예시는 과적합 위험
- 사용 사례별로 실험 필요

---

## 3. 컨텍스트 추가 및 구조화

### 핵심 원칙
- 모델이 필요한 모든 정보를 프롬프트에 포함
- 복잡한 프롬프트는 구성요소로 분할 (요청 분리, 프롬프트 연결, 응답 집계)
- XML 태그나 마크다운으로 구조화

### 구조화 예시 (XML)
```xml
<role>
You are a helpful assistant.
</role>

<constraints>
1. Be objective.
2. Cite sources.
</constraints>

<context>
[Insert User Input Here]
</context>

<task>
[Insert the specific user request here]
</task>
```

### 구조화 예시 (마크다운)
```markdown
# Identity
You are a senior solution architect.

# Constraints
- No external libraries allowed.
- Python 3.11+ syntax only.

# Output format
Return a single code block.
```

---

## 4. Gemini 3 특화 전략

### 핵심 원칙
- 구조화된 프롬프트 (XML/마크다운)
- 명확한 매개변수 정의
- 중요한 안내를 앞쪽에 배치
- 긴 컨텍스트는 먼저 제공 후 끝에 질문 배치

### 시스템 안내 템플릿
```xml
<role>
You are Gemini 3, a specialized assistant for [Domain].
You are precise, analytical, and persistent.
</role>

<instructions>
1. **Plan**: Analyze the task and create a step-by-step plan.
2. **Execute**: Carry out the plan.
3. **Validate**: Review your output against the user's task.
4. **Format**: Present the final answer in the requested structure.
</instructions>

<constraints>
- Verbosity: [Low/Medium/High]
- Tone: [Formal/Casual/Technical]
</constraints>

<output_format>
Structure your response as follows:
1. **Executive Summary**: [Short overview]
2. **Detailed Response**: [The main content]
</output_format>
```

### 추론 및 계획 명시
- 복잡한 작업은 "Before providing the final answer, please: 1) Parse into sub-tasks, 2) Check completeness, 3) Create outline" 같은 명시적 계획 요청
- 자체 비판: "Before returning your final response, review your output against constraints"

---

## 5. 프리픽스 활용

### 용도
- **입력 프리픽스**: 의미론적으로 의미 있는 부분에 추가 ('영어:', '프랑스어:')
- **출력 프리픽스**: 예상 응답 형식 안내 ('JSON:', 'The answer is:')
- **퓨샷 프리픽스**: 예시에 라벨 제공하여 출력 파싱 용이

### 예시
```
Classify the text as one of the following categories: [large, small]
Text: Rhino
The answer is: large
Text: Mouse
The answer is: small
Text: Elephant
The answer is:
```

---

## 6. 모델 파라미터 실험

### 주요 파라미터
- **최대 출력 토큰**: 100 토큰 ≈ 60-80 단어
- **온도 (Temperature)**: 0(확정적) ~ 높음(창의적). **Gemini 3는 기본값 1.0 유지 권장** (1.0 미만 설정 시 루핑/성능 저하 가능)
- **topK**: 가장 확률 높은 K개 토큰에서 선택
- **topP**: 확률 합이 topP가 될 때까지 선택 (기본 0.95)
- **stop_sequences**: 콘텐츠 생성 중지 시퀀스

---

## 7. 프롬프트 반복 전략

### 시도할 방법
1. **다른 표현 사용**: "How do I bake a pie?" → "Suggest a recipe for a pie" → "What's a good pie recipe?"
2. **유사 작업으로 전환**: 객관식 질문으로 변환, 분류 작업으로 변경 등
3. **프롬프트 콘텐츠 순서 변경**: [examples][context][input] → [input][examples][context] 등

### 대체 응답 발생 시
- 온도(temperature)를 높여보기
- 프롬프트 재구성

---

## 8. 피해야 할 사항

- ⛔ 사실에 기반한 정보 생성을 모델에 의존하지 않기
- ⛔ 수학 및 논리 문제에 주의해서 사용
- ⛔ 모호한 용어나 매개변수 사용 금지

---

## 9. 에이전트형 워크플로

### 고려할 측면
- **추론 및 전략**: 논리적 분해, 문제 진단, 정보 완전성
- **실행 및 안정성**: 적응성, 지속성 및 복구, 위험 평가
- **상호작용 및 출력**: 모호성 및 권한 처리, 장황성, 정밀도 및 완전성

### 시스템 안내 템플릿 (에이전트용)
복잡한 에이전트 작업을 위한 상세한 추론 및 계획 프레임워크가 필요할 경우, Google AI 문서의 "에이전트형 워크플로" 섹션 참조.

---

## 10. 로빙 프로젝트 적용

### 관련 문서
- **프롬프트 동적 관리**: [[plans/251225_프롬프트_동적관리_계획]] - 프롬프트 DB화를 통한 동적 변경 및 개인화
- **LLM 통합**: [[230_감정윤리_필터_LLM후처리와_정체성]] - LLM 후처리와 정체성 관리
- **FastAPI 구조**: [[311_FastAPI_구조_원칙]] - 계층 분리 원칙

### 로빙 프로젝트에서의 활용
- 시스템 프롬프트 설계 시 명확성과 구조화 원칙 적용
- 감정 기반 동적 프롬프트 조합 시 퓨샷 예시 활용
- 사용자별 개인화 프롬프트 오버라이드 시 컨텍스트 구조화

---

## 참고 자료

- [Google AI Gemini API 프롬프트 설계 전략](https://ai.google.dev/docs/prompt_design_strategy)
- [프롬프트 갤러리](https://ai.google.dev/gemini-api/docs/prompt-gallery) - 대화형 샘플 프롬프트
- [[plans/251225_프롬프트_동적관리_계획]] - 로빙 프롬프트 동적 관리 시스템 계획