---
name: structured-output
description: >
  사용자가 텍스트나 도구 결과를 JSON·표·CSV 같은 구조화된 형식으로 추출·변환해
  달라고 할 때 로드한다 — 스키마가 주어지지 않았어도 해당한다. 스키마 준수, 누락
  값 처리와 machine-readable 출력 계약을 지킨다.
---

# 구조화 출력 스킬

비정형 텍스트(대화, 문서, 도구 결과)를 JSON, 표, CSV 같은 구조화된 형식으로
추출·변환할 때 따르는 지침이다.

## 공통 규칙

- **스키마가 주어지면 그대로 따른다.** 필드를 추가하거나 이름을 바꾸지 않는다.
- **원문에 없는 값을 만들지 않는다.** 찾을 수 없는 필드는 `null`(JSON) 또는
  빈 칸으로 두고, 추론한 값이면 사용자에게 추론임을 밝힌다.
- **출력 계약을 먼저 지킨다.** `JSON only`, `raw JSON`, `CSV only`처럼
  machine-readable 결과를 요구하면 앞뒤 설명과 code fence 없이 결과만 반환한다.
- 설명이 허용된 일반 대화에서는 결과 뒤에 필요한 설명만 짧게 분리한다.
- 날짜는 `YYYY-MM-DD`, 숫자는 천 단위 구분 없이, 통화·단위는 별도 필드로
  분리하는 것을 기본으로 한다 (스키마가 다르게 정하면 스키마 우선).

## JSON

- 유효한 JSON만 출력한다 — 주석, trailing comma, 작은따옴표 금지.
- machine-readable 출력이면 code fence 없이 반환한다. 사람이 읽는 일반 대화이고
  별도 출력 계약이 없을 때만 `json` code fence를 사용한다.
- 스키마가 없으면 먼저 간단한 스키마를 제안하고 확인을 받은 뒤 추출한다.
  단, 요청이 명확하면 (예: "이름과 이메일만 뽑아줘") 바로 진행한다.
- 배열 항목의 키 순서를 모든 항목에서 동일하게 유지한다.

## 표 / CSV

- 사용자 스키마가 없을 때 표는 가능하면 열 수를 5개 이하로 유지한다.
  주어진 열을 임의로 제거하지 않는다.
- CSV는 첫 줄에 헤더를 두고, 쉼표·따옴표·줄바꿈이 들어간 값은 CSV 규칙에 맞게
  큰따옴표로 감싼다. 값 안의 큰따옴표는 두 번 쓴다.
- 정렬 기준이 있으면 명시하고 적용한다 (예: 날짜 내림차순).

## 도구 결과에서 추출할 때

도구가 돌려준 데이터는 "원문"이 아니라 **어느 시점에 어느 출처가 준 답**이다.

- **결과가 잘렸는지 먼저 본다.** 잘린 결과에는 그렇다는 표시가 붙는다. 그 상태로
  추출하면 부분 목록을 전체인 것처럼 내놓게 된다. 표시가 있으면 결과에 남기거나,
  스키마에 자리가 없으면 결과 밖에 한 줄로 밝힌다.
- **`Error:`로 시작하는 결과는 데이터가 아니다.** 실패한 호출의 메시지를 값으로
  집어넣지 않는다.
- 여러 도구·서버의 결과를 한 표에 합칠 때는 **행마다 출처를 남긴다.** 스키마에
  출처 필드가 없으면 합치기 전에 물어보거나, 출처별로 나눠서 내놓는다.
- 같은 항목을 두 출처가 다르게 말하면 임의로 하나를 고르지 않는다. 둘 다 보이거나
  불일치를 밝힌다.
- 조회 시점이 의미를 바꾸는 값(가격, 재고, 순위)은 언제 기준인지 함께 적는다.

## 검증

출력 전에 스스로 확인한다:

- 항목 수가 원문과 일치하는가 (빠뜨리거나 중복하지 않았는가)
- 원문이 잘리지 않았는가 — 잘렸다면 "전체"라고 말하지 않았는가
- 모든 값이 원문에서 추적 가능한가
- JSON이라면 파싱 가능한 문법인가

원문이 모호해서 두 가지 이상으로 해석되는 값이 있으면 임의로 고르지 않는다.
스키마에 표현할 수 있으면 `null`을 사용하고, 설명 필드가 허용될 때만 불확실성을
그 필드에 기록한다. 출력 계약이 추가 필드를 허용하지 않으면 결과를 만들기 전에
한 가지 핵심 질문을 한다.