프롬프트 엔지니어링

프롬프트 엔지니어링 (Prompt engineering)

OpenAI API로는 대규모 언어 모델을 써서 프롬프트로 텍스트를 생성할 수 있어요. ChatGPT를 쓰는 것처럼요. 모델은 코드, 수학 방정식, 구조화된 JSON, 사람 같은 산문 등 거의 모든 종류의 텍스트를 만들 수 있어요.

출처: 문서

본문

간단한 예시

Responses API를 쓰는 간단한 예시를 볼게요.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

모델이 생성한 콘텐츠 배열은 응답의 output 속성에 들어 있어요. 간단한 예시에서는 output이 하나뿐이에요. 그런데 output 배열에는 항목이 하나 이상인 경우가 많아요! 도구 호출, reasoning 모델이 생성한 reasoning 토큰 데이터 등이 들어갈 수 있어요. 그래서 텍스트 출력이 반드시 output[0].content[0].text에 있다고 가정하면 안 돼요. 일부 공식 SDK는 편의상 output_text 속성을 제공해 모델의 모든 텍스트 출력을 하나의 문자열로 모아줘요.

일반 텍스트뿐 아니라 모델이 JSON 형식의 구조화된 데이터를 반환하게 할 수도 있는데, 이 기능을 Structured Outputs라고 불러요.

모델 선택하기

API로 콘텐츠를 생성할 때 핵심 선택은 어떤 모델을 쓸지예요. 코드의 model 파라미터죠. 사용 가능한 모델 전체 목록은 여기에서 볼 수 있어요. 텍스트 생성용 모델을 고를 때 고려할 몇 가지는 다음과 같아요.

Reasoning 모델 은 입력 프롬프트를 분석하는 내부 chain-of-thought를 생성하고, 복잡한 과업 이해와 다단계 계획에 뛰어나요. 다만 일반적으로 GPT 모델보다 느리고 비싸요.
GPT 모델은 빠르고 비용 효율적이며 지능이 높지만, 과업 수행 방법에 대한 더 명시적인 지시를 받을수록 좋아요.
크고 작은 (mini 또는 nano) 모델은 속도·비용·지능의 트레이드오프를 제공해요. 큰 모델은 여러 도메인에서 프롬프트 이해와 문제 해결에 더 효과적이고, 작은 모델은 일반적으로 더 빠르고 저렴해요.

어떤 걸 쓸지 모르겠다면 gpt-6-astra가 범용 텍스트 생성과 프롬프트 반복의 강력한 기본값이에요.

프롬프트 엔지니어링

프롬프트 엔지니어링은 모델의 조건을 일관되게 충족하는 콘텐츠를 생성하도록, 모델을 위한 효과적인 지시를 작성하는 과정이에요.

모델 생성 콘텐츠는 비결정적이라 원하는 출력을 얻는 프롬프팅은 예술과 과학의 결합이에요. 하지만 기법과 모범 사례를 적용하면 좋은 결과를 일관되게 얻을 수 있어요. 메시지 역할처럼 모든 모델에 적용되는 기법도 있지만, 모델 유형(예: reasoning 대 GPT)에 따라 프롬프팅 방식이 다를 수 있어요. 같은 계열의 다른 스냅샷조차 다른 결과를 낼 수 있어요. 그래서 복잡한 앱을 만들수록 다음을 강력히 권장해요.

운영 앱을 특정 모델 스냅샷(예: gpt-4.1-2025-04-14)에 고정해서 일관된 동작을 보장해요.
프롬프트 동작을 측정하는 테스트와 평가 스위트를 만들어, 반복하거나 모델 버전을 바꿀 때 성능을 모니터링해요.

메시지 역할과 지시 따르기

instructions API 파라미터나 메시지 역할로, 모델에게 서로 다른 권위 수준의 지시를 줄 수 있어요.

