원본 캡처

구조화 출력 + 프롬프팅 안티패턴 리서치 원본 — 2026-07-25

불변 캡처. 절대 편집하지 마라. 가공본은 위키 페이지에.

조사 방법

검색어

  1. OpenAI structured outputs JSON schema strict limitations recursion unsupported keywords
  2. Anthropic structured outputs output_config format json_schema tool use strict 2026
  3. prompt engineering anti-patterns reasoning models 2025 2026 don't force chain of thought
  4. "lost in the middle" long context LLM retrieval position 2024 2025 study
  5. Anthropic Claude prompt engineering positive instructions instead of negative "do this" not "don't" xml tags best practices
  6. Claude "extended thinking" prompting do not include "think step by step" official Anthropic reasoning tips don't force

WebFetch 로 실제로 열어본 URL (6개 성공, 1개 403)

  • [HIGH] https://platform.claude.com/docs/en/build-with-claude/structured-outputs (Anthropic 1차)
  • [HIGH] https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices (Anthropic 1차)
  • [MED] https://www.digitalapplied.com/blog/prompt-engineering-anti-patterns-10-mistakes-2026
  • [MED] https://sureprompts.com/blog/ai-reasoning-models-prompting-complete-guide-2026
  • [MED] https://atlan.com/know/llm/lost-in-the-middle-problem/
  • [MED] https://www.codewords.ai/blog/openai-structured-outputs-json-schema
  • (403 차단) https://openai.com/index/introducing-structured-outputs-in-the-api/ — 열지 못함. OpenAI 정밀 수치는 미확인 처리.

규격서 §7 (Anthropic first-party, claude-api 스킬) 도 기준으로 사용 — 웹과 충돌 시 §7 우선.

확인된 사실 [신뢰도]

A. Anthropic 구조화 출력 — output_config.format (JSON outputs)

  • [HIGH] 두 개의 상호보완 기능: JSON outputs (output_config.format) = Claude 응답 전체를 스키마에 맞춤 / Strict tool use (strict: true) = 툴 이름·입력 파라미터를 스키마에 맞춤. 한 요청에서 둘 다 조합 가능. (platform.claude.com/structured-outputs)
  • [HIGH] 구문: json {"output_config": {"format": {"type": "json_schema", "schema": {"type":"object","properties":{...}, "required":[...], "additionalProperties": false}}}} format 객체에 "type":"json_schema" 필수. 객체마다 additionalProperties:false 필수. 응답은 text content block 안에 스키마에 맞는 valid JSON.
  • [HIGH] 모델 지원 (Claude API GA): Claude 4.5 and later + Claude Mythos Preview. (즉 §7 현행 5세대 전부 + Sonnet/Opus 4.5 계열 포함). Bedrock/Vertex 는 지원 목록이 조금 다름 (Vertex 가 가장 넓음: Fable 5, Mythos 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5/4.6/4.5, Opus 4.5, Haiku 4.5).
  • [HIGH] 동작 원리 = grammar-constrained sampling (constrained decoding). 샘플링 시점에 문법으로 제약되어 스키마 위반이 원천 불가.
  • [HIGH] 이점: 항상 valid (JSON.parse 에러 없음), type safe, 재시도 불필요.
  • [HIGH] 문법 컴파일 & 캐싱: 첫 요청은 문법 컴파일로 추가 지연. 컴파일된 문법은 마지막 사용 후 24시간 캐시. 캐시 무효화 = JSON 스키마 구조 변경 / (두 기능 병용 시) 툴 셋 변경. name·description 만 바꾸면 무효화 안 됨.
  • [HIGH] 토큰 비용: 출력 형식 설명하는 시스템 프롬프트가 주입되어 input 토큰이 약간 증가. output_config.format 을 바꾸면 그 스레드의 prompt cache 가 무효화됨.
  • [HIGH] 미지원 기능 사용 시 400 에러 (상세 포함).

B. Anthropic JSON Schema 제약 (지원/미지원) [HIGH, platform.claude.com]

