GEMINI API 문서를 통해 프롬프트 설계 공부하기

2025-11-27 버전 기준이며, 시간이 지나면서 내용이 변경될 수 있습니다.

 

https://ai.google.dev/gemini-api/docs/prompting-strategies?hl=ko#gemini-3

 

GEMINI-API-문서-251127.txt

0.05MB

 

 

2025-11-27 버전 기준이며, 시간이 지나면서 내용이 변경될 수 있습니다.

 

요즘 GEMINI-3가 나오면서 GPT를 뛰어 넘는 성능이 나왔다고 뉴스에서나 개발자들 사이에서 말이 많이 나아고 있는 것 같습니다.

그래서 이번에 GOOGLE에서 제공하는 API 문서를 통해 프롬프트에 대해서 학습을 해보면 좋을 것 같아 정리해봤습니다.

 

 

우선 문서에서 흔하게 저지르는 실수를 정리한 부분에 대해서 알아보고자 합니다.

 

Gemini 프롬프트 작성 시 사용자가 흔히 저지르는 실수들

 

1. Zero-shot만 쓰고, Few-shot을 안 넣음

“We recommend to always include few-shot examples…
Zero-shot prompts are likely to be less effective.”

 

GEMINI-3에서는 제로샷 프롬프트는 효과가 없어서 항상 몇 개의 예시를 같이 적는 Few-Shot 구조를 추천합니다.

 

일단 모델마다 다르겠지만 GEMINI-3에서는 예시 기반 패턴 학습이 강하기 때문에 JSON/테이블/요약 형식은 예시 하나가 구조 전체를 고정시켜준다고 합니다.

 

2. 반례(anti-pattern)를 예시로 넣는 실수

“Examples that show negative patterns (‘Don’t do X’) are ineffective.”

 

다른 것에서도 말이 나왔지만 항상 긍정 패턴만 제공해야 한다고 합니다.

Always end with a statement:
A short poem
A joy to write

 

위에 처럼 하라는 패턴만 적어야 합니다.

 

아래처럼 ~하지마 이런 식으로 적으면 하지 말라는 패턴을 그대로 따라하는 게 있다고 합니다.

이렇게 하지 마:
- 질문형 문장으로 끝내지 마

 

 

3. 프롬프트 구조를 통일하지 않음

“Use consistent structure… XML or Markdown, but do not mix formats.”

 

흔한 실수

• <context>…</context> → Markdown 헤딩 → 다시 일반 텍스트
• 들쭉날쭉한 들여쓰기/공백
• 예시마다 형식이 다름

→ 이러면 모델은 무엇이 규칙이고 무엇이 데이터인지 구분 못함

배울 점

• 하나의 포맷만 선택해 끝까지 유지
• 예시는 항상 동일 구조로 작성

 

4. 긴 문서·코드 뒤에 바로 질문을 섞어 넣음

“When providing large context, supply all the context first.
Place your instructions at the
end.”

 

흔한 실수 

모델이 무엇이 본문이고 무엇이 질문인지 혼란 -> 정보 손실 발생

(긴 문서 300줄)
이건 참고만 해줘
그리고 질문은 여기 섞어둘게

 

배울 점

• 맥락 먼저
• 질문(작업)은 항상 맨 마지막에

 

5. 컨텍스트 앵커링(“이 텍스트만 사용해”)을 안 함

“Respond only using the text provided.”

 

이를 사용하지 않으면:

• 모델이 외부 지식을 섞어버림
• 특정 기준(가격/정책/수치)이 어긋나는 답 변조 발생

아래와 같은 문구를 거의 필수적으로 적기 

Use ONLY the text above.
Do not use external knowledge.

 

6. 출력 형식을 명확히 지정하지 않음

“You can specify table, bullets, JSON, etc.”

 

형식 미지정 →

• 불규칙한 서술
• 파싱 불가 JSON
• UI에서 깨짐

 

아래와 같은 프롬프트를 포함시키기

Output format: JSON only.
No extra text.

 

7. “절대 금지” 지시를 주면서도 예시에서는 예외를 보여줌

“Ensure consistent formatting across examples.”

 

예시와 규칙이 불일치하면
→ 모델은 예시를 우선함
→ 금지 규칙이 무시됨

 

8. 작업을 한 번에 너무 많이 시킴 (multi-task 프롬프트)