instructions 파라미터는 응답을 생성할 때 어떻게 행동할지에 대한 상위 수준 지시를 주고, 톤·목표·올바른 응답 예시를 포함해요. 이렇게 준 지시는 input 파라미터의 프롬프트보다 우선해요.

instructions는 현재 응답 생성 요청에만 적용되는 점을 유의하세요. previous_response_id 파라미터로 대화 상태를 관리한다면, 이전 턴에서 쓴 instructions는 컨텍스트에 남지 않아요.

OpenAI 모델 스펙은 서로 다른 역할의 메시지에 모델이 부여하는 우선순위를 설명해요.

`developer`	`user`	`assistant`
앱 개발자가 제공하는 지시로, `user` 메시지보다 우선해요.	최종 사용자가 제공하는 지시로, `developer` 메시지보다 뒤에 처리돼요.	모델이 생성하는 메시지의 역할이에요.

멀티턴 대화는 이런 유형의 여러 메시지와, 사용자와 모델 양쪽이 제공하는 다른 콘텐츠 유형으로 구성될 수 있어요. 여기에서 대화 상태 관리를 자세히 볼 수 있어요.

developer와 user 메시지는 프로그래밍 언어의 함수와 그 인자로 생각할 수 있어요.

developer 메시지는 함수 정의처럼 시스템의 규칙과 비즈니스 로직을 제공해요.
user 메시지는 함수의 인자처럼, developer 메시지 지시가 적용될 입력·설정을 제공해요.

코드에서 프롬프트 버전 관리하기

운영 프롬프트는 재사용 가능한 프롬프트 객체 대신 앱 코드에 저장하는 게 좋아요. 코드로 관리하는 프롬프트는 타입 있는 입력, 코드 리뷰, 테스트, 일반적인 배포 프로세스를 써서 모델 동작을 바꿀 수 있게 해줘요.

OpenAI는 API에서 재사용 가능한 프롬프트 객체를 폐기(deprecate)하고 있어요. 프롬프트 생성은 2026년 6월 3일부터 비중이 줄어들고, v1/prompts는 2026년 11월 30일에 종료될 예정이에요. 자세한 일정은 deprecations 페이지를 확인하세요.

새 프롬프트 엔지니어링 작업에서는:

프롬프트 빌더를 기능 옆의 작은 모듈에 두세요.
고객 데이터·파일·작업 옵션 같은 동적 값은 타입 있는 함수 인자나 스키마를 쓰세요.
생성한 instructions와 input을 Responses API에 직접 전달하세요.
운영 프롬프트를 바꾸기 전에 대표적인 fixture·테스트·평가 체크를 추가하세요.
프롬프트 변경은 배포 시스템으로 롤아웃하고, 단계적 릴리스가 필요하면 feature flag나 설정을 쓰세요.

이미 프롬프트 ID나 버전으로 저장된 프롬프트를 호출하고 있다면, 프롬프트 객체 마이그레이션 가이드로 그 프롬프트를 코드로 옮기세요.

Markdown과 XML로 메시지 서식 지정하기

developer와 user 메시지를 작성할 때 Markdown 서식과 XML 태그를 조합하면 모델이 프롬프트와 컨텍스트 데이터의 논리적 경계를 이해하는 데 도움이 돼요. Markdown 헤더와 목록은 프롬프트의 구역을 구분하고 계층을 전달하는 데 쓸 수 있어요. XML 태그는 참조용 보조 문서 같은 콘텐츠가 시작하고 끝나는 지점을 분리해 주고, XML 속성은 지시문에서 참조할 수 있는 메타데이터를 정의할 수 있어요.

일반적으로 developer 메시지에는 보통 이 순서로 이 섹션들이 들어가요. (정확한 최적 콘텐츠와 순서는 사용하는 모델에 따라 달라질 수 있어요.)

