Claude API 프롬프트 엔지니어링: XML 태그 구조화 실전 가이드

앤트로픽 프롬프트 엔지니어링의 핵심은 XML 태그로 입력을 구조화하는 것입니다. <context>, <instructions>, <examples>처럼 블록을 분리하면 Claude는 각 영역의 역할을 명확히 파악해 응답 정확도가 높아집니다. Claude 특유의 훈련 구조에서 나온 방식이며, 앤트로픽 공식 가이드도 이 기법을 맨 앞에 소개합니다. 태그 없이 긴 지시문을 넣으면 지시 항목이 뒤섞이는 오류가 자주 발생합니다.

앤트로픽 프롬프트 엔지니어링이 GPT 방식과 어떻게 다른가?

GPT 계열 모델은 자연어 지시문을 그대로 처리하도록 훈련되었습니다. 반면 Claude는 XML 태그를 포함한 구조화된 텍스트를 대규모로 학습했습니다. 이 훈련 차이가 프롬프트 설계 방식을 근본적으로 갈라놓습니다.

GPT에서 효과적인 패턴, 예컨대 "당신은 시니어 개발자입니다. 다음 코드를 리뷰해 주세요. 코드: …" 형식은 Claude에서도 작동하지만 최적의 방식은 아닙니다. Claude에게는 이렇게 씁니다.

당신은 시니어 개발자입니다.

<task>
다음 코드를 리뷰하세요.
</task>

<code language="python">
def process_order(user_id, items):
    ...
</code>

<output_format>
버그, 성능 이슈, 개선 제안 순서로 작성하세요.
</output_format>

두 방식이 표면상 비슷해 보여도, 실제 응답 품질과 파싱 안정성에서 차이가 납니다. 특히 지시 항목이 여럿일 때, 태그가 없으면 Claude가 어느 부분을 배경 정보로 볼지, 어느 부분을 실행 지시로 볼지 혼동하는 경우가 생깁니다. 모델이 지시와 데이터를 경계 없이 처리하기 때문입니다.

GPT 방식으로 짠 프롬프트를 Claude에 그대로 이식하면 일관성이 떨어지는 이유가 여기 있습니다. Claude는 XML 태그를 "의미 구분자"로, GPT는 "읽어야 할 텍스트"로 처리합니다.

XML 태그는 왜 Claude에게만 특히 효과적인가?

앤트로픽은 Claude를 훈련할 때 구조화된 마크업 언어를 포함한 다양한 문서 형식을 학습 데이터에 사용했습니다. RLHF(인간 피드백 강화학습) 과정에서도 XML 태그 기반 프롬프트가 대거 활용되었습니다. 이로 인해 Claude는 XML 태그를 단순 텍스트로 처리하지 않고 의미 경계로 인식합니다.

<context> 태그 안의 내용은 "배경 정보", <instructions> 안의 내용은 "실행해야 할 지시"로 모델 내부에서 다르게 처리됩니다. 이는 모델 가중치 수준의 차이이기 때문에, 단순히 마크다운 볼드(**)나 줄바꿈으로는 동일한 효과를 내기 어렵습니다.

반면 GPT-4나 Gemini는 XML 태그를 특별히 인식하도록 훈련했다는 공개된 기록이 없습니다. 같은 태그를 써도 Claude만큼 일관된 효과를 내지 못하는 이유입니다. 앤트로픽 프롬프트 엔지니어링 기법을 GPT에 그대로 이식하면 기대 이하의 결과가 나오는 경우가 많습니다.

어떤 태그를 언제 써야 하는가?

태그 이름 자체에는 제약이 없습니다. 다만 역할이 명확한 이름을 쓸수록 Claude의 이해도가 높아집니다. 실무에서 검증된 태그와 사용 기준을 정리합니다.

