Python으로 공부하는 OpenAI 2편 — 프롬프트를 잘 쓰는 사람과 헤매는 사람의 차이

Python으로 공부하는 OpenAI 2편 — 프롬프트를 잘 쓰는 사람과 헤매는 사람의 차이

첫 글에서는 OpenAI를 Python에서 처음 붙이는 방법을 다뤘습니다.
솔직히 1편은 “된다”에 가까운 글이었어요. API 키 넣고, SDK 설치하고, client.responses.create() 호출해서 답변 받기. 여기까지는 생각보다 금방 됩니다. OpenAI 공식 Python SDK도 현재 기본 흐름으로 OpenAI() 클라이언트와 client.responses.create(...)를 안내하고 있습니다. (GitHub)

근데 진짜 문제는 그다음부터예요.

분명 같은 모델인데,
어떤 날은 답이 괜찮고,
어떤 날은 너무 장황하고,
어떤 날은 엉뚱한 방향으로 가고,
어떤 날은 내가 원하는 형식은 전혀 안 지켜줍니다.

처음엔 “모델이 별로인가?” 싶었는데, 조금 지나고 보니 대부분의 문제는 모델보다 입력 방식, 정확히는 프롬프트 설계에서 시작되더라고요.

이번 글은 여기 집중합니다.

• 프롬프트가 왜 중요한지
• instructions와 input을 어떻게 나눠야 하는지
• 좋은 프롬프트와 나쁜 프롬프트 차이
• Python으로 바로 돌려보는 비교 실험
• 실무에서 결과를 덜 흔들리게 만드는 기본 습관

오늘 글부터는 진짜 “실무 감각”이 들어오기 시작합니다.

---

1. 프롬프트는 그냥 질문 문장이 아니다

처음 OpenAI를 붙이면 대부분 이렇게 씁니다.

response = client.responses.create(
    model="gpt-5.2",
    input="파이썬 데코레이터 설명해줘"
)

이렇게 해도 답은 나옵니다.
문제는 답의 품질을 통제하기 어렵다는 거예요.

왜냐하면 모델은 단순히 질문만 읽는 게 아니라,
“어떤 역할로”, “어떤 기준으로”, “어떤 형식으로”, “어느 정도 길이로”, “무엇을 우선시해서” 답해야 하는지에 따라 결과가 꽤 달라지기 때문입니다.

OpenAI 공식 문서 구조를 보면 Prompt engineering, Prompt guidance, Structured output, Function calling 같은 항목이 따로 있는 이유가 바로 이겁니다. 그냥 질문 하나 잘 던지는 문제가 아니라, 입력 구조 자체를 설계하는 문제에 가깝습니다. (OpenAI 플랫폼)

제가 느끼기엔 프롬프트는 “AI에게 말 걸기”가 아니라,
조금 더 정확히 말하면 작업 명세서 초안 쓰기에 가깝습니다.

---

2. 지금 Python 코드에서 가장 먼저 익혀야 할 감각: instructions와 input 분리

OpenAI 공식 Python SDK README의 기본 예제는 이런 식입니다.

• model
• instructions
• input

이 구성이 초보자에게 굉장히 중요합니다. SDK README는 instructions로 모델의 역할과 응답 스타일을 정하고, input으로 실제 질문을 넣는 예제를 보여줍니다. (GitHub)

이걸 한국말로 풀면 대략 이렇게 이해하면 됩니다.

반응형

instructions

모델에게 주는 상위 지침입니다.

예:

• 너는 친절한 파이썬 멘토다
• 답변은 초보자 눈높이로 해라
• 코드 예시는 반드시 포함해라
• 표 대신 불릿으로 설명해라
• 길게 쓰지 말고 핵심부터 말해라

input

그 순간 사용자가 실제로 요청한 내용입니다.

예:

• 파이썬의 *args와 **kwargs 차이를 설명해줘
• 리스트 컴프리헨션 예제 보여줘
• 아래 코드 왜 에러 나는지 알려줘

이 둘을 섞어서 한 줄에 다 넣으면,
처음엔 편해 보여도 점점 통제가 어려워집니다.

---

3. 프롬프트를 못 쓰는 사람의 전형적인 패턴

이건 진짜 많이 봤습니다.

패턴 1. 요청이 너무 짧다

input="JWT 설명해줘"

이러면 모델은 알아서 추론해서 답을 만듭니다.
그런데 “초보자용인지”, “백엔드 개발자 대상인지”, “예제가 필요한지”, “짧게 원하는지”, “실무 관점인지”가 빠져 있죠.