지원: - 기본 타입: object, array, string, integer, number, boolean, null - enum (문자열/숫자/bool/null 만 — 복합 타입 불가), const - anyOf, allOf (제약 있음; allOf + $ref 는 미지원) - $ref, $def, definitions (단 external $ref (http://...) 미지원) - default (지원 타입 전부) - required, additionalProperties (반드시 false) - String formats: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid - Array minItems (값 0 과 1 만 지원)

미지원 (사용 시 400): - 재귀(recursive) 스키마 - enum 안의 복합 타입 - external $ref - 수치 제약: minimum, maximum, multipleOf - 문자열 제약: minLength, maxLength - Array 제약: minItems 의 0/1 외 값 전부, maxItems 등 - additionalProperties 를 false 외 값으로

C. Anthropic Strict tool use [HIGH]

  • [HIGH] 툴 정의에 strict: true (top-level 필드). input_schema 는 JSON outputs 와 동일한 스키마 제약 사용. required + additionalProperties:false 필요.
  • [HIGH] strict 없으면 Claude 가 enum 자리에 문자열을, 2 대신 "2" 를 넣는 등 타입 불일치 가능. strict 가 타입·이름 정확성 보장.
  • [HIGH] §7 재확인: strict:true 는 top-level 필드지 tool_choice 아님. 스키마에 additionalProperties:false + required 필수.

D. JSON outputs vs Strict tool use vs 언제 뭘 [HIGH]

JSON Outputs Strict Tool Use
제어 대상 Claude의 응답 형식 툴 파라미터 검증
용도 구조화된 최종 응답, 데이터 추출 신뢰성 있는 툴 호출
병용 같은 요청에서 가능 같은 요청에서 가능
  • 병용: agentic 워크플로우에서 "파라미터 보장된 툴 호출 + 구조화된 최종 JSON" 둘 다 필요할 때.
  • XML 태그 방식(§F 참조)은 constrained decoding 이 아니라 소프트 스티어링 — 스키마 강제가 필요 없거나 자유 산문 + 일부 구조 혼합일 때.

E. SDK 헬퍼 [HIGH]

  • Python: client.messages.parse(..., output_format=PydanticModel) → response.parsed_output
  • TypeScript: client.messages.parse({ output_config: { format: zodOutputFormat(Schema) }}) → response.parsed_output
  • Java outputConfig(Class<T>), Ruby output_config:{format: Model}, PHP StructuredOutputModel 인터페이스.
  • SDK 는 편의상 output_format 를 여전히 받아 내부 변환.

F. 마이그레이션 (베타→GA) [HIGH]

  • 구 파라미터 output_format → output_config.format 로 이동.
  • 구 베타 헤더 structured-outputs-2025-11-13 더이상 불필요. 구 헤더·파라미터는 전환기간 동안 계속 동작.
  • §7 재확인: top-level output_format 은 deprecated. Python 은 messages.parse(output_format=Pydantic) 권장.

G. OpenAI 구조화 출력 (비교용) [MED, aggregator]

  • [MED] response_format 에 json_schema + strict: true. 함수 호출도 strict 모드 지원.
  • [MED] 모든 필드가 required 여야 함. optional 필드는 anyOf 에 null 타입 유니온으로 우회.
  • [MED] additionalProperties: false 를 모든 객체에 필수.
  • [MED] 최대 5단계 중첩(nesting) 지원.
  • [MED] 미강제 키워드: pattern, minLength, minimum, maximum, format 등 — 모델이 강제하지 않음 (스키마는 구조만 제약, 내용은 앱단 검증 필요).
  • [MED] 지원 타입: string, number, integer, boolean, array, object, null.
  • [MED] root object 는 anyOf 타입 불가 (검색 결과, 미개봉 확인).
  • [MED] OpenAI 도 일부 재귀 스키마는 지원 (root schema 를 참조하는 CFG 방식으로 UI 트리 등). ← Anthropic 은 재귀 전면 미지원인 것과 대비. 단 이 재귀 지원은 aggregator 서술이라 낮은 신뢰.
  • 핵심 대비: Anthropic = 재귀 완전 미지원 / OpenAI = 제한적 재귀 가능. 양쪽 다 수치·문자열 길이 제약은 강제 안 함.

H. 프롬프팅 안티패턴 — Anthropic 1차 [HIGH]

  • [HIGH] 오버트리거 (핵심 사실): "Claude Opus 4.5 and Claude Opus 4.6 are also more responsive to the system prompt than previous models. If your prompts were designed to reduce undertriggering on tools or skills, these models may now overtrigger. The fix is to dial back any aggressive language. Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'." (best-practices 490행)
  • [HIGH] "Remove over-prompting. Tools that undertriggered in previous models are likely to trigger appropriately now. Instructions like 'If in doubt, use [tool]' will cause overtriggering." (527행)
  • [HIGH] 긍정 지시 > 부정 지시: "Tell Claude what to do instead of what not to do." 예: "Do not use markdown in your response" (X) → "Your response should be composed of smoothly flowing prose paragraphs." (O). (344–347행)
  • [HIGH] XML 태그: 지시/컨텍스트/예시/입력이 섞일 때 각각을 <instructions> <context> <input> 등 태그로 감싸면 오해석 감소. 예시는 <example> (복수 <examples>) 로 감싸 지시와 구분. 다문서는 <document> + <document_content> + <source>.
  • [HIGH] few-shot 사용법: 3–5개 예시가 최적. 형식·톤·구조 스티어링에 가장 신뢰성 높은 수단. 단 예시는 다양·연관되어야 함.
  • [HIGH] thinking 모델에는 고수준 지시: "Prefer general instructions over prescriptive steps. A prompt like 'think thoroughly' often produces better reasoning than a hand-written step-by-step plan. Claude's reasoning frequently exceeds what a human would prescribe." (776행)
  • [HIGH] manual CoT 는 fallback: "Manual chain-of-thought (CoT) prompting as a fallback. When thinking is off, you can still encourage step-by-step reasoning... On Claude Opus 5, prefer keeping thinking enabled at a lower effort level instead: with thinking disabled, the model can occasionally emit internal XML tags into its visible output." (778행) → 추론 켜져 있으면 수동 CoT 지시 불필요·역효과.
  • [HIGH] over-verification: "Claude Opus 5... verifies its own work well without explicit instruction, and verification instructions carried over from prompts tuned for earlier models can cause over-verification, adding tokens and latency. When migrating to Claude Opus 5, remove these instructions." (779행)
  • [HIGH] adaptive thinking: 4.6+ 및 Mythos Preview 는 thinking:{type:"adaptive"}. Fable 5/Mythos 5 는 always-on adaptive 가 유일 모드. effort + 쿼리 복잡도로 스스로 사고량 조절. "In internal evaluations, adaptive thinking reliably drives better performance than extended thinking." (545행)
  • [HIGH] conflicting instructions 피하기 / 하나 골라라: "If you're weighing two approaches, pick one and see it [through]." (535행 인근) — 모순되는 지시 지양.
  • [HIGH] prefill 대체: assistant prefill 로 JSON 강제하던 패턴 → 이제 structured outputs / tool calling / XML 태그로. (§7: 현행 모델 prefill 은 400)

I. 프롬프팅 안티패턴 — aggregator [MED]

digitalapplied "10 mistakes 2026" (MED): - [MED] Few-Shot Pollution: 예시가 현재 지시와 모순 → 모델이 옛 예시를 따름. "single most common silent-failure source." Fix: PR마다 예시-지시 동기화. - [MED] Instruction Stacking: 규칙 8–10개 넘으면 정확도 5–10점 하락 (모델이 어떤 규칙이 중요한지 triage). Fix: 3–4개 원칙문으로 압축, 엣지케이스는 예시로. - [MED] Format Via Example: 형식을 예시로만 보여주면 구조가 다른 입력에서 파서 깨짐. Fix: 스키마를 지시에 명시 + 프로바이더 structured output. - [MED] Persona Stuffing: "world-class expert" 류 페르소나가 기술 작업에서 스타일 노이즈만 추가, 정확도·지시준수 저하. Fix: 스타일 중심 창작에만. - [MED] Over-Correction: 나쁜 출력 하나에 제약을 과하게 걸어 정상 출력 10개를 목조름. Fix: eval 케이스 먼저 쓰고 필요한 만큼만 제약. - [MED] Missing Output Schema / Prompt-Response Coupling: 다운스트림이 "answer is X" 같은 문구에 의존 → 모델 업그레이드로 문구 바뀌면 파서 깨짐. Fix: 스키마 필드만 파싱, 자유문 파싱 금지. - [MED] Ungrounded Chain-of-Thought: 실제 데이터에 앵커 안 된 그럴듯한 추론 단계 지어냄 → 환각 결론. Fix: 검색 컨텍스트에 CoT 그라운딩하거나 제거. - [MED] Silent Drift / Model-Version Drift: 측정 없으면 프롬프트가 몇 달에 걸쳐 조용히 썩음. Fix: 일일 eval + 회귀 알림, 업그레이드 전 스위트 실행.

sureprompts 추론모델 (MED): - [MED] manual CoT 중복: "Asking a reasoning model to 'think step by step' in the visible response either duplicates the work — once in hidden thinking tokens, once in narrated output, doubling cost without improving quality." 추론모델 프롬프트에서 이 문구 완전 삭제 권장. - [MED] few-shot 가 추론 저해: "the model anchors on your specific solution path and reduces solution diversity." few-shot 은 패턴매칭·분류용으로만, 추론 문제엔 스크래치부터 생성하게. - [MED] persona/emotional primer: "Detailed personas underperform direct task framing, emotional primers do nothing measurable, and 'if you're unsure, say so' is now a tax because reasoning models self-flag uncertainty inside the thinking phase." 2023 트릭(페르소나 스택, take-a-deep-breath, confidence-eliciting)은 프론티어 추론모델에서 무효/역효과. - [MED] over-prompting/procedure script: "A prompt that reads like a procedure manual replaces the model's reasoning with yours, and the model's reasoning is usually better than the script you would write." goal+constraint 만 주고 경로는 모델에게.

J. Lost-in-the-middle / 컨텍스트 오염 [MED]

  • [MED] U자 정확도 곡선: 컨텍스트 시작/끝 정보는 신뢰성 있게 쓰지만 중간은 성능 저하. 원 연구 Liu et al., TACL 2024 (multi-document QA + key-value retrieval). 중간 위치 시 정확도 >30% 하락. GPT-3.5/GPT-4/Claude 1.3/LongChat-13B/MPT-30B/Cohere Command 6개 모델군에서 재현.
  • [MED] 아키텍처 원인 후보: RoPE long-term decay — 먼 토큰쌍 dot-product 유사도 감소 → 중간 컨텍스트 attention 가중치 하락.
  • [MED] 신형 모델도 완전 해결 아님: Chroma 2025 "context rot" 리포트 (18개 모델: GPT-4.1, Claude 4, Gemini 2.5, Qwen3) — "newer models still do not use context uniformly, and performance grows less reliable as input length grows." effective context 가 advertised max 대비 최대 99% 미달인 경우도.
  • [MED] 부분 개선 사례: Gemini 2.5 Flash 는 단순 factoid needle-in-haystack 은 위치 무관 고정확도.
  • [HIGH] Anthropic 1차 정합: "Put longform data at the top: Place your long documents and inputs near the top of your prompt, above your query, instructions, and examples. This improves performance across all models." (best-practices 247행)
  • [MED] 완화책: 중요 지시/정책은 시작(또는 끝) 근처 배치, query rewriting·reranking·dedup·filtering, context compression.

엇갈리거나 미확인

  • OpenAI 정밀 수치 미확인: openai.com 공식 페이지가 403 으로 열리지 않음. 최대 프로퍼티 수(흔히 인용되는 5000), 총 스키마 크기(120,000자), enum 최대 1000개 등은 1차 확인 실패 → [unverified]. 확인된 건 "5단계 중첩", "root anyOf 불가", "모든 필드 required", "additionalProperties:false"뿐이며 이마저 aggregator MED.
  • OpenAI 재귀 지원 여부: 검색 요약은 "일부 재귀 CFG 로 지원"이라 하고 codewords 는 "명시 안 함". 엇갈림 → OpenAI 재귀는 미확정.
  • Anthropic strict tool use 가 지원되는 정확한 모델 하한: 구조화 출력 전체가 "Claude 4.5 and later"라고만 명시. strict tool use 만 따로 다른 하한인지는 미확인 (같다고 가정).
  • "8–10 규칙 후 5–10점 하락", ">30% 중간 하락", "24시간 문법 캐시" 같은 수치: 각각 aggregator 또는 벤치성 — 정확 재현 조건은 미확인. 위키에서는 정성 서술 권장(규격 §5: 벤치 점수 인용 금지).
  • XML 태그가 "학습 데이터에 많았다"는 주장: aggregator 다수 반복하나 Anthropic 공식은 "helps Claude parse"까지만 명시. "trained heavily on XML" 은 [MED] 취급.

원문 발췌 (load-bearing 인용)

Anthropic 오버트리거 (best-practices 490행, HIGH):

"these models may now overtrigger. The fix is to dial back any aggressive language. Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'."

Anthropic over-prompting (527행, HIGH):

"Remove over-prompting. ... Instructions like 'If in doubt, use [tool]' will cause overtriggering."

Anthropic 긍정 지시 (344–347행, HIGH):

"Tell Claude what to do instead of what not to do. Instead of: 'Do not use markdown in your response' → Try: 'Your response should be composed of smoothly flowing prose paragraphs.'"

Anthropic thinking 고수준 지시 (776행, HIGH):

"Prefer general instructions over prescriptive steps. A prompt like 'think thoroughly' often produces better reasoning than a hand-written step-by-step plan. Claude's reasoning frequently exceeds what a human would prescribe."

Anthropic manual CoT fallback (778행, HIGH):

"Manual chain-of-thought (CoT) prompting as a fallback. When thinking is off, you can still encourage step-by-step reasoning... On Claude Opus 5, prefer keeping thinking enabled at a lower effort level instead: with thinking disabled, the model can occasionally emit internal XML tags into its visible output."

Anthropic 구조화 출력 미지원 목록 (structured-outputs, HIGH):

"NOT Supported: Recursive schemas; Complex types within enums; External $ref; Numerical constraints (minimum, maximum, multipleOf); String constraints (minLength, maxLength); Array constraints beyond minItems of 0 or 1; additionalProperties set to anything other than false. Using unsupported features returns a 400 error."

sureprompts manual CoT 중복 (MED):

"Asking a reasoning model to 'think step by step' in the visible response either duplicates the work — once in hidden thinking tokens, once in narrated output, doubling cost without improving quality."

Liu et al. lost-in-the-middle (atlan/search, MED):

"performance is often highest when relevant information appears at the beginning or end, and performance plummeted when the same information is present in the middle." (TACL 2024, U-shaped, >30% drop, 6 model families)