프롬프트 설계

모델 교체보다 프롬프트 한 줄이 품질을 더 올릴 때가 많습니다. 네 가지만 제대로.

1. 시스템 프롬프트 — 캐릭터 설정

system = """당신은 내부 개발 문서에 답하는 어시스턴트입니다.

규칙:
- 주어진 문서에 없는 내용은 "문서에서 찾을 수 없습니다" 로 답하세요
- 답변은 한국어 3~5 문장, 핵심부터
- 코드 예시가 필요하면 ```python ``` 블록으로
- 출처는 [문서명] 형식으로 인용
"""

messages = [
    {"role": "system", "content": system},
    {"role": "user", "content": prompt},
]

시스템 프롬프트는 "모든 응답에 공통 적용" 되는 규칙 저장소. 유저 프롬프트를 깔끔하게 유지.

2. Few-shot — 예시로 가르치기

system = """사용자 질문을 분류하세요. 카테고리: bug · feature · question · other.
출력은 한 단어만.

예시:
Q: 로그인이 안 돼요
A: bug

Q: 다크 모드 추가 가능한가요?
A: feature

Q: 환불 정책이 뭔가요?
A: question
"""

2 ~ 5 개 예시로 포맷 · 톤을 학습. zero-shot 대비 정확도 +10 ~ 30%.

3. 출력 스키마 강제

system = """다음 JSON 스키마로만 답하세요. 다른 텍스트 금지.

{
  "category": "bug" | "feature" | "question" | "other",
  "priority": "high" | "medium" | "low",
  "summary": string (100자 이내)
}
"""

JSON 파싱 실패를 줄이기 위한 보조:

response_format={"type": "json_object"} (OpenAI · Gemini 일부)
Pydantic 으로 파싱 + 실패 시 재시도
LLM 이 프리앰블 ("답변입니다:") 를 붙이면 json.loads 첫 { 부터 마지막 } 까지 슬라이스

4. Hallucination 방지 3 구

"~로만 답하세요" — 근거 범위 명시
"모르면 모른다" — 탈출 경로 제공
"출처 인용" — 검증 가능한 답변

아래 문서를 근거로만 답하세요.
문서에 없으면 "문서에서 찾을 수 없습니다" 라고 답하세요.
각 주장 옆에 [문서 ID] 를 적으세요.

5. 예산 · 토큰 관리

def estimate_tokens(text: str) -> int:
    return len(text) // 2               # 한국어 대략치 (1 자 = 0.5 ~ 1 토큰)

def fit_context(chunks, max_tokens=4000):
    result, used = [], 0
    for c in chunks:
        t = estimate_tokens(c)
        if used + t > max_tokens: break
        result.append(c); used += t
    return result

컨텍스트 80% 만 사용 · 20% 는 응답 공간
tiktoken · tokenizers 라이브러리가 정확한 카운트

6. A/B 테스트 한 줄

# prompts.py
PROMPTS = {
    "v1": "당신은 어시스턴트입니다. 짧게 답하세요.",
    "v2": "당신은 기술 문서 전문 어시스턴트입니다. 3~5 문장, 코드 예시 포함.",
}
selected = PROMPTS[os.environ.get("PROMPT_VERSION", "v2")]

버전별 응답을 로그 · 피드백 수집 → 다음 배포 때 winner.

7. 자주 걸리는 자리

시스템 프롬프트에 사용자 입력 삽입 — prompt injection 취약. 사용자 입력은 반드시 user role 에
Few-shot 예시가 편향 — 한 카테고리만 3 개면 편향 학습
JSON 요청했는데 실패 — 재시도 + 명시적 "JSON only, no prose"
너무 긴 시스템 프롬프트 — 컨텍스트 낭비 · latency 증가. 300 ~ 800 자 권장

하고픈 말

프롬프트 설계는 코드 리뷰처럼 남이 한 번 더 보는 게 효과적. "이 프롬프트가 악의적 입력에서 어떻게 깨지나?" 를 질문.

security/02-oauth-state-pkce
ai/06-agents-overview