Identity(정체성): 어시스턴트의 목적, 커뮤니케이션 스타일, 상위 수준 목표를 설명해요.
Instructions(지시): 원하는 응답을 생성하는 방법을 안내해요. 따라야 할 규칙, 해야 할 일·절대 하지 말아야 할 일을요. 이 섹션은 커스텀 함수 호출처럼 용도에 맞는 여러 하위 섹션을 포함할 수 있어요.
Examples(예시): 가능한 입력과 원하는 모델 출력의 예시를 제공해요.
Context(컨텍스트): 모델이 응답을 생성하는 데 필요한 추가 정보를 제공해요. 훈련 데이터 밖의 사유·독점 데이터나 특히 관련 있는 데이터처럼요. 이 내용은 요청마다 컨텍스트가 다를 수 있으니 프롬프트 끝부분에 두는 게 보통 좋아요.

아래는 Markdown과 XML 태그로 구역을 나누고 예시를 든 developer 메시지 예시예요.

# Identity

You are coding assistant that helps enforce the use of snake case
variables in JavaScript code, and writing code that will run in
Internet Explorer version 6.

# Instructions

* When defining variables, use snake case names (e.g. my_variable)
  instead of camel case names (e.g. myVariable).
* To support old browsers, declare variables using the older
  "var" keyword.
* Do not give responses with Markdown formatting, just return
  the code as requested.

# Examples

<user_query>
How do I declare a string variable for a first name?
</user_query>

<assistant_response>
var first_name = "Anna";
</assistant_response>

프롬프트 캐싱으로 비용·지연 줄이기

메시지를 구성할 때, API 요청에서 반복 사용할 내용을 프롬프트 맨 앞에 두는 게 좋아요. 그리고 Chat Completions 또는 Responses의 JSON 요청 본문에서도 앞쪽 파라미터로 넣어야 해요. 그래야 프롬프트 캐싱으로 비용·지연 절감을 최대화할 수 있어요.

Few-shot 학습

Few-shot 학습은 모델을 fine-tuning하는 대신, 프롬프트에 몇 개의 입력/출력 예시를 넣어 새 과업으로 끌어가는 방법이에요. 모델은 그 예시에서 패턴을 암묵적으로 배워 프롬프트에 적용해요. 예시는 가능한 다양한 입력 범위와 원하는 출력을 보여주도록 해요.

보통 예시는 developer 메시지의 일부로 제공해요. 아래는 제품 리뷰를 Positive/Negative/Neutral로 분류하는 예시를 담은 developer 메시지예요.

# Identity

You are a helpful assistant that labels short product reviews as
Positive, Negative, or Neutral.

# Instructions

* Only output a single word in your response with no additional formatting
  or commentary.
* Your response should only be one of the words "Positive", "Negative", or
  "Neutral" depending on the sentiment of the product review you are given.

# Examples

<product_review id="example-1">
I absolutely love this headphones — sound quality is amazing!
</product_review>

<assistant_response id="example-1">
Positive
</assistant_response>

<product_review id="example-2">
Battery life is okay, but the ear pads feel cheap.
</product_review>

<assistant_response id="example-2">
Neutral
</assistant_response>

현재 모델 프롬프팅

gpt-6-astra 같은 GPT 모델은 과업을 완수하는 데 필요한 로직과 데이터를 명시적으로 제공하는 정밀한 지시에서 이점을 얻어요. 최신 모델을 최대한 활용하려면 현재 프롬프팅 가이드부터 시작하세요. 전체 최신 내용은 최신 모델 프롬프팅 모범 사례에서 볼 수 있어요. 실용적인 핵심 몇 가지를 요약하면 이래요.

코딩

gpt-6-astra로 코딩 과업을 할 때는 역할 정의, 도구 사용 예시, 철저한 테스트 요구, 깔끔한 출력을 위한 Markdown 기준을 따르는 게 효과적이에요.