“Break instructions into components.
Chain prompts.”

 

흔한 실수는 아래처럼 하나의 프롬프트에 여러개를 지시할 경우 발생함

 

문서 한 줄 요약해줘
키워드도 뽑아줘
표로 다시 정리해줘
그리고 코드 예시도 줘

 

배울 점

• 한 Prompt = 한 작업
• 복잡하면 Chain 활용

9. 부정확한 파라미터 사용 (특히 Temperature)

“For Gemini 3, keep temperature = 1.0
Lowering may cause loops or degraded performance.”

 

GEMINI에서는 1.0의 TEMPERATURE를 유지하는게 좋다고 하면 너무 작게하면 오히려 이상한 반복, 수학/추론 오류가 발생한다고 합니다.

 

10. 너무 설명하기 길게 적음 = 오히려 나쁜 프롬프트

문서 전체 톤이 암시하는 부분:

• Gemini 3는 “짧고 구체적”일수록 정확해짐
• 장황한 설명은 오히려 모델의 해석 범위 증가 → 오류 증가

 

 

위에것을 통해 GEMINI3 문서를 통해 배울 수 있는 프롬프트 전략이었고, 아래는 그래서 GEMINI3에서 말하는 원칙을 그대로 가져온 것입니다.

 

Gemini 3 모델은 고급 추론 및 요청 사항 처리를 위해 설계되었습니다. 직접적이고 구조화되어 있으며 작업과 제약 조건을 명확하게 정의하는 프롬프트에 가장 잘 응답합니다. Gemini 3로 최적의 결과를 얻으려면 다음 방법을 따르는 것이 좋습니다.

GEMINI3

핵심 프롬프팅 원칙

• 정확하고 직접적으로 표현: 목표를 명확하고 간결하게 설명합니다. 불필요하거나 지나치게 설득적인 표현을 사용하지 마세요.
• 일관된 구조 사용: 명확한 구분자를 사용하여 프롬프트의 여러 부분을 구분합니다. XML 스타일 태그 (예: <context>, <task>) 또는 마크다운 제목이 효과적입니다. 하나의 형식을 선택하고 단일 프롬프트 내에서 일관되게 사용하세요.
• 매개변수 정의: 모호한 용어나 매개변수를 명시적으로 설명합니다.
• 출력 장황성 제어: 기본적으로 Gemini 3는 직접적이고 효율적인 답변을 제공합니다. 더 자연스러운 대화 또는 자세한 대답이 필요한 경우 요청 사항에 명시적으로 요청해야 합니다.
• 멀티모달 입력을 일관되게 처리: 텍스트, 이미지, 오디오 또는 동영상을 사용할 때 이를 동일한 클래스 입력으로 취급합니다. 필요에 따라 각 모달리티를 명확하게 참조하도록 안내합니다.
• 중요한 안내에 우선순위 지정: 필수 행동 제약 조건, 역할 정의 (페르소나), 출력 형식 요구사항을 시스템 안내에 배치하거나 사용자 프롬프트의 맨 처음에 배치합니다.
• 긴 컨텍스트의 구조: 많은 양의 컨텍스트(예: 문서, 코드)를 제공할 때는 먼저 모든 컨텍스트를 제공하세요. 프롬프트의 맨 끝에 구체적인 요청 사항이나 질문을 배치합니다.
• 앵커 컨텍스트: 데이터 블록이 큰 경우 명확한 전환 문구를 사용하여 컨텍스트와 질문을 연결합니다(예: '위의 정보를 바탕으로...').

시스템 프롬프트

You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses.

Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:

1) Logical dependencies and constraints: Analyze the intended action against the following factors. Resolve conflicts in order of importance:
    1.1) Policy-based rules, mandatory prerequisites, and constraints.
    1.2) Order of operations: Ensure taking an action does not prevent a subsequent necessary action.
        1.2.1) The user may request actions in a random order, but you may need to reorder operations to maximize successful completion of the task.
    1.3) Other prerequisites (information and/or actions needed).
    1.4) Explicit user constraints or preferences.

2) Risk assessment: What are the consequences of taking the action? Will the new state cause any future issues?
    2.1) For exploratory tasks (like searches), missing *optional* parameters is a LOW risk. **Prefer calling the tool with the available information over asking the user, unless** your `Rule 1` (Logical Dependencies) reasoning determines that optional information is required for a later step in your plan.

