핵심 정리

{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "riskLevel": { "type": "string" }
        },
        "required": ["summary", "riskLevel"],
        "additionalProperties": false
      }
    }
  }
}

구조

structured outputs는 형식 요청이 아니라 decoding 제약이다

일반 프롬프트에서 "JSON으로 답해라"라고 쓰면 Claude가 형식을 따르도록 유도할 뿐입니다. structured outputs는 API 요청에 JSON schema를 넣어 응답 형식을 더 강하게 제한합니다. downstream 코드가 JSON.parse()나 타입 검증에 의존한다면 prompt-only 방식보다 structured outputs가 맞습니다.

prompt-only
  -> 모델이 형식을 따르도록 요청

structured outputs
  -> API 응답 형식을 schema로 제한

schema는 사람이 읽는 출력 예시가 아니라 애플리케이션 계약입니다. 필드 이름, 필수 여부, 허용 타입, 추가 속성 허용 여부를 실제 파서 기준으로 정해야 합니다.

JSON outputs와 strict tool use는 해결하는 문제가 다르다

JSON outputs는 Claude의 최종 텍스트 응답이 어떤 JSON 구조를 가져야 하는지 다룹니다. strict tool use는 tool call의 이름과 입력 인자가 schema에 맞는지 다룹니다. 에이전트 흐름에서는 둘을 함께 쓸 수 있지만, 검증 대상이 다르다는 점을 분리해야 합니다.

JSON outputs
  -> 최종 답변 구조

strict tool use
  -> tool call 입력 구조

최종 보고서는 JSON outputs로, 내부 API 호출 인자는 strict tool use로 제한하는 방식이 자연스럽습니다.

schema가 복잡할수록 비용과 실패 지점이 늘어난다

structured outputs는 schema를 grammar로 컴파일해 사용합니다. schema가 복잡하면 최초 요청 지연이 생기고, optional field나 union type이 많을수록 complexity limit에 걸릴 수 있습니다. 모든 필드를 유연하게 열어 두는 schema보다, 실제로 필요한 필드만 좁게 정의한 schema가 안정적입니다.

선택 기준

주의할 점

schema 이름, enum 값, pattern에 민감 정보나 개인정보를 넣으면 schema 캐싱과 로그 정책에서 별도 위험이 생길 수 있습니다. 민감한 값은 schema가 아니라 사용자 메시지나 내부 데이터로 다루는 편이 안전합니다.