즉, 답이 틀릴 수도 있지만,
그보다 더 자주 일어나는 건 답이 내 기대와 어긋난다는 겁니다.

패턴 2. 한 문장에 모든 걸 때려 넣는다

input="너는 파이썬 멘토고 내가 주니어인데 너무 어렵지 않게 설명하고 예제도 주고 표도 주고 실무 예시도 주고 너무 길지 않게 해주고 JWT가 뭔지 알려줘"

처음엔 이런 방식 많이 씁니다.
근데 이건 읽는 사람도 힘들고, 모델도 중요도를 덜 명확하게 해석할 수 있습니다.

패턴 3. 형식을 안 정해놓고 형식을 기대한다

사람들이 자주 이렇게 말합니다.

“왜 답변 형식이 맨날 다르지?”

근데 정작 입력엔 형식 요구가 없습니다.
형식 요구가 없는데 매번 같은 형식을 기대하는 건, 사실 개발자 쪽 기대가 더 무리일 때가 많습니다.

---

4. 좋은 프롬프트의 핵심은 “친절함”이 아니라 “명확함”이다

이 부분이 제일 중요합니다.

많은 분이 프롬프트를 잘 쓴다는 걸
“모델한테 공손하게 말하는 것”이라고 생각하는데, 제 경험상 핵심은 그게 아닙니다.

핵심은 아래 4가지예요.

4-1. 역할을 정한다

누구처럼 답해야 하는가?

예:

• 주니어 백엔드 개발자를 가르치는 Python 멘토
• 실무 코드 리뷰어
• 기술 블로그 편집자
• API 문서 작성 도우미

4-2. 독자를 정한다

누가 이 답을 읽는가?

예:

• 입문자
• 1~3년차 백엔드 개발자
• 비전공자
• 서비스 기획자

4-3. 출력 형식을 정한다

답을 어떤 모양으로 받을 것인가?

예:

• 3문단
• 번호 목록 5개
• 코드 + 해설
• JSON
• 표
• 요약 3줄 + 상세 설명

4-4. 제약조건을 정한다

무엇을 하지 말아야 하는가?

예:

• 너무 장황하게 쓰지 마라
• 추상적 설명보다 코드 예제를 우선하라
• 모르면 추정하지 말고 불확실하다고 말하라
• 한국어로 작성하라

이 4가지만 들어가도 결과가 꽤 안정됩니다.

---

5. Python으로 바로 보는 나쁜 예시 vs 좋은 예시

5-1. 애매한 프롬프트

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

response = client.responses.create(
    model="gpt-5.2",
    input="파이썬 클래스 설명해줘"
)

print(response.output_text)

이 코드는 실행은 됩니다.
그런데 결과가 들쭉날쭉할 가능성이 큽니다.

왜냐하면 모델이 스스로 아래를 다 추정해야 하거든요.

• 독자 수준
• 설명 길이
• 예제 포함 여부
• 문체
• 실무 중심인지 이론 중심인지

5-2. 조금 더 나은 프롬프트

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

response = client.responses.create(
    model="gpt-5.2",
    instructions=(
        "당신은 주니어 개발자를 가르치는 친절한 파이썬 멘토입니다. "
        "설명은 한국어로 하고, 초보자 눈높이에 맞춰 작성하세요. "
        "추상적인 정의보다 짧은 코드 예제를 우선하고, "
        "답변은 1) 개념 설명 2) 예제 코드 3) 실무 팁 순서로 구성하세요."
    ),
    input="파이썬 클래스가 무엇인지 설명해줘"
)

print(response.output_text)

이렇게 바꾸면 같은 모델이어도 결과가 훨씬 읽기 좋아질 가능성이 큽니다.
이건 SDK 구조상 instructions를 통해 상위 행동 규칙을 주고 input으로 실제 요청을 분리하는 방식과도 잘 맞습니다. (GitHub)

---

6. 실무에서 진짜 많이 쓰는 프롬프트 템플릿

저는 입문자에게 프롬프트를 “매번 새로 쓰지 말고 템플릿화하라”고 자주 말합니다.
그게 훨씬 안정적이거든요.

아래는 Python 학습/개발 블로그/실무 도우미에 잘 맞는 기본 템플릿입니다.