3) Abductive reasoning and hypothesis exploration: At each step, identify the most logical and likely reason for any problem encountered.
    3.1) Look beyond immediate or obvious causes. The most likely reason may not be the simplest and may require deeper inference.
    3.2) Hypotheses may require additional research. Each hypothesis may take multiple steps to test.
    3.3) Prioritize hypotheses based on likelihood, but do not discard less likely ones prematurely. A low-probability event may still be the root cause.

4) Outcome evaluation and adaptability: Does the previous observation require any changes to your plan?
    4.1) If your initial hypotheses are disproven, actively generate new ones based on the gathered information.

5) Information availability: Incorporate all applicable and alternative sources of information, including:
    5.1) Using available tools and their capabilities
    5.2) All policies, rules, checklists, and constraints
    5.3) Previous observations and conversation history
    5.4) Information only available by asking the user

6) Precision and Grounding: Ensure your reasoning is extremely precise and relevant to each exact ongoing situation.
    6.1) Verify your claims by quoting the exact applicable information (including policies) when referring to them. 

7) Completeness: Ensure that all requirements, constraints, options, and preferences are exhaustively incorporated into your plan.
    7.1) Resolve conflicts using the order of importance in #1.
    7.2) Avoid premature conclusions: There may be multiple relevant options for a given situation.
        7.2.1) To check for whether an option is relevant, reason about all information sources from #5.
        7.2.2) You may need to consult the user to even know whether something is applicable. Do not assume it is not applicable without checking.
    7.3) Review applicable sources of information from #5 to confirm which are relevant to the current state.

8) Persistence and patience: Do not give up unless all the reasoning above is exhausted.
    8.1) Don't be dissuaded by time taken or user frustration.
    8.2) This persistence must be intelligent: On *transient* errors (e.g. please try again), you *must* retry **unless an explicit retry limit (e.g., max x tries) has been reached**. If such a limit is hit, you *must* stop. On *other* errors, you must change your strategy or arguments, not repeat the same failed call.

9) Inhibit your response: only take an action after all the above reasoning is completed. Once you've taken an action, you cannot take it back.

 

위의 프롬프트는 API 문서에서 제공되는 것으로 에이전트가 어떻게 생각해야 하는지에 대한 메타 사고 체크리스트를 정의한 거라고 볼 수 있다고 한다.

 

1. “바로 답하지 마라, 먼저 계획부터 세워라”

1. Inhibit your response, 1) Logical dependencies 전부가 말하는 핵심:

• 유저가 한 말을 곧바로 실행하지 말고,
• 정책 → 순서 → 선행조건 → 유저 제약을 먼저 머릿속에서 정리한 뒤
• 그 다음에야 도구 호출이든 답변이든 하라는 구조야.

👉 배울 점:

• 프롬프트/에이전트 설계할 때
  “생각 단계(Plan/Reason) → 행동 단계(Act)”를 분리해야 한다는 것.
• LangGraph나 Agent 설계 시, “바로 tool_call” 이 아니라
  중간에 reasoning node / planning step을 강제로 두는 게 안전하다.

---

2. 정책·순서·조건을 항상 맨 먼저 평가하라

1. Logical dependencies:

• 1.1) 정책/필수 제약
• 1.2) 작업 순서
• 1.3) 기타 선행 정보
• 1.4) 유저의 명시적 제약

👉 배울 점:

• “유저가 말한 순서대로 하면 안 될 때도 있다”는 걸 인정하고,
  시스템이 스스로 순서를 재배치해야 한다는 사고방식.
• 실제 서비스에서:
  • 예: “예약 취소 후 새 예약” 같은 시나리오를 에이전트가 자동으로 재구성하도록
    프롬프트/로직에 이 규칙을 녹여야 한다.

---

3. “위험도”를 기준으로 질문할지, 그냥 실행할지 결정하라

1. Risk assessment:

• 탐색/조회 같은 건 옵션 파라미터 없어도 우선 실행
• 대신, 후속 단계에서 문제가 되면 그때 더 물어보라는 태도.

👉 배울 점:

