일관된 JSON 응답을 위한 AI 프롬프트 방법

Source: Dev.to

This was originally posted on the VSL Substack publication.

잘못된 JSON은 높은 비용을 초래합니다

API 연동, 데이터베이스 작업, 설정 파일 등 구조화된 데이터를 필요로 하는 기능을 구축할 때, JSON 일관성은 앱이 정상 작동할지 아니면 깨질지를 직접 결정합니다. 하나의 형식이 잘못된 응답만으로도 수백 건의 사용자 행동 실패, 데이터베이스 쓰기 손상, 그리고 지원 티켓이 쏟아지는 상황이 빠르게 발생합니다.

AI가 개발 단계에서는 올바르게 보이는 JSON을 생성하지만, 실제 운영 환경에서는 다음과 같은 불일치가 드러납니다:

• 엄격한 파서에서 발생하는 누락된 콤마 또는 뒤에 붙는 콤마
• 사용자 생성 콘텐츠에서 이스케이프되지 않은 따옴표
• 국제 사용자의 유니코드 문자

이러한 사소한 포맷 오류가 전체 기능을 중단시키므로, 유효하고 프로덕션에 바로 사용할 수 있는 JSON을 일관되게 출력하도록 AI를 제어해야 합니다.

공항 보안 모델

공항 보안은 체크인, 보안 검색, 탑승구에서 문서를 여러 번 확인합니다. 실수는 나중에 고치기 비싸기 때문이죠. JSON 검증도 같은 원리입니다: AI는 제어된 조건에서는 구조적으로 올바른 JSON을 만들 수 있지만, 실제 변동성에서는 종종 깨집니다. 여러 검증 체크포인트를 두면 오류가 프로덕션에 도달하기 전에 잡을 수 있습니다.

대부분의 개발자는 프롬프트 단계에서 멈추지만, 프로덕션 수준의 앱은 신뢰성을 보장하기 위해 다섯 개의 별도 체크포인트가 필요합니다.

AI가 데이터를 망치는 가장 흔한 방식

• 구문 오류 – 누락되거나 과다한 콤마, 대괄호, 따옴표가 JSON.parse()를 즉시 실패하게 합니다. 예: 마지막 속성 뒤에 붙은 콤마 또는 닫히지 않은 중첩 객체.
• 이스케이프 문자 함정 – JSON 문자열 안에서 문자를 이중 이스케이프(\\" 대신 \")하면 기술적으로는 유효한 문자열이지만 파서에서는 잘못된 JSON이 됩니다.
• 구조 불일치 – 형식은 맞지만 기대하는 형태와 다른 JSON 객체를 받는 경우, 예: {"title":"My Article"} 대신 {"article":{"title":"My Article"}}가 필요할 때.
• 타입 혼동 – 숫자가 필요한 곳에 문자열을 반환하거나, 객체가 필요한 곳에 배열을 반환합니다. 예: 25 대신 "25"(문자열).
• 잘린 응답 – 큰 페이로드는 모델의 토큰 제한에 걸려 JSON 조각이 불완전하게 잘릴 수 있습니다. 신뢰할 수 있는 해결책은 데이터를 작은 청크로 요청하고 코드에서 결과를 합치는 것입니다.

탄탄한 JSON을 위한 5‑체크포인트 프레임워크

1. 프롬프트를 명확히

말하지 말 것: “SEO 데이터를 JSON으로 반환해 주세요.”

말할 것: “오직 유효한 JSON만 반환하고 추가 텍스트는 포함하지 마세요. 정확히 이 구조를 사용하세요: {\"title\": string, \"description\": string}.”

2. JSON 스키마 제공

일관된 JSON 구조를 얻는 가장 확실한 방법은 AI에게 정확한 스키마를 제시하는 것입니다. JSON Schema는 데이터의 구조, 타입, 요구 사항을 정의해 모호성을 없애줍니다.

프롬프트에 다음을 추가하세요:

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 70,
      "description": "매력적이고 SEO‑친화적인 기사 제목"
    },
    "description": {
      "type": "string",
      "maxLength": 160,
      "description": "기사 내용의 간결한 요약"
    }
  },
  "required": ["title", "description"],
  "additionalProperties": false
}

왜 효과적인가: 스키마는 타입 혼동과 구조 불일치를 없애줍니다. 모델은 생성 과정에서 스키마 패턴에 맞춰 출력을 검증합니다. additionalProperties: false 플래그는 허위 필드를 차단해 오류가 코드에 도달하기 전에 잡아냅니다. 자세한 내용은 OpenAPI Schema specification을 참고하세요.

3. 코드 펜스 요청

프롬프트에 “JSON을 json 구문 강조가 적용된 마크다운 코드 펜스로 감싸 주세요.” 라고 추가하세요.

이는 AI가 JSON 앞뒤에 설명 텍스트를 삽입하는 것을 방지해, 응답을 추출할 때 파싱 오류가 발생하지 않게 합니다.

4. 사용 전에 검증

AI 출력이 유효하다고 가정하지 마세요. 항상 파싱을 try‑catch 블록으로 감싸세요:

try {
  const data = JSON.parse(aiResponse);
  // 여기서 data 사용
} catch (error) {
  console.error('AI에서 받은 JSON이 유효하지 않음:', error);
  // 오류를 우아하게 처리
}

5. 파싱 후 구조 확인

유효한 JSON이라도 형태가 맞는지는 별개입니다. 파싱 후 가벼운 검증을 수행하세요:

function validateSeoData(data) {
  if (!data.title) return false;
  if (typeof data.title !== 'string') return false;
  if (typeof data.description !== 'string') return false;
  return true;
}

위험 신호: 주의할 점

• 🚩 AI가 JSON 앞뒤에 설명 텍스트를 추가 – 파싱이 깨집니다.
• 🚩 누락되거나 과다한 콤마, 대괄호, 따옴표 – 즉시 JSON.parse 실패를 초래합니다.
• 🚩 이중 이스케이프 문자 – 유효하지 않은 JSON 문자열을 만들게 합니다.
• 🚩 예상치 못한 구조나 타입 – 하위 로직 오류를 유발합니다.
• 🚩 출력이 잘림 – 불완전하고 파싱할 수 없는 페이로드가 됩니다.

위의 다섯 체크포인트를 적용하고 이러한 위험 신호에 지속적으로 주의한다면, AI 모델로부터 언제든지 깨끗하고 프로덕션에 바로 사용할 수 있는 JSON을 안정적으로 얻을 수 있습니다.