• <context>: 태스크를 수행하는 데 필요한 배경 정보를 담습니다. 사용자 프로필, 시스템 상태, 이전 대화 요약이 여기에 들어갑니다. 지시문과 분리하면 Claude가 배경과 명령을 혼동하지 않습니다.
• <instructions>: 핵심 실행 지시를 담습니다. 간결하게 씁니다. 여러 단계가 있다면 내부에 <step>을 중첩해 구조화할 수 있습니다.
• <examples>: Few-shot 예시를 담습니다. 예시가 여럿이면 <example>을 반복해 각각 감싸면 Claude가 패턴을 더 정확히 추출합니다.
• <output_format>: 원하는 출력 형식을 명세합니다. JSON 스키마, 마크다운 구조, 특정 섹션 이름을 여기에 기술합니다. 이 태그가 있으면 파싱 오류가 현저히 줄어듭니다.
• <constraints>: 하지 말아야 할 것의 목록을 담습니다. 금지 항목을 instructions에 섞으면 모델이 잊어버리기 쉽습니다. 별도 태그로 분리하면 준수율이 높아집니다.
• <document> 또는 <input>: 처리할 원문 데이터를 담습니다. 태그 바깥의 지시문과 경계가 명확해져 원문이 지시로 오인되는 "경계 오류"를 방지합니다.

태그 중첩도 허용됩니다. <examples><example>...</example><example>...</example></examples>처럼 쓰면 복수 예시를 깔끔하게 처리할 수 있습니다. 태그명은 팀 내에서 통일해 사용하면 온보딩 비용도 줄어듭니다.

시스템 메시지와 사용자 메시지를 어떻게 나눠야 하는가?

Claude API는 system과 messages 파라미터를 분리합니다. 실무에서 두 영역을 혼용하는 경우가 많은데, 이를 제대로 구분하면 비용과 품질 양쪽에서 이점이 생깁니다.

시스템 메시지에는 요청마다 변하지 않는 행동 지침을 담습니다. 페르소나 정의, 항상 지켜야 할 응답 형식, 전역 제약 조건이 여기에 속합니다.

사용자 메시지에는 요청별 변수 데이터를 담습니다. 처리할 문서, 사용자 입력, 동적으로 채워지는 컨텍스트가 여기에 해당합니다.

이 구분이 중요한 이유는 두 가지입니다. 첫째, 시스템 메시지를 요청마다 동일하게 유지하면 앤트로픽의 프롬프트 캐싱 기능을 활용해 입력 토큰 비용을 최대 90%까지 줄일 수 있습니다. 프롬프트 캐싱은 Claude Opus 4.8, Sonnet 4.6 등 현행 모델에서 모두 지원됩니다. 둘째, 멀티턴 대화에서 지시 항목이 희석되지 않아 응답 품질이 안정적으로 유지됩니다.

권장 구조는 다음과 같습니다.

# system 파라미터 (변하지 않는 지침)
당신은 한국어 기술 문서를 영어로 번역하는 전문 번역가입니다.

<global_rules>
- 전문 용어는 원문을 괄호 안에 병기합니다.
- 문체는 기술 문서 표준 영어를 사용합니다.
</global_rules>

# user 메시지 (요청별 데이터)
<document>
{{번역할 원문}}
</document>

<output_format>
번역문만 출력하세요. 설명이나 주석 없이.
</output_format>

XML 태그로 출력 형식을 제어하면 파싱 오류가 얼마나 줄어드는가?

Claude API에서 구조화된 출력을 받아 파싱하는 코드를 작성할 때 가장 흔한 문제는 모델이 예상치 못한 형식을 출력하는 것입니다. JSON이 필요한 경우 마크다운 코드 블록으로 감싸거나, 앞에 설명 문장을 붙이거나, 필드명을 변형하는 경우가 생깁니다.

두 가지 방법으로 이 문제를 잡을 수 있습니다.

첫째, <output_format> 태그로 출력 명세를 구체적으로 기술합니다. "JSON으로 출력하세요"라고만 쓰는 것보다, 원하는 스키마를 직접 명시할 때 준수율이 높아집니다.

<output_format>
다음 JSON 형식만 출력하세요. 코드 블록이나 설명 없이.

{
  "category": "billing|technical|general",
  "confidence": 0.0~1.0,
  "reason": "string"
}
</output_format>

