[카테고리:] ezformatter

API 호출이 JSONDecodeError: Expecting property name enclosed in double quotes로 실패했습니다. 시계가 째깍째깍 돌아갑니다. 데이터는 LLM에서 왔고, 2,000 토큰짜리 응답 어딘가에서 후행 쉼표 하나가 전체 파이프라인을 망가뜨렸습니다.

2026년 5월 현재, 잘못된 JSON 파일을 수정하는 가장 빠른 방법은 json_repair(Python) 또는 jsonrepair(npm) 같은 자동화 라이브러리를 사용하는 것입니다. 이 도구들은 LLM이 생성한 구문 오류를 즉시 수정하도록 특별히 설계되었습니다. 수동 수정의 경우, 흔한 범인은 후행 쉼표, 작은따옴표, 인용되지 않은 키입니다. 이는 RFC 8259 표준을 위반하는 가장 흔한 세 가지 사례입니다.

가장 빠른 수정: LLM 출력을 위한 json_repair

Python의 json.loads() 같은 표준 파서는 설계상 엄격합니다. 잘못 배치된 문자 하나가 JSONDecodeError를 발생시키고 모든 것이 멈춥니다. 이는 2026년에 일상적인 문제입니다. LLM이 JSON을 대화형 텍스트로 감싸거나, 응답을 문장 중간에 잘라버리거나, 사양을 깨뜨리는 주석을 뿌려 넣기 때문입니다.

json_repair 라이브러리가 정답입니다. GitHub에 따르면, 2026년 현재 이 프로젝트는 4,700개 이상의 별을 받았습니다. 이 도구는 문자열의 의도를 “추측”하는 방식으로 동작합니다. 누락된 괄호를 닫고, 따옴표를 추가하고, JSON 블록 주변의 불필요한 텍스트를 제거합니다.

Python: 수정 전과 후

설치: pip install json-repair

손상된 입력:

import json_repair

bad_json = '{"user": "Alice", "status": tru'
decoded_object = json_repair.loads(bad_json)

내부적으로 무슨 일이 일어났는지: json_repair는 tru가 아마도 true일 것이라고 판단하고, 누락된 닫는 중괄호를 추가한 다음, 유효한 Python 딕셔너리를 반환했습니다. 수동 개입은 전혀 없었습니다.

Salvage 모드: 데이터가 정말 엉망일 때

더 까다로운 경우를 위해, json_repair(v0.59.5+)에는 Salvage 모드가 있습니다. 프로젝트 문서에 설명된 대로, 이 모드는 잘린 AI 응답이나 손상된 로그를 위해 특별히 만들어졌습니다. 배열을 객체로 강제 변환하거나 너무 손상되어 복구할 수 없는 항목을 삭제하여 출력이 스키마에 맞도록 보장합니다.

import json_repair

# Salvage mode for severely truncated data
result = json_repair.loads(
    '{"items": [{"id": 1, "name": "Widget"}, {"id": 2, "na',
    salvage_mode=True
)
# Result: {'items': [{'id': 1, 'name': 'Widget'}, {'id': 2}]}
# Dropped the incomplete 'na' but saved everything else

npm 대안

Node.js 프로젝트의 경우, jsonrepair CLI가 같은 작업을 처리합니다:

# Fix a file in place
npx jsonrepair broken.json > fixed.json

# Fix a string in a script
const { jsonrepair } = require('jsonrepair');
const fixed = jsonrepair('{"name": "test",}');

수동 디버깅: 사양을 깨뜨린 것 찾기

자동화로는 부족할 때, 파일이 정확히 어디에서 RFC 8259를 위반했는지 찾아야 합니다. JSON은 YAML이나 JavaScript보다 훨씬 관대하지 않습니다. JSONParser 진단 팀의 설명에 따르면, “파서는 이해할 수 없는 첫 번째 문자에서 실패하는데, 이는 종종 몇 줄 앞선 문제의 하위 증상입니다.”

3대 JSON 킬러

킬러 1: 후행 쉼표

DEV Community에 따르면, 후행 쉼표는 파싱 실패의 1번째 원인입니다. JavaScript에서는 괜찮지만, JSON 배열이나 객체의 마지막 항목 뒤에는 허용되지 않습니다.