TEMPLATE_INSTRUCTIONS = """
당신은 주니어 개발자를 돕는 시니어 Python 멘토입니다.
설명은 반드시 한국어로 작성하세요.
답변은 초보자도 이해할 수 있게 쉬운 표현을 사용하세요.
가능하면 짧은 예제 코드를 포함하세요.
모르는 내용을 추정하지 말고, 불확실하면 불확실하다고 말하세요.
답변은 다음 순서를 따르세요:
1. 한 줄 요약
2. 핵심 설명
3. 예제 코드
4. 실무 팁
"""

그리고 실제 질문은 이렇게 넣습니다.

question = "파이썬에서 예외 처리를 왜 해야 하는지 설명해줘"

response = client.responses.create(
    model="gpt-5.2",
    instructions=TEMPLATE_INSTRUCTIONS,
    input=question
)

이 방식의 장점은 분명합니다.

• 매번 품질 편차를 줄일 수 있고
• 팀 안에서 공통 스타일을 맞추기 쉽고
• 나중에 서비스 API로 만들기도 좋습니다

실무에서는 이걸 아예 상수, 설정 파일, 프롬프트 버전 테이블 같은 형태로 관리하는 경우도 많습니다.

---

7. 결과가 흔들릴 때는 프롬프트를 감으로 고치지 말고 비교 실험해야 한다

이건 정말 중요한 습관입니다.

결과가 마음에 안 든다고 해서
그때그때 감으로 프롬프트를 길게 늘리기 시작하면 금방 엉망이 됩니다.

대신 이렇게 해야 합니다.

• 기준 프롬프트 A를 만든다
• 한 요소만 바꾼 프롬프트 B를 만든다
• 같은 질문으로 각각 실행한다
• 결과를 비교한다

이런 식으로요.

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

question = "파이썬 데코레이터를 설명해줘"

prompt_a = """
당신은 Python 멘토입니다.
한국어로 설명하세요.
"""

prompt_b = """
당신은 주니어 개발자를 돕는 Python 멘토입니다.
한국어로 설명하세요.
답변은 1) 한 줄 요약 2) 쉬운 설명 3) 짧은 예제 코드 순서로 작성하세요.
"""

for name, instructions in [("A", prompt_a), ("B", prompt_b)]:
    response = client.responses.create(
        model="gpt-5.2",
        instructions=instructions,
        input=question
    )
    print("=" * 60)
    print(name)
    print(response.output_text)

이 코드는 아주 단순하지만,
프롬프트 개선을 “느낌”이 아니라 “비교”로 보게 해줍니다.

이 습관이 나중에 eval, prompt optimization, structured output 같은 단계로 넘어갈 때 큰 차이를 만듭니다. OpenAI 문서 구조에도 Evaluation, Prompt optimizer 같은 항목이 따로 있는 걸 보면, 프롬프트 품질을 실험적으로 다루는 흐름이 공식적으로도 중요하게 다뤄지고 있다는 걸 알 수 있습니다. (OpenAI 플랫폼)

---

8. 초보자일수록 출력 형식을 먼저 고정해야 한다

많은 분이 프롬프트 공부를 “어떻게 더 똑똑하게 말하게 만들까”로 접근하는데,
실무에서는 오히려 어떻게 더 예측 가능하게 받을까가 더 중요합니다.

예를 들어 아래 두 요청을 비교해보세요.

형식 없는 요청

input="JWT를 설명해줘"

형식 있는 요청

input="""
JWT를 설명해줘.
아래 형식으로 답변해줘.
1. 정의
2. 구성 요소
3. 장점
4. 단점
5. Python 백엔드에서 쓰는 예시
"""

두 번째는 훨씬 다루기 쉽습니다.
왜냐하면 응답을 읽는 사람도 편하고,
나중에 API 응답으로 프론트에 보여줄 때도 구조를 맞추기 쉬우니까요.

그리고 이건 다음 편에서 더 다루겠지만, OpenAI 문서는 Structured output을 핵심 개념 중 하나로 따로 안내하고 있습니다. 즉 “형식을 지정한다”는 습관은 나중에 JSON 출력과도 자연스럽게 연결됩니다. (OpenAI 플랫폼)

---

9. 실무형 프롬프트를 만들 때 넣어두면 좋은 문장들

이건 제가 실제로 자주 쓰는 문장들입니다.

설명 수준 제어

• 초보자도 이해할 수 있게 설명하세요.
• 비전공자도 이해할 수 있게 쉬운 비유를 포함하세요.
• 너무 전문 용어 위주로 쓰지 마세요.

형식 제어

• 답변을 번호 목록으로 작성하세요.
• 반드시 코드 예제를 하나 포함하세요.
• 답변을 5문장 이내로 요약한 뒤 상세 설명을 이어가세요.