둘째, 앤트로픽이 제공하는 Structured Outputs 기능을 활용합니다. output_config 파라미터에 JSON 스키마를 전달하면 API 수준에서 출력 형식을 강제합니다. Python SDK에서는 Pydantic 모델로도 적용할 수 있습니다.

from pydantic import BaseModel

class ClassificationResult(BaseModel):
    category: str
    confidence: float
    reason: str

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=512,
    messages=[{"role": "user", "content": prompt}],
    output_format=ClassificationResult,
)
result = response.parsed_output  # ClassificationResult 인스턴스

두 방법을 함께 쓰면 코드 블록 감싸기, 설명 문장 추가, 필드명 변형 같은 파싱 오류를 사전에 거의 완전히 차단할 수 있습니다. Structured Outputs는 Claude Opus 4.8, Sonnet 4.6, Haiku 4.5에서 모두 지원됩니다.

문서 분류·코드 리뷰·요약, 바로 복사해 쓸 수 있는 템플릿은?

아래 세 템플릿은 복사해 바로 쓸 수 있습니다. {{변수}} 부분만 실제 데이터로 교체하면 됩니다.

패턴 1: 문서 분류

<context>
고객 문의 메시지를 분류하는 시스템입니다. 결과는 CRM에 자동 저장됩니다.
</context>

<categories>
- billing: 청구서, 결제, 환불 관련
- technical: 버그, 기능 오류, 설치 문제
- general: 그 외 일반 문의
</categories>

<input>
{{고객 메시지}}
</input>

<output_format>
{"category": "billing|technical|general", "confidence": 0.0~1.0}
</output_format>

패턴 2: 코드 리뷰

<task>
아래 Python 코드를 시니어 개발자 관점에서 리뷰하세요.
</task>

<code language="python">
{{코드}}
</code>

<review_criteria>
1. 보안 취약점 (SQL 인젝션, 인증 우회 등)
2. 성능 병목 (N+1 쿼리, 불필요한 루프 등)
3. 코드 품질 (네이밍, 가독성, 모듈화)
</review_criteria>

<output_format>
각 기준별로 이슈가 있으면 설명과 수정 예시를 작성하세요.
이슈가 없으면 "이상 없음"으로 표기합니다.
</output_format>

패턴 3: 임원 보고용 요약

<context>
이 요약은 임원 보고서에 포함됩니다. 독자는 기술 배경이 없습니다.
</context>

<document>
{{원문}}
</document>

<instructions>
3~5개 핵심 포인트로 요약하세요.
</instructions>

<constraints>
- 기술 용어를 사용하지 마세요.
- 각 포인트는 두 문장을 넘지 않습니다.
- 주관적 평가 없이 사실만 기술합니다.
</constraints>

<output_format>
• 포인트 1
• 포인트 2
(3~5개)
</output_format>

세 템플릿을 팀 내 공유 파일로 저장해 두면, 새로운 기능을 개발할 때 이 구조를 베이스로 빠르게 확장할 수 있습니다. 시스템 메시지에 <global_rules>를 고정하고 사용자 메시지에 태스크별 태그를 조합하는 방식으로 운영하면 프롬프트 캐싱 효과도 함께 누릴 수 있습니다.

이 방법론을 체계적으로 공부하려면?

XML 태그 구조화는 앤트로픽 프롬프트 엔지니어링의 출발점입니다. 클로드 API를 프로덕션에 적용하다 보면 컨텍스트 관리, 멀티턴 대화 설계, 프롬프트 평가 지표 설정 같은 더 깊은 주제가 이어집니다. CCA-F(Claude Certified Architect — Foundations) 자격증은 이 주제들을 체계적으로 다루며 실무 역량을 검증할 수 있는 경로 중 하나입니다. PlinthPrep은 Anthropic과 무관한 독립 학습 사이트입니다. 이 글에서 다룬 내용을 실제로 이해했는지 확인하고 싶다면 PlinthPrep의 연습 문제로 점검해 보세요. plinthprep.com에서 무료로 확인할 수 있습니다.