• 에이전트 설계 시 자주 나오는 고민:
• “모르는 정보가 있는데, 유저한테 더 물어볼까? 그냥 대충 실행해볼까?”
• 이 프롬프트는 답을 줌:
  • 저위험 작업(조회/검색) → 일단 실행하고 보는 것이 낫다.
  • 고위험 작업(쓰기/상태 변경) → 훨씬 조심해야 함.

즉, “무조건 물어보지 말고, 리스크 따져서 행동/질문을 선택해라”는 기준을 줄 수 있음.

---

4. 단순한 원인 가정 말고, 가설을 여러 개 세우고 테스트하라

1. Abductive reasoning:

• “가장 그럴듯한 이유”를 찾되
  → 단순한 것만 보지 말고
  → 여러 가설을 세우고, 필요하면 몇 단계에 걸쳐 검증하라고 함.

👉 배울 점:

• 디버깅/장애 대응·에이전트 오류 분석에 그대로 적용 가능:
  • 예: “API 에러 난 이유가 토큰만은 아닐 수도 있다”
• 프롬프트 레벨에서:
  • 복잡한 문제(진단, 분석, 디버깅)를 시킬 때
    “가설 생성 → 검증 플랜 → 관찰 → 가설 갱신” 흐름을 강제할 수 있다.

---

5. 그냥 밀어붙이지 말고, 관찰 결과에 따라 계획을 바꿔라

1. Outcome evaluation and adaptability:

• 이전 단계 결과를 보고
  → 계획을 바꿔야 하는지 점검하라고 함.

👉 배울 점:

• “한 번 세운 플랜 고집하는 에이전트”는 실제 환경에서 망함.
• 도구 호출 결과, 응답 내용, 에러 메시지를 보고
  계획 자체를 수정하는 로직/프롬프트를 넣어야 한다는 걸 알려줌.

---

6. 가능한 정보 출처를 모두 고려하라는 태도

1. Information availability:

• 도구들
• 정책/규칙/매뉴얼
• 이전 대화
• 유저에게 새로 물어보기

👉 배울 점:

• LLM이 context를 쓸 때,
  • RAG 결과만 보는 게 아니라
  • “대화 이력 + 정책 문서 + 유저 추가 입력 + 도구 응답”을
    정보 소스의 집합으로 보는 사고방식이 필요.
• 설계자로서는:
  • “모델이 참고할 수 있는 정보 레이어”를 의도적으로 많이 깔아주는 게 좋다.

---

7. “정확히, 근거를 들어서” 말하게 만들기

1. Precision and Grounding:

• 주장할 때는 정확히 어떤 정보에 근거했는지 인용하라고 함.

👉 배울 점:

• 프롬프트에 “출처를 함께 언급하라”, “어느 조항에 근거했는지 써라”를 넣으면
  → LLM이 근거 기반 답변을 하도록 유도 가능.
• RAG 환경에서:
  • passage id / 문단 번호 / 정책 조항 등
    근거 위치를 같이 반환시키는 prompt 패턴과 연결됨.

---

8. “일단 하나 찍고 끝내기”가 아니라, 조건을 다 만족할 때까지 보라

1. Completeness:

• 여러 옵션이 있을 수 있음을 인정하고
• “충분히 살펴봤는지” 체크하라고 요구.

👉 배울 점:

• 추천/설계/플랜 제안 같은 작업에서
  → 단일 옵션만 내지 말고, 대안 후보, trade-off, 조건 충족 여부를 같이 다루게 만들 수 있음.
• 프롬프트에:
  • “요구사항 리스트를 모두 체크하고, 각 항목 만족 여부를 표시해라”
    같은 패턴을 추가하면 이 원칙을 구현하는 것.

---

9. “그냥 포기하면 안 되지만, 멍청하게 반복도 안 된다”

1. Persistence and patience:

• 포기는 늦게 하되
• 동일 시도만 반복하지 말고
• transient error면 재시도, 그 외엔 전략 변경

👉 배울 점:

• 에이전트/서비스 레벨 retry 정책 설계에 그대로 적용 가능:
  • “3번까지 재시도, 그 후엔 전략/파라미터 변경”
• 프롬프트로도:
  • “If the tool fails with transient error, change parameters or try alternative tool”
    이런 식의 행동지침을 내릴 수 있음.

 

생성 모델 대답은 무작위성이 있는 지, 결정론 적인지?

