Structured data · Claude API로 구축하기

Claude가 JSON, Python 코드, 또는 글머리 기호 목록과 같은 구조화된 데이터를 생성하도록 요청할 때, 흔히 마주치는 문제가 있습니다. Claude는 도움이 되고자 콘텐츠 주변에 설명 텍스트를 추가하려고 합니다. 이는 대부분의 경우 훌륭하지만, 때로는 다른 것 없이 원시 데이터만 필요할 때가 있습니다.

AWS EventBridge 규칙을 생성하는 웹 앱을 만든다고 생각해 보세요. 사용자가 설명을 입력하고 생성 버튼을 클릭하면, 즉시 복사해서 사용할 수 있는 깔끔한 JSON을 기대합니다. Claude가 설명 텍스트와 함께 마크다운 코드 블록으로 감싼 JSON을 반환하면, 사용자는 전체 응답을 그대로 복사할 수 없고 JSON 부분만 수동으로 선택해야 합니다.

기본 응답의 문제점

기본적으로 Claude에게 JSON을 생성하도록 요청하면 다음과 같은 결과를 얻을 수 있습니다:

markdown

```json
\{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": \{
    "state": ["running"]
  \}
\}
```

This rule captures EC2 instance state changes when instances start running.

JSON은 정확하지만 마크다운 형식으로 감싸져 있고 설명 텍스트가 포함되어 있습니다. 사용자가 원시 JSON을 복사해야 하는 웹 앱의 경우, 이는 사용자 경험에 마찰을 일으킵니다.

해결책: 어시스턴트 메시지 프리필링 + 중지 시퀀스

어시스턴트 메시지 프리필링과 중지 시퀀스를 결합하여 원하는 콘텐츠만 정확히 얻을 수 있습니다. 작동 방식은 다음과 같습니다:

python

messages = []

add_user_message(messages, "Generate a very short event bridge rule as json")
add_assistant_message(messages, "```json")

text = chat(messages, stop_sequences=["```"])

이 기법은 다음과 같이 작동합니다:

사용자 메시지는 Claude에게 무엇을 생성할지 알려줍니다
프리필된 어시스턴트 메시지는 Claude가 이미 마크다운 코드 블록을 시작했다고 생각하게 만듭니다
Claude는 JSON 콘텐츠만 작성하며 계속합니다
Claude가 ```로 코드 블록을 닫으려고 할 때, 중지 시퀀스가 즉시 생성을 종료합니다

결과는 추가 형식이 없는 깔끔한 JSON입니다:

json

{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["running"]
  }
}

응답 처리하기

응답에서 몇 개의 추가 줄바꿈 문자를 발견할 수 있습니다. 이는 쉽게 처리할 수 있습니다:

python

import json

# JSON을 정리하고 파싱합니다
clean_json = json.loads(text.strip())

JSON을 넘어서

이 기법은 JSON 생성에만 국한되지 않습니다. 설명 없이 구조화된 데이터가 필요할 때마다 사용하세요:

Python 코드 스니펫
글머리 기호 목록
CSV 데이터
설명이 아닌 콘텐츠만 원하는 모든 형식의 콘텐츠

핵심은 Claude가 자연스럽게 콘텐츠를 감싸고자 하는 것을 파악한 다음, 이를 프리필과 중지 시퀀스로 사용하는 것입니다. 코드의 경우 보통 마크다운 코드 블록입니다. 목록의 경우 다른 형식 마커일 수 있습니다.

이 접근 방식은 Claude의 출력 형식을 정밀하게 제어할 수 있게 해주어, 깔끔하고 구조화된 데이터가 필수적인 애플리케이션에 AI가 생성한 콘텐츠를 통합하는 것을 훨씬 쉽게 만들어 줍니다.