개발자를 위한 프롬프트 엔지니어링: 시스템 프롬프트 설계
역할·제약·출력 형식을 갖춘 시스템 프롬프트를 설계하고 버전 관리하는 실전 접근을 정리합니다.
개발자를 위한 프롬프트 엔지니어링: 시스템 프롬프트 설계
개요
개발자에게 프롬프트 엔지니어링은 마법적인 말재주가 아니라 인터페이스 설계에 가깝습니다. 시스템 프롬프트는 결국 LLM에게 주는 API 명세이고, 그렇다면 개발자의 설계 감각을 그대로 적용할 수 있습니다.
역할·제약·출력 형식
제가 시스템 프롬프트를 쓸 때 지키는 구조는 세 가지입니다. 역할(누구로서), 제약(무엇을 하지 말지), 출력 형식(어떻게 응답할지)입니다.
[역할] 당신은 TypeScript 코드 리뷰어입니다.
[제약]
- 스타일 지적은 하지 않는다 (lint가 담당)
- 보안 문제는 최우선으로 지적한다
- 확실하지 않으면 추측 대신 "확인 필요"로 표시한다
[출력 형식]
각 이슈를 아래 형식으로 응답한다:
- 심각도: high | medium | low
- 위치: 파일과 대략적인 줄
- 문제와 이유 한 문장
특히 “하지 말 것”을 명시하는 게 효과가 컸습니다. LLM은 긍정 지시만으로는 행동 반경을 줄이지 않는 경우가 많습니다.
퓨샷으로 형식을 고정하기
출력 형식을 지키고 싶을 때 가장 확실한 방법은 예시, 즉 퓨샷(few-shot)입니다. 형식 설명 문장 세 줄보다 실제 예시 하나가 더 잘 동작합니다.
{"severity": "high", "location": "src/auth.ts:42", "issue": "토큰을 쿼리스트링으로 전달해 로그에 남을 수 있음"}
이런 예시를 프롬프트에 두 개쯤 넣으면, 응답이 거의 항상 이 구조를 따라옵니다.
프롬프트도 버전 관리하자
프롬프트는 코드처럼 변경되고, 변경은 회귀를 만듭니다. 그래서 프롬프트를 코드베이스에 넣고 버전 관리합니다.
from pathlib import Path
PROMPT_VERSION = "2026.03.10"
def load_system_prompt() -> str:
path = Path(f"prompts/reviewer_v{PROMPT_VERSION}.txt")
return path.read_text(encoding="utf-8")
변경할 때는 이전 버전 파일을 남기고, 로깅에 버전을 함께 기록합니다. 나중에 “응답 품질이 이상해졌다”는 보고가 왔을 때 프롬프트 변경 이력을 바로 추적할 수 있습니다.
자주 겪은 실패와 교훈
- 지시가 충돌하면(간결하게 + 모든 케이스 나열) 둘 다 어중간해집니다. 우선순위를 명시합니다.
- 긴 프롬프트 뒤에 중요 지시를 넣으면 흐려집니다. 핵심은 앞이나 뒤에 둡니다.
- 예시가 편향되면 출력도 편향됩니다. 퓨샷은 다양한 케이스를 골라 넣습니다.
마무리
시스템 프롬프트 설계는 역할·제약·출력 형식의 명세 작성이고, 퓨샷은 예시 기반의 스키마 고정이며, 버전 관리는 프롬프트를 다루는 최소한의 엔지니어링입니다. 코드 다루듯 다루면 됩니다.