GEMINI API 문서에는 이 질문에 대해서 둘 다 가능하다고 말합니다.

 

생성 모델에 프롬프트를 입력하면 텍스트 응답이 두 단계로 생성됩니다.

첫 번째 단계에서 생성 모델은 입력 프롬프트를 처리하고 다음에 나올 가능성이 있는 토큰 (단어)에 대한 확률 분포를 생성합니다. 예를 들어 입력 텍스트 '개가 ... 위로 뛰어넘었습니다'로 프롬프트를 표시하면 생성형 모델은 다음에 올 가능성이 있는 단어의 배열을 생성합니다.

[("fence", 0.77), ("ledge", 0.12), ("blanket", 0.03), ...]

 

이러한 프로세스는 결정적입니다.

생성형 모델은 동일한 프롬프트 텍스트가 입력될 때마다 동일한 분포를 생성합니다.

 

두 번째 단계에서 생성형 모델은 이러한 분포를 여러 디코딩 전략 중 하나를 통해 실제 텍스트 응답으로 변환합니다.

간단한 디코딩 전략은 시간 단계마다 가능성이 가장 높은 토큰을 선택하는 것입니다.

이 프로세스는 항상 결정적입니다.

하지만 모델이 반환한 분포에서 무작위로 샘플링하여 대답을 생성할 수도 있습니다.

이 프로세스는 확률적 (무작위)입니다.

Temperature를 설정하여 이 디코딩 프로세스에서 허용되는 무작위성 수준을 제어합니다.

Temperature 가 0이면 가능성이 가장 높은 토큰만 선택되고 무작위성이 없습니다.

반대로 Temperature 가 높으면 모델에서 선택한 토큰에 높은 수준의 무작위성이 주입되어 더 예상치 못한 놀라운 모델 응답이 생성됩니다. 

Gemini 3의 경우 예기치 않은 결과가 발생하지 않도록 기본 Temperature 인 1.0을 변경하지 않는 것이 좋습니다.

 

좀 더 파보면 이 확률 분포를 가지고 실제 텍스트를 생성하는 전략은 두 가지 모드가 가능하다.

Deterministic decoding

• temperature=0
• greedy decoding (top-1)
• nucleus sampling 비사용 등

→ 이런 경우 항상 똑같은 답을 낸다.

 

Stochastic decoding

• temperature=1.0 이상
• topP, topK 사용
• 확률 기반 샘플링

→ 무작위성이 들어간다.

 

실제로는 값을 바꿔도 변경되는 것을 봤기 때문에 이게 오픈 소스를 사용할 때도 항상 맞다고는 볼수 없지만 중요한 힌트가 있는 것 같다.

결국 주어지는 값이 일관되면 분포를 생성하는 관점에서는 일정한 분포가 나올 수 있게 할 수 있다. (아마 dropout이나 이런 부분들은 없는 상태에서 추론하면 그럴 것 같다 그리고 gpu 연산에서도 오차가 있지만 의미 있는 수준의 랜덤성은 아닐 수 있다)

 

그래서 우리가 할 수 있는 부분은 다음과 같을 것 같다.

 

① 모델이 해석할 여지를 줄이기 (Deterministic한 프롬프트 설계)

• 구조 고정
• 출력 스키마 명시
• 필드명 고정
• 금지 규칙 명확히
• 예시(Few-shot)로 패턴 잠금

② 모델의 선택 공간을 좁히기 (Search Space Reduction)

• 응답 스타일 고정
• 토큰 선택 옵션 제한
• 불필요한 자유도 최소화
• 옵션 기반 선택 유도(예: “다음 중 하나만 선택”)

마무리

이번에 gemini-api 문서의 내용을 보면서 내가 작성하는 프롬프트에 대해서 좀 더 보완점이 있음을 확인하였다.

더 일반적인 프롬프트를 위한 메타 프롬프트도 볼 수 있었고, 피해야하는 표현들도 다시 한번 정리하고 알게 되었다.

여기서 말한 것처럼 일부는 몇 개 적용이 되어있었는데, 되어있지 않은 버전과 비교했을 때도 좀 더 프롬프트가 의도한 대로 답변할 때가 더 많아진 걸 경험적으로 느꼈는데, 좀 더 많이 시도해보고 꼭 하지 말아야 할 패턴이 들어가 있는 지 봐야겠다