역할 지정이 틀리면 에러보다 무섭다: 조용한 오답을 잡는 법

역할 지정의 진짜 함정

"당신은 전문가입니다"처럼 막연한 역할 지정은 모델이 원하는 페르소나를 임의로 채워 예상치 못한 방향으로 흐릅니다. 더 위험한 건 에러가 아니라 자신감 넘치는 오답이 돌아온다는 점입니다.

좋은 역할 지정의 3요소:

1. 도메인 + 제약 — "당신은 한국 세법 전문가이며, 2024년 이전 법령만 참조합니다."
2. 출력 형식 명시 — "답변은 반드시 JSON으로 반환하고, 확실하지 않은 항목은 null로 표기하세요."
3. 범위 이탈 시 행동 정의 — "모르면 '확인이 필요합니다'라고만 답하세요."

에러 핸들링: API 오류 vs 조용한 오답

API 에러는 try/catch로 잡으면 끝이지만, 역할 이탈로 인한 오답은 코드가 정상 실행되고 나서야 문제가 드러납니다. 두 레이어를 모두 방어해야 합니다.

import anthropic
import json

client = anthropic.Anthropic()

SYSTEM_PROMPT = """당신은 제품 리뷰 감성 분석 전문가입니다.
반드시 아래 JSON 형식으로만 응답하세요:
{"sentiment": "positive|negative|neutral", "score": 0.0~1.0, "reason": "한 문장"}
형식을 벗어난 응답은 절대 하지 마세요."""

def analyze_sentiment(review_text: str) -> dict:
    # ── 레이어 1: API 호출 에러 처리 ──
    try:
        response = client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=256,
            temperature=0.1,  # 구조화 출력엔 낮게
            system=SYSTEM_PROMPT,
            messages=[{"role": "user", "content": review_text}],
        )
    except anthropic.RateLimitError:
        return {"error": "rate_limit", "retry_after": 60}
    except anthropic.APIStatusError as e:
        return {"error": "api_error", "status_code": e.status_code}

    raw = response.content[0].text.strip()

    # ── 레이어 2: 역할 이탈(조용한 오답) 검증 ──
    try:
        result = json.loads(raw)
        assert result["sentiment"] in {"positive", "negative", "neutral"}
        assert 0.0 <= float(result["score"]) <= 1.0
        assert isinstance(result.get("reason"), str)
    except (json.JSONDecodeError, KeyError, AssertionError):
        # 형식 위반 → 재시도 또는 폴백 처리
        return {"error": "format_violation", "raw_response": raw}

    return result

# 사용 예
print(analyze_sentiment("배송이 너무 느려서 별로였어요."))

포인트: claude-haiku-4-5는 속도·비용 효율이 좋지만 역할 준수율이 낮아질 수 있습니다. 레이어 2 검증이 없으면 오류가 프로덕션까지 흘러갑니다.

역할 설계 + 에러 핸들링 체크리스트

• [ ] System 프롬프트에 도메인 + 출력 형식 + 범위 이탈 행동을 모두 명시했는가
• [ ] 막연한 "전문가" 대신 구체적인 제약 조건을 추가했는가
• [ ] API 호출을 try/catch로 감싸 RateLimitError, APIStatusError를 구분 처리하는가
• [ ] JSON·구조화 응답은 스키마 검증 레이어를 별도로 두는가
• [ ] 검증 실패 시 재시도 횟수(max 2~3회) 상한을 설정했는가
• [ ] 폴백 응답(사용자에게 보여줄 기본값)을 미리 정의했는가
• [ ] temperature 0.3 이하로 설정해 형식 일관성을 높였는가