Quick Reference

출력이 흔들릴 때는 먼저 사람이 읽을 결과인지, 프로그램이 파싱할 계약인지를 나눕니다. 지시문과 예시는 내용·톤을 맞추는 방법이고, prefill은 응답 시작을 유도하는 호환성 의존 기법이며, JSON schema가 반드시 맞아야 하면 API의 structured outputs를 사용합니다.

출력 계약
- fields: title, risk, evidence
- risk: low | medium | high
- evidence가 없으면 null
- 추가 설명이나 Markdown은 출력하지 않음

형식 계약을 먼저 쓰는 법

형식 일관성은 "JSON으로 답해 줘"보다 필드 이름, 타입, 순서가 중요한지, 누락 값, 추가 설명 허용 여부를 적을 때 좋아집니다. 사람이 읽는 보고서라면 자연스러운 문장을 허용할 수 있지만, 파서가 받는 출력은 이 계약을 프로그램 수준으로 검증해야 합니다.

예시는 모델에게 답의 모양뿐 아니라 판단 기준을 보여 줍니다. 정상 입력 하나만 주면 예외를 억지로 정상 형태에 넣을 수 있으므로, 값이 없는 경우와 둘 이상의 후보가 있는 경우도 포함합니다. 예시는 실제 입력과 같은 개인정보·고객 식별자를 반복하지 않고, 합성 데이터로 만듭니다.

예시 1: 근거가 있는 입력
{ "risk": "high", "evidence": "production database" }

예시 2: 근거가 없는 입력
{ "risk": "low", "evidence": null }

prefill과 structured outputs

assistant prefill은 assistant message를 미리 시작해 응답이 {, XML tag, 정해진 접두사에서 이어지도록 유도하는 방식입니다. 이 방법의 지원 여부와 제약은 모델·API 버전에 따라 달라질 수 있으므로, 새 구현에서 보편적인 JSON 보장 장치로 가정하지 않습니다. 사용한다면 지원 모델에서 접두사, 빈 입력, refusal, 최대 출력 길이를 모두 테스트합니다.

구조가 API 계약이면 prefill 대신 structured outputs를 고릅니다. output_config.format에 json_schema를 넣으면 Claude의 text content block이 schema에 맞는 유효 JSON으로 반환됩니다. 이는 Claude 웹·데스크톱 대화 화면의 형식 지시가 아니라 Messages API 기능입니다.

response = client.messages.create(
    model="지원 모델 ID",
    max_tokens=1_024,
    messages=[{"role": "user", "content": source_text}],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": schema,
        }
    },
)

검증과 실패 처리

schema를 사용해도 내용이 사실인지, enum 선택이 업무 규칙에 맞는지, 근거 문장이 원문을 뒷받침하는지는 보장하지 않습니다. JSON parsing 실패가 아니라 request 오류, timeout, refusal, 입력 부족, 오래된 retrieval 자료가 실제 실패 원인이 될 수 있습니다. 그러므로 schema validation 뒤에 domain validation과 원문 대조를 둡니다.