안정성 제어

• 확실하지 않은 내용은 단정하지 마세요.
• 사실과 의견을 구분해서 작성하세요.
• 근거가 부족하면 추정이라고 명시하세요.

실무성 강화

• 단순 개념 설명보다 실무 예시를 우선하세요.
• Python 백엔드 개발 관점에서 설명하세요.
• 운영 환경에서 주의할 점도 함께 써주세요.

이 문장들을 조합해서 쓰면,
처음부터 꽤 괜찮은 품질이 나오는 편입니다.

---

10. 프롬프트를 길게 쓰는 게 항상 좋은 건 아니다

이것도 은근히 많이 오해합니다.

처음 프롬프트 효과를 보면,
사람들이 갑자기 지시문을 엄청 길게 씁니다.
근데 길다고 항상 좋은 건 아닙니다.

너무 길면 오히려:

• 핵심 지시가 흐려지고
• 우선순위가 섞이고
• 유지보수가 어려워지고
• 팀원이 읽기 힘들어집니다

좋은 프롬프트는 보통
“짧지만 핵심이 분명한 상태”에 가깝습니다.

제 기준에선 아래처럼 정리되면 꽤 좋습니다.

• 역할 1줄
• 독자 1줄
• 출력 형식 1~3줄
• 금지/제약 1~2줄

이 정도면 충분한 경우가 많습니다.

---

11. 지금 단계에서 꼭 해봐야 할 실습

이번 글은 읽고 넘기면 체감이 적습니다.
아래 실습은 꼭 직접 돌려보는 걸 추천합니다.

실습 1. 같은 질문을 서로 다른 instructions로 실행하기

질문 하나를 정하고, instructions만 바꿔보세요.

예:

• 멘토 스타일
• 면접관 스타일
• 블로그 작가 스타일

실습 2. 출력 형식 유무 비교하기

하나는 자유 답변, 하나는 번호 목록으로 요청해보세요.

실습 3. “실무 팁 포함” 문구를 넣고 빼보기

별거 아닌 것 같아도 결과 차이가 꽤 납니다.

---

12. 오늘 글의 핵심 요약

오늘 글에서 꼭 가져가야 할 건 이것입니다.

프롬프트는 그냥 질문 문장이 아니라, 모델이 어떻게 답해야 하는지 정하는 작업 명세다.

그리고 Python에서 OpenAI를 쓸 때는:

• instructions로 상위 규칙을 주고
• input으로 실제 요청을 넣고
• 형식을 미리 정하고
• 비교 실험으로 개선하는 습관

이 네 가지가 정말 중요합니다. OpenAI 공식 Python SDK의 기본 예제도 바로 이 흐름을 보여주고 있고, 공식 문서 구조 역시 Prompt engineering, Prompt guidance, Structured output, Evaluation 같은 주제를 별도로 다루고 있습니다. (GitHub)

이 감각이 생기면,
이제부터는 “질문 잘하기” 수준을 넘어서
서비스에 들어갈 수 있는 안정적인 입력 설계로 넘어갈 수 있습니다.

---

다음 편 예고

다음 글에서는 한 단계 더 실무적으로 들어가겠습니다.

Python으로 OpenAI 응답을 JSON 형태로 안정적으로 받는 방법

이 주제로,

• 왜 자유문장보다 JSON이 중요한지
• 구조화 출력이 필요한 이유
• 블로그 생성기, 분류기, 요약기에서 JSON이 왜 필수인지
• Python 코드로 JSON 파싱하는 흐름
• 응답 형식이 깨졌을 때 어떻게 처리하는지

까지 이어가보겠습니다.

---

출처

• OpenAI 공식 Python SDK README — OpenAI() 클라이언트, client.responses.create(...), instructions와 input 사용 예제, Chat Completions는 이전 표준으로 안내 (GitHub)
• OpenAI API Docs 탐색 결과 — Prompt engineering, Reasoning, Evaluation, Prompt optimizer 등 문서 구조 확인 (OpenAI 플랫폼)
• OpenAI API Docs 내 Guides/Concepts — Prompt guidance, Structured output, Responses API 등 핵심 개념 섹션 확인 (OpenAI 플랫폼)

 

Python, OpenAI, 프롬프트 엔지니어링, OpenAI Python SDK, Responses API, GPT API, AI 개발 입문, 주니어 개발자, Python 실무, 생성형 AI, LLM, 프롬프트 작성법, AI 백엔드, 구조화 출력, OpenAI 튜토리얼