목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Structured Outputs 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/build-with-claude/structured-outputs 마지막 확인: 2026-05-20
1. 한 줄 요약 #
Claude에게 “이런 칸들에 채워서 답해줘"라고 미리 양식을 정해주면, 답이 그 양식대로만 깔끔하게 나옵니다.
2. 무엇이고 왜 좋을까 #
설문조사 종이를 미리 만들어두고 답하게 하는 것과 같습니다. 자유롭게 줄글로 쓰라고 하면 사람마다 답이 제각각이지만, “이름: __, 나이: __, 좋아하는 색: __” 이렇게 칸을 만들어두면 답이 일정하게 모입니다.
AI에게 자유롭게 답하라고 하면, 같은 질문에도 어떤 날은 “이름은 김철수이고, 나이는 30세입니다"라고 답하고, 다른 날은 “성함: 김철수 / 연령: 30” 식으로 답합니다. 사람이 읽기엔 똑같지만, 그 결과를 엑셀이나 다른 프로그램에 옮겨 담으려면 매번 다르게 정리해야 해서 골치가 아픕니다.
구조화 출력(Structured Outputs) 은 이 문제를 해결합니다. “이름은 글자로, 나이는 숫자로, 데모 요청 여부는 예/아니오로” 같은 양식을 미리 정해주면, Claude가 항상 그 양식대로만 답을 내놓습니다. 핵심 효과 하나: 답이 양식과 어긋날 일이 사실상 0% 입니다(공식 문서 표현으로는 “schema-compliant 보장”). 결과를 받아서 다시 정리할 필요가 없습니다.
3. 이런 상황에서 써요 #
상황 1: 학생 — 강의 자료에서 표 만들기 #
대학 강의에서 “교수님이 추천한 책 30권"이 PDF 강의안 곳곳에 흩어져 있다고 해봐요. 책 제목, 저자, 추천 이유를 손으로 옮겨 적자니 두 시간은 걸릴 일입니다. AI에게 “책 목록 정리해줘"라고 하면 줄글로 길게 답해주긴 하는데, 그걸 엑셀에 옮기는 게 또 일이죠.
이때 “제목·저자·추천이유, 이렇게 세 칸으로만 답해줘"라고 양식을 정해주면, 답이 표처럼 깔끔하게 30줄로 나옵니다. 그대로 복사해서 엑셀에 붙이면 끝입니다.
상황 2: 직장인 — 고객 문의 메일 정리 #
회사 대표 메일함에 “데모 신청합니다”, “가격 문의드려요”, “샘플 보내주세요” 같은 메일이 하루에도 수십 통씩 쌓입니다. 누가 어느 회사에서, 무엇을 원해서, 언제 답을 줘야 하는지 한 명씩 읽고 정리하기엔 시간이 너무 듭니다.
“보낸이 이름 / 회사명 / 요청 종류 / 답변 시급도, 이 네 칸으로 정리해줘"라고 양식을 정해주면, 메일 하나당 깔끔한 카드 한 장처럼 정리된 결과가 나옵니다. 그대로 사내 시트에 옮기거나 담당자에게 분배하기 쉬워집니다.
상황 3: 일반인 — 책 한 권 독서 노트 #
긴 자기계발서 한 권을 다 읽고 나면 머리에 남는 게 흐릿할 때가 있어요. AI에게 “정리해줘” 하면 줄글로 길게 답이 오는데, 나중에 다시 꺼내 보려면 또 통째로 읽어야 합니다.
“챕터별로 핵심 문장 한 줄, 내 일에 적용할 점 한 줄, 다시 읽고 싶은 페이지 번호, 이렇게 세 가지로만 정리해줘"라고 양식을 주면, 책 한 권이 카드 10장짜리 요약 노트로 변합니다. 노션이나 메모 앱에 그대로 옮겨 두면, 한 달 뒤에도 1분이면 다시 훑어볼 수 있어요.
4. 가볍게 시작하기 #
💻 개발 경험이 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “이런 식으로 양식을 정의하는구나” 정도로 보고 넘어가셔도 좋습니다.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{
"role": "user",
"content": "다음 메일에서 핵심 정보를 뽑아줘: "
"김철수([email protected])님이 엔터프라이즈 요금제에 "
"관심이 있으시고, 다음 주 화요일 오후 2시 데모를 원하십니다."
}],
# 답을 받을 '양식'을 미리 정의합니다
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"}, # 이름은 글자
"email": {"type": "string"}, # 이메일도 글자
"plan_interest": {"type": "string"}, # 관심 요금제도 글자
"demo_requested": {"type": "boolean"}, # 데모 요청은 예/아니오
},
# 이 네 칸은 반드시 채워져야 함
"required": ["name", "email", "plan_interest", "demo_requested"],
"additionalProperties": False,
},
}
},
)
print(response.content[0].text)핵심은 output_config 한 덩어리입니다. properties 안에 “이름은 글자, 데모 요청 여부는 예/아니오” 처럼 각 칸의 타입을 적어두면, Claude는 무슨 일이 있어도 그 양식대로만 답합니다. 줄글로 답이 섞이거나 칸이 빠질 일이 없어서, 받은 결과를 곧장 엑셀·구글시트·다른 앱에 옮겨 담을 수 있습니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “양식만 정하면 알아서 좋은 답이 나오겠지?” #
양식은 “어떤 칸에 답을 담을지"만 정해줍니다. 무엇을 담을지는 여전히 질문 글에 달려 있어요. “이메일에서 정보 뽑아줘"라고만 하고 정작 메일 내용을 안 붙이면, 칸은 만들어지지만 안에는 빈 글자나 그럴듯한 가짜 정보가 들어갑니다.
❌ “고객 정보 뽑아줘” (자료 없음) → 칸은 채워지지만 내용은 추측 ✅ “다음 메일에서 뽑아줘: (메일 본문 붙여넣기)” → 정확한 정보
⚠️ 함정 2: “답이 중간에 잘려서 양식이 깨졌어요” #
양식은 답이 끝까지 나왔을 때만 보장됩니다. max_tokens(답변 최대 길이) 값을 너무 작게 잡아두면, 답이 양식 중간에서 뚝 끊기고 “괄호가 안 닫혔다"는 식의 오류가 납니다. 표 30줄을 뽑고 싶은데 답 길이를 100자로 잡아둔 경우가 대표적입니다. 응답이 너무 길어 보이면 max_tokens를 넉넉히(예: 2048 이상) 늘려보세요.
⚠️ 함정 3: “처음 한 번이 너무 느려요” #
같은 양식을 처음 쓸 때는 “이 양식 외워두기” 작업 때문에 몇 초 더 걸릴 수 있습니다. 다행히 같은 양식을 다시 쓰면 24시간 동안 빨라진 상태로 유지됩니다. “왜 두 번째부터 빨라지지?“가 아니라 “원래 그렇게 설계되어 있구나” 정도로 알아두시면 됩니다. 양식 글자를 조금이라도 바꾸면 다시 처음처럼 느려진다는 점만 기억하세요.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
파이썬에서는 매번 properties를 손으로 적는 대신, Pydantic이라는 도구로 클래스 하나만 만들어두면 그게 곧 양식이 됩니다. 영수증을 출력하는 도장 같은 거예요. 한 번 만들어두면 여러 번 깔끔하게 찍을 수 있습니다.
from pydantic import BaseModel
from anthropic import Anthropic
# '연락처 정보'라는 양식 도장을 만듭니다
class ContactInfo(BaseModel):
name: str # 이름 — 글자
email: str # 이메일 — 글자
plan_interest: str # 관심 요금제 — 글자
demo_requested: bool # 데모 요청 여부 — 예/아니오
client = Anthropic()
response = client.messages.parse(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{
"role": "user",
"content": "다음 메일에서 정보 뽑아줘: 김철수([email protected])님이 "
"엔터프라이즈 요금제에 관심이 있고, 다음 주 화요일 오후 2시 데모 희망."
}],
output_format=ContactInfo, # 만들어둔 도장을 그대로 넘김
)
# .parsed_output 으로 바로 객체처럼 꺼내쓸 수 있습니다
print(response.parsed_output.name) # "김철수"
print(response.parsed_output.demo_requested) # TrueJSON 양식을 직접 적기 vs. Pydantic 클래스
| 항목 | 직접 적기 | Pydantic 클래스 |
|---|---|---|
| 첫 시도 난이도 | 쉬움 (그냥 칸만 적으면 됨) | 처음에 라이브러리 설치 필요 |
| 양식 재사용 | 칸 정의를 매번 복붙 | 클래스 하나 만들어두면 끝 |
| 결과 꺼내쓰기 | 글자에서 다시 파싱 필요 | .name, .email 식으로 바로 사용 |
| 추천 | 한두 번 쓸 때 | 같은 양식을 여러 곳에서 쓸 때 |
처음에는 직접 적기로 시작하시고, “같은 양식을 또 쓰네?” 싶을 때 Pydantic으로 넘어가시면 자연스럽습니다.
7. 한 마디 #
처음 보면 “양식? JSON? 어려워 보인다"는 생각이 들 수 있어요. 그런데 사실은 종이 설문지 만드는 것과 똑같습니다. “이름 칸, 나이 칸, 좋아하는 색 칸"을 정해두면 답이 깔끔하게 모이는 그 단순한 원리예요. 코드는 그 설문지를 글자로 옮긴 것뿐입니다.
혹시 결과가 이상하게 나오면 함정 1~3 중 하나일 가능성이 높습니다. 자료를 안 붙였거나, 답 길이를 너무 짧게 잡았거나, 양식을 잠깐 바꿔서 다시 느려진 경우죠. 천천히 하나씩 확인해보세요.
다음 가이드(#11)에서는 Citations(인용) — Claude가 답할 때 “이 문장은 어느 자료의 몇 페이지에서 가져왔어요"라고 출처까지 함께 알려주는 기능을 살펴보겠습니다. 자료 기반 작업을 하시는 분들께 든든한 친구가 되어줄 거예요.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