명시적 역할·워크플로: 모델을 책임이 명확한 소프트웨어 엔지니어링 에이전트로 프레이밍해요. 코드 작업에는 functions.run 같은 도구 사용 지시를 명확히 하고, 대화형 실행은 필요한 때만 쓰게 해요.
테스트와 검증: 단위 테스트나 Python 명령으로 변경을 테스트하게 하고, apply_patch 같은 도구가 실패해도 "Done"을 반환할 수 있으므로 패치를 신중히 검증하게 해요.
도구 사용 예시: 제공된 함수로 명령을 호출하는 구체적인 예시를 포함하면 신뢰성과 워크플로 준수가 좋아져요.
Markdown 기준: 인라인 코드·코드 펜스·목록·표를 적절히 써서 깨끗하고 의미적으로 올바른 markdown을 생성하게 하고, 파일 경로·함수·클래스는 백틱으로 감싸게 해요.

프론트엔드 엔지니어링

GPT-6 Astra는 처음부터 프론트엔드를 만들고 큰 기존 코드베이스에 기여하는 데 모두 뛰어나요. 좋은 결과를 위해 다음 라이브러리를 권장해요.

스타일링/UI: Tailwind CSS, shadcn/ui, Radix Themes
아이콘: Lucide, Material Symbols, Heroicons
애니메이션: Motion

큰 코드베이스에서 프론트엔드 작업을 할 때는 이런 범주의 지시를 프롬프트에 추가하는 게 좋아요.

Principles(원칙): 시각적 품질 기준을 세우고, 모듈형/재사용 컴포넌트를 쓰며, 디자인을 일관되게 유지해요.
UI/UX: 타이포그래피, 색, 간격/레이아웃, 상호작용 상태(hover·empty·loading), 접근성을 지정해요.
Structure(구조): 매끄러운 통합을 위한 파일/폴더 배치를 정의해요.
Components(컴포넌트): 재사용 가능한 래퍼 예시와 백엔드 호출 분리 전략을 제공해요.
Pages(페이지): 공통 레이아웃용 템플릿을 제공해요.
Agent Instructions: 디자인 가정을 확인하고, 프로젝트를 스캐폴딩하고, 기준을 적용하고, API를 통합하고, 상태를 테스트하고, 코드를 문서화하게 해요.

에이전트 작업

gpt-6-astra로 에이전트·장기 실행 롤아웃을 할 때는 세 가지 핵심에 집중해요. 완전한 해결을 보장하도록 작업을 철저히 계획하고, 주요 도구 사용 결정에 대해 명확한 preamble을 제공하고, TODO 도구로 워크플로와 진행을 체계적으로 추적하게 해요.

작업을 하위 과업으로 분해하고 각 도구 호출 후 반성해서 완결성을 확인하게 해요. 툴 호출 전에는 그 이유를 설명하게 하고, TODO 목록 도구나 루브릭으로 구조화된 계획을 강제해 단계 누락을 막아요.

Reasoning 모델 프롬프팅

reasoning 모델을 프롬프팅할 때는 GPT 모델과 다른 점이 있어요. 일반적으로 reasoning 모델은 상위 수준 지시만 있는 과업에서 더 좋은 결과를 내요. 이는 매우 정밀한 지시에서 이점을 얻는 GPT 모델과 달라요.

reasoning 모델은 선임 동료 같아요. 목표만 주면 세부 사항은 알아서 해결해요.
GPT 모델은 주니어 동료 같아요. 특정 출력을 만들도록 명시적 지시를 받을 때 최고 성능을 내요.

reasoning 모델 사용 모범 사례에 대한 자세한 내용은 이 가이드를 참고하세요.

프롬프트 엔지니어링

프롬프트 엔지니어링 (Prompt engineering)

본문

간단한 예시

모델 선택하기

프롬프트 엔지니어링

메시지 역할과 지시 따르기

코드에서 프롬프트 버전 관리하기

Markdown과 XML로 메시지 서식 지정하기

프롬프트 캐싱으로 비용·지연 줄이기

Few-shot 학습

관련 컨텍스트 정보 포함하기

컨텍스트 윈도우 계획하기

현재 모델 프롬프팅

Reasoning 모델 프롬프팅

더 알아보기 (Learn more)