// BROKEN - trailing comma after "active"
{
  "name": "Alice",
  "status": "active",
}

// FIXED - no comma before closing brace
{
  "name": "Alice",
  "status": "active"
}

킬러 2: 작은따옴표

JSON은 키와 문자열 값 모두에 이중 따옴표(")를 요구합니다. 많은 Python과 JavaScript 개발자가 실수로 작은따옴표(')를 사용합니다. TidyCode가 지적하듯, 이는 반드시 수정해야 합니다.

// BROKEN - single quotes
{'name': 'Alice'}

// FIXED - double quotes
{"name": "Alice"}

킬러 3: 인용되지 않은 키

JavaScript에서는 { name: "Alice" }라고 쓸 수 있습니다. 하지만 JSON에서는 모든 키에 이중 따옴표가 필요합니다.

// BROKEN - unquoted key
{name: "Alice"}

// FIXED - quoted key
{"name": "Alice"}

“Unexpected Token” 오류

검증기가 “Unexpected Token”을 보고하면, 파서가 NaN, Infinity, 또는 undefined를 만났다는 뜻입니다. 이는 JSON이 지원하지 않는 JavaScript 상수입니다. JSON은 null, true, false, 숫자만 허용합니다.

// BROKEN - NaN is not valid JSON
{"score": NaN, "result": Infinity}

// FIXED - replace with null or valid values
{"score": null, "result": null}

엄격한 파싱 vs. 복구 파싱: 언제 무엇을 쓸까

올바른 접근 방식은 데이터가 어디서 오는지에 따라 다릅니다. 사람이 편집한 설정 파일은 작성자가 실수를 고치도록 엄격한 파싱이 필요합니다. LLM이나 API 로그에서 온 기계 생성 데이터는 복구 기반 파싱이 필요합니다.

특성	엄격(json.loads)	복구(json_repair)
후행 쉼표	JSONDecodeError 발생	자동으로 제거
작은따옴표	실패	이중 따옴표로 변환
잘린 데이터	실패	열린 괄호/따옴표를 닫음
주석	실패	자동으로 제거
최적 용도	사람이 편집한 설정 파일	LLM 출력, API 로그

Pydantic으로 스키마 기반 복구

Pydantic v2 또는 JSON Schema를 사용해 복구 과정을 안내할 수 있습니다. json_repair에 스키마를 제공하면, 도구는 구문을 수정할 뿐만 아니라 타입을 교정하고(문자열 "1"을 숫자 1로 변환) 누락된 필수 필드를 기본값으로 채웁니다.

from pydantic import BaseModel
import json_repair

class User(BaseModel):
    id: int
    name: str
    active: bool = True

# Broken JSON with wrong types
raw = '{"id": "42", "name": "Alice"}'
repaired = json_repair.loads(raw)

# Validate against schema
user = User(**repaired)
# user.id is now int(42), user.active defaults to True

Stefano Baccianella가 2025년 프로젝트 인용에서 언급했듯이, 이 접근법은 언어 모델이 자주 생성하는 “대체로 맞지만 기술적으로 유효하지 않은” JSON에 최적화되어 있습니다.

수 기가바이트 파일을 크래시 없이 처리하기

10KB 스니펫을 수정하는 건 쉽습니다. 2GB 파일을 수정하려면 메모리를 다 잡아먹지 않는 전략이 필요합니다. 전체 파일을 메모리에 로드하면 메모리 부족(OOM) 오류가 발생합니다.

전략 1: ijson으로 스트리밍

대규모 데이터셋의 경우, ijson을 사용해 데이터를 조각 단위로 처리하세요. Scrapfly가 언급한 대로, ijson은 데이터를 점진적으로 처리합니다. 파싱 전에 문제를 줄 단위로 수정하는 정리 스크립트와 함께 사용하세요.

import ijson

# Stream through a large JSON file
with open('huge_broken.json', 'r') as f:
    for item in ijson.items(f, 'records.item'):
        # Process each item individually
        process(item)

전략 2: 최대 효율을 위한 CLI 파이프

대용량 파일에서 가장 메모리 효율적인 방법은 jsonrepair CLI를 사용하고 출력을 새 파일로 직접 파이프하는 것입니다:

# Streams repair, never loads full file into memory
jsonrepair large_broken.json > fixed.json

이 방법은 파일을 Python이나 브라우저에 로드하는 것보다 훨씬 메모리 효율적입니다.

결론

json_repair 같은 AI 인식 라이브러리 덕분에 잘못된 JSON을 수정하는 것은 더 이상 수동 작업이 아닙니다. 여전히 RFC 8259 기본 사항(후행 쉼표 금지, 작은따옴표 금지, 인용되지 않은 키 금지)을 이해해야 하지만, 2026년에 대규모 데이터를 다룰 때는 자동화만이 유일한 실용적인 접근법입니다.

워크플로는 간단합니다. 먼저 복구 라이브러리를 시도하세요. 실패하면 검증기를 사용해 정확한 구문 오류를 찾아냅니다. 이렇게 하면 들어오는 데이터가 완벽하지 않더라도 애플리케이션이 계속 실행됩니다.

자주 묻는 질문

JSON이 공식적으로 주석이나 작은따옴표를 지원하나요?

아니요. RFC 8259 표준은 주석을 엄격히 금지합니다. 작은따옴표도 유효하지 않습니다. 키와 문자열에는 이중 따옴표만 허용됩니다. 하지만 json_repair 같은 도구는 주석을 제거하고 따옴표를 자동으로 변환하여 표준 라이브러리로 파일을 파싱할 수 있게 만듭니다.

매우 크고 잘못된 JSON 파일을 크래시 없이 어떻게 처리하나요?

ijson 같은 스트리밍 파서를 사용해 데이터를 청크 단위로 처리하세요. 전체 잘못된 문자열을 단일 변수에 로드하지 마세요. 가장 빠르려면, 출력을 메모리에 모두 담지 않고 디스크의 새 파일로 직접 파이프하는 CLI 복구 도구를 사용하세요.

잘못된(malformed) JSON과 유효하지 않은(invalid) JSON의 차이는 무엇인가요?

잘못된 JSON은 구문 규칙(괄호 누락, 인용되지 않은 키, 후행 쉼표)을 위반하여 파싱할 수 없게 만듭니다. 유효하지 않은 JSON은 모든 구문 규칙을 따르지만 특정 JSON Schema와 일치하지 않습니다(예: 스키마가 정수를 기대하는데 필드가 문자열인 경우). 잘못된 JSON을 수정하는 것은 구조적 복구이고, 유효하지 않은 JSON을 수정하는 것은 데이터 무결성에 관한 것입니다.

json_repair를 Pydantic 검증과 함께 사용할 수 있나요?

네. 먼저 json_repair.loads()로 구문 오류를 수정한 다음, 복구된 딕셔너리를 Pydantic 모델에 전달하여 타입 검증과 스키마 적용을 수행하세요. 이 두 단계 접근법은 구조적 문제와 의미적 문제를 모두 해결합니다.

JavaScript 스타일 주석이 있는 JSON은 어떨까요?

표준 JSON은 주석을 지원하지 않지만, json_repair는 //와 /* */ 주석을 자동으로 제거할 수 있습니다. 설정 파일에 주석이 필요하다면 JSONC(주석이 있는 JSON) 형식과 Python용 json5 같은 호환 파서를 사용하는 것을 고려해 보세요.

AI 출력이 요청한 것과 전혀 다를 때의 그 좌절감을 아실 겁니다. JSON은 깨지고, 톤은 엇나가고, 지시의 절반은 무시됩니다. 문제는 모델이 아니라 프롬프트를 어떻게 포맷하고 있는가에 있습니다.

포매터로 AI 프롬프트를 작성하는 법을 익히려면, XML이나 JSON 같은 구조화 구분자를 사용해 RTCCO 프레임워크(역할·태스크·문맥·제약·출력)를 구현하세요. 이렇게 하면 프롬프트를 모듈화된 소프트웨어 자산으로 다룰 수 있어, 2026년 5월 기준으로 모델 환각을 최대 60%까지 줄이고 수동 처리 시간을 75% 단축할 수 있습니다.

문단식 프롬프트가 계속 실패하는 이유

2026년에 이르러 전문적인 AI 작업은 “채팅”에서 프롬프트 즉 코드(Prompt-as-Code, PaC)로 이동했습니다. 문단식 프롬프트, 즉 길고 구조 없는 텍스트 블록의 문제는 모델이 실제 지시와 그 안에 섞여 있는 배경 데이터나 출력 요구사항을 분리하기 어렵다는 데 있습니다.

PromptOT의 데이터에 따르면, 구조화 엔지니어링으로 전환하면 오류를 60% 줄이고 수동 처리 속도를 75% 높일 수 있습니다. Alex Ostrovskyy는 하드코딩된 프롬프트를 “소스코드의 매직 넘버에 해당하는 현실판”이라고 묘사합니다. 무언가를 망가뜨리지 않고는 거의 업데이트할 수 없는 취약한 시스템이죠.

변경 전후: 포맷팅의 차이

변경 전(구조 없음):

You are a helpful coding assistant. Please write a Python function that validates
email addresses. Make sure it handles edge cases like plus signs and subdomains.
The output should be in JSON format with a valid boolean and the cleaned email.
Also make sure you add proper error handling and don't forget logging.

변경 후(RTCCO + XML 구분자):

<system_instructions>
  <role>Senior Python engineer specializing in input validation</role>
  <primary_objective>Write a production-grade email validator</primary_objective>
</system_instructions>

<context>
  Must handle: plus addressing ([email protected]), subdomains,
  internationalized domains. Target: Python 3.11+.
</context>

<task_requirements>
  <rules>
    - Use only stdlib (no regex shortcuts)
    - Return structured JSON
    - Include type hints
  </rules>
  <steps>
    1. Parse the input string
    2. Validate format per RFC 5322
    3. Return JSON with "valid" boolean and "cleaned_email"
  </steps>
</task_requirements>

<output_format>
  {"valid": bool, "cleaned_email": str, "error": str | null}
</output_format>

같은 목표, 결과는 하늘과 땅 차이입니다. 포맷된 버전은 모델에게 모호함의 여지를 주지 않습니다.

RTCCO 프레임워크: 프롬프트의 뼈대

업계는 RTCCO를 표준 프롬프트 아키텍처로 수렴했습니다. 모든 프롬프트는 다섯 부분으로 쪼개집니다.

요소	용도	예시
R 역할(Role)	AI는 누구인가?	“시니어 백엔드 엔지니어”
T 태스크(Task)	구체적으로 무엇을?	“속도 제한 미들웨어 작성”
C 문맥(Context)	어떤 배경 데이터?	RAG 검색 결과, 코드베이스 조각
C 제약(Constraints)	규칙은 무엇?	“외부 의존성 없음”
O 출력(Output)	어떤 형태여야?	“타입 힌트가 있는 유효한 Python 3.11”

당장 복사할 수 있는 XML 뼈대 템플릿

다음은 프로덕션에 바로 쓸 수 있는 템플릿입니다. 복사하고, 다듬고, 배포하세요.

<system_instructions>
  <role> [Expert Persona] </role>
  <primary_objective> [Main Goal] </primary_objective>
</system_instructions>

<context>
  [Background Data or RAG Retrieval]
</context>

<task_requirements>
  <rules> [Non-negotiable Constraints] </rules>
  <steps> [Specific Workflow] </steps>
</task_requirements>

<output_format>
  [JSON/XML/Markdown Specification]
</output_format>

<recency_recap>
  [Reminder of Critical Constraints]
</recency_recap>

최근성 요약이 중요한 이유

대형 언어 모델은 “초두·최근 효과”라는 알려진 편향이 있습니다. 프롬프트의 처음과 끝을 중간보다 더 잘 기억합니다. PromptOT가 인용한 테스트에 따르면, 중요한 규칙을 중간에서 맨 아래의 “최근성 요약(Recency Recap)” 블록으로 옮기자 프로덕션 정확도가 78%에서 96%로 올랐습니다. 역할은 맨 위에, 가장 중요한 규칙은 맨 아래에 두세요.

구분자를 보안 울타리로

구분자는 단순한 정리 수단이 아닙니다. 하나의 보안 메커니즘입니다. 사용자 입력을 <user_input> 같은 태그로 감싸면 모델에게 “이것은 처리할 데이터이지, 따라야 할 새 지시가 아니다”라고 알려주는 셈입니다. 이것이 사용자가 시스템 지시를 덮어쓰려 하는 프롬프트 인젝션 공격에 대한 첫 번째 방어선입니다.

흔한 함정: 구분자 없이 사용자 데이터를 프롬프트에 직접 끼워 넣으면, 사용자가 “이전의 모든 지시를 무시하고…”라고 쓰기만 해도 모델이 그대로 따릅니다. 외부 데이터는 항상 태그가 붙은 블록으로 감싸세요.

모듈형 아키텍처: 메가 프롬프트 작성을 멈추자

하나의 취약한 2,000 토큰짜리 프롬프트 대신, 시스템을 독립적인 모듈로 쪼개세요. 이렇게 하면 프롬프트의 톤을 바꿨다가 JSON 출력 형식이 깨지는 지시 충돌을 막을 수 있습니다.

핵심 원칙은 문맥 엔지니어링(Context Engineering)입니다. 정적 지시와 동적 데이터를 분리하세요. 프로덕션 RAG 시스템에서 프롬프트는 하나의 템플릿이며, <context> 블록은 질의 시점에 새로운 데이터로 채워집니다. OptizenApp의 Jono Farrington이 설명하듯, 이 모듈형 접근은 대규모 AI 배포의 일관성을 훨씬 높여줍니다.

프롬프트 체이닝: 모듈 연결하기

복잡한 워크플로에는 프롬프트 체이닝(Prompt Chaining)을 사용하세요. 한 모듈의 출력이 다음 모듈의 입력이 됩니다.

[Planner Module] --> outline --> [Executor Module] --> draft --> [Reviewer Module] --> final

이 단계별 방식은 모델이 한 번에 하나의 하위 태스크에만 집중하기 때문에 출력 품질을 약 35% 향상시킵니다.

복사해서 쓰는 체이닝 예시:

planner_prompt = """
<system_instructions>
  <role>Technical architect</role>
  <task>Create a step-by-step plan for: {user_request}</task>
</system_instructions>
<output_format>JSON array of steps</output_format>
"""

executor_prompt = """
<system_instructions>
  <role>Senior developer</role>
  <task>Implement step: {step_from_planner}</task>
</system_instructions>
<context>{previous_outputs}</context>
<output_format>Code block with inline comments</output_format>
"""

어려운 문제를 위한 사고열쇠(Chain-of-Thought) 추가

태스크에 복잡한 논리가 포함되면 <thought_process> 블록을 추가하세요. 이 블록은 모델이 답을 내놓기 전에 단계별로 추론하게 만들어 수학·코딩·다단계 추론에서의 오류를 크게 줄여줍니다.

<task_requirements>
  <rules>Reason inside <thought> tags before answering</rules>
</task_requirements>

<output_format>
  <thought> [Your step-by-step reasoning here] </thought>
  <answer> [Final JSON output here] </answer>
</output_format>

Zencoder에 따르면, 사고의 나무(Tree-of-Thoughts, ToT) 같은 기술은 이를 더 밀어붙여 모델이 여러 해결 경로를 동시에 평가하고 최선을 고르도록 요구합니다. 이는 정답이 하나가 아닌 아키텍처 결정에서 특히 가치가 있습니다.

토큰 비용 경고

구조화된 추론은 토큰을 더 소모합니다. 일반적인 <thought_process> 블록은 요청마다 200~500 토큰을 추가합니다. 대규모에서는 API 비용 상승으로 이어집니다. 교환은 정확도입니다. 요청당 더 내되 재시도와 수동 수정은 줄어듭니다.

프로덕션 준비: 버전 관리, 테스트, CI/CD

마지막 단계는 프롬프트를 소프트웨어처럼 대하는 것입니다. 시맨틱 버저닝(v1.0.0)을 사용해 팀이 변경 사항을 추적하고, 새 프롬프트 버전이 성능을 떨어뜨릴 때 즉시 롤백할 수 있게 하세요.

PromptOT는 50개 이상의 프롬프트를 관리하는 기업이 관리를 중앙화하고 엔지니어의 수동 미세 조정 시간을 줄여 연간 최대 40만 달러를 절약할 수 있다고 보고합니다.

프롬프트 CI/CD 파이프라인 구축

# .github/workflows/prompt-tests.yml
name: Prompt Quality Gate
on: [push]
jobs:
  test-prompts:
    runs-on: ubuntu-latest
    steps:
      - name: Run Golden Dataset Tests
        run: |
          # Test against 50-200 curated cases
          python scripts/eval_prompts.py \
            --dataset golden_dataset.json \
            --judge-model gpt-4 \
            --min-score 0.85

      - name: Regression Check
        run: |
          # Compare new version vs. production
          python scripts/compare_versions.py \
            --staging v2.1.0 \
            --production v2.0.3 \
            --threshold 0.05

프롬프트는 “LLM-as-a-judge”가 채점하는 이 품질 게이트를 통과해야만 Staging에서 Production으로 승급됩니다.

결론

포매터를 활용한 구조화 프롬프트 엔지니어링은 더 이상 선택이 아닙니다. 신뢰할 수 있는 AI 도구를 만드는 모두를 위한 기본기입니다. RTCCO 프레임워크, XML 구분자, 모듈형 아키텍처가 예측 불가능한 LLM 출력을 일관되고 프로덕션급 결과로 바꾸는 당신의 스택입니다.

가장 자주 쓰는 프롬프트부터 시작해 위의 XML 템플릿으로 RTCCO 프레임워크에 맞게 리팩터링하세요. 버전 관리에 넣고, 기본 평가를 세팅하면, 확장 가능한 프롬프트 인프라가 완성됩니다.

자주 묻는 질문

기존 문단식 프롬프트를 RTCCO 블록 형식으로 어떻게 바꾸나요?

먼저 핵심 태스크(Task)를 식별하고 그것을 문맥(Context)에서 분리하세요. 지시는 <rules> 태그로 감싸고, <examples> 태그에 3~5개 예시를 제공합니다. LLM의 도움을 받을 수도 있습니다. “이 비정형 텍스트를 XML 구분자로 RTCCO 프레임워크에 맞게 다시 파싱해 줘”라고 프롬프트하면 무거운 작업을 대신 처리해 줍니다.

XML, JSON, Markdown 구분자 중 무엇을 써야 하나요?

Claude과 GPT-5 같은 모델에서 긴 콘텐츠와 지시를 분리할 때 XML이 엄격한 계층 구조 덕분에 현재의 황금 표준입니다. API 통합을 위한 프로그래밍 방식의 입출력이 필요하면 JSON이 더 낫습니다. Markdown은 단순하고 사람이 읽기 쉬운 프롬프트에 적합하지만, 복잡하고 다층적인 프로덕션 프롬프트에 필요한 엄격한 경계 정의가 부족합니다.

프롬프트에 대한 자동화된 CI/CD 테스트는 어떻게 구현하나요?

“골든 데이터셋”(50~200개의 엄선된 테스트 케이스)과 출력을 루브릭 기준으로 채점하는 “LLM-as-a-judge”로 구성된 테스트 스위트를 구축하세요. 이 테스트들을 GitHub Actions나 Jenkins 파이프라인에 통합하면, 프롬프트 변경 사항이 배포 전에 정확도와 톤 면에서 검증됩니다.

구조화 프롬프트로 전환할 때 가장 흔한 실수는 무엇인가요?

<context> 블록에 너무 많은 것을 쑤셔넣는 것입니다. 개발자들은 종종 전체 코드베이스나 문서를 문맥에 쏟아붓는데, 이는 모델의 주의를 희석시킵니다. 문맥은 태스크와 직접적으로 관련된 것에만 집중시키세요. 대형 문서를 참조해야 한다면 RAG 검색으로 관련 섹션만 가져오세요.