운영 환경에서 통제되지 않은 채 실행되는 LLM 프롬프트: 아키텍처 해결책

부끄러운 사실을 하나 보여드리고 싶습니다.

이것은 제 코드베이스의 실제 git 커밋 내역입니다. 2025년 1월:

commit a3f91c2
Author: Gandiv <gandiv@----.io>
Date:   Fri Jan 10 23:41:07 2025
...

그 커밋은 운영 환경(production)에 반영되었습니다. 리뷰도 없었습니다. 저를 제외한 누구에게도 diff(차이점)가 보이지 않았습니다. 이전 동작이 무엇이었는지, 왜 변경했는지에 대한 기록도 없었습니다. 롤백(rollback) 계획도 없었습니다. 그저 밤 11시 30분에 저 혼자 문자열을 수정하며 아무것도 망가지지 않기를 바랄 뿐이었습니다.

3주 후, 팀의 다른 엔지니어가 설정(config) 파일을 "정리"하면서 해당 변경 사항을 되돌렸습니다(revert). 우리 중 누구도 6일 동안 이를 알아차리지 못했습니다. 사용자는 2일 차에 알아차렸습니다.

"프롬프트 성능 저하(prompt regressed)"와 "문제를 발견함" 사이의 이 6일간의 간극을 없애기 위해 제가 PromptMatrix를 만들었습니다.

아무도 말하지 않는 인프라의 간극

프롬프트가 스택 내의 다른 모든 설정값(config value)과 다른 점은 바로 이것입니다.

데이터베이스 연결 문자열(database connection string)은 작동하거나 작동하지 않거나 둘 중 하나입니다. 실패 모드(failure mode)가 이진적(binary)이고 즉각적입니다.

반면 프롬프트 실패는 행동적(behavioural)이며 점진적입니다. AI는 여전히 응답합니다. 다만 조금 다르게 응답할 뿐입니다. 말투가 부드러워지거나, 거절 동작이 달라지거나, 페르소나(persona)가 미묘하게 깨지는 식입니다. 그리고 당신은 3초 뒤의 모니터링 알림이 아니라, 3일 뒤의 사용자 피드백을 통해 이를 알게 됩니다.

이러한 비대칭성은 표준적인 설정 관리 방식(환경 변수(environment variables), 하드코딩된 문자열(hardcoded strings), .env 파일)이 프롬프트에는 진정으로 잘못된 방식임을 의미합니다. 당신은 이진적 실패 모드를 위해 설계된 도구를 미묘한 행동적 실패 모드를 가진 대상에 사용하고 있는 것입니다.

당신에게 실제로 필요한 것은 코드에 이미 존재하는 것들입니다: 버전 이력(version history), diff 가시성(diff visibility), 리뷰 게이트(review gates), 그리고 롤백 기능(rollback capability)입니다.

문제는 아무도 프롬프트를 위해 이것들을 구축하지 않았다는 점입니다. 최근까지는 말이죠.

현재의 상태

아키텍처에 대해 들어가기에 앞서, 현재 LLM 제품을 만드는 대부분의 팀에서 "프롬프트 관리(prompt management)"가 어떤 모습인지 솔직하게 말씀드리겠습니다.

1단계: 파일 안의 문자열

# agent.py
SYSTEM_PROMPT = "You are a customer support agent for Acme Corp. Be helpful and professional."

...

이것이 모든 이들이 시작하는 지점입니다. 프로토타입(prototype) 단계에서는 괜찮습니다. 하지만 당신 이외의 누군가가 해당 문자열을 변경해야 하는 순간, 이는 리스크(liability)가 됩니다.

2단계: 환경 변수 (The environment variable)

# agent.py
import os

...

조금 더 나아졌습니다. 이제 코드를 건드리지 않고도 프롬프트를 변경할 수 있습니다. 하지만 새로운 값을 적용하려면 여전히 배포(deploy)가 필요합니다. 또한, 이전 값이 무엇이었는지에 대한 이력(history)이 전혀 남지 않습니다.

3단계: 데이터베이스 설정 테이블 (The database config table)

# agent.py
from db import get_config

...

이제 재배포 없이도 변경이 가능합니다. 하지만 여전히 차이점 보기(diff view), 승인 워크플로우(approval workflow), 감사 추적(audit trail)이 없으며, 엔지니어가 아닌 사람이 안전하게 사용할 수 있는 인터페이스도 없습니다.

4단계: Notion 문서 (The Notion doc)

여기서부터 조직적 부채(organizational debt)가 복리로 쌓이기 시작합니다. 누군가 "승인된 프롬프트 - 운영 환경(Approved Prompts - Production)"이라는 이름의 Notion 페이지를 만듭니다. 엔지니어들은 거기서 내용을 복사해 오기로 되어 있습니다. 하지만 항상 그러지는 않습니다. 문서는 운영 환경과 괴리됩니다. 어떤 버전이 실제로 실행되고 있는지 아무도 모르게 됩니다.

익숙한 상황인가요? 익숙해야 합니다. 제가 대화해 본 거의 모든 AI 제품 팀은 2단계와 4단계 사이 어딘가에 머물러 있습니다.

운영 환경 프롬프트 거버넌스(Production Prompt Governance)에 실제로 필요한 것

이 요구사항들이 과소평가되고 있다고 생각하기에, 제대로 명세(spec)를 정의해 보겠습니다.

요구사항 1: 안정적인 키를 가진 정식 레지스트리 (A canonical registry with stable keys)

모든 프롬프트에는 안정적인 식별자(identifier)가 필요합니다. 리팩터링(refactor) 시 이름을 바꿀 수 있는 변수명이 아니라, API 계약(API contract)의 일부가 되는 불변의 키(immutable key)여야 합니다.

assistant.system
email.rewriter  
lead.qualifier
...

이 키들은 애플리케이션이 프롬프트를 참조하는 방식입니다. 그 뒤에 담긴 내용은 변경될 수 있지만, 키는 절대 변하지 않습니다.

요구사항 2: 불변의 버전 이력 (Immutable version history)

프롬프트가 변경될 때마다 이전 상태가 보존되어야 합니다. (읽기 위해 저장소 접근 권한이 필요한) git 로그가 아니라, 무엇이, 누구에 의해, 언제 변경되었으며 차이점(diff)이 무엇이었는지를 보여주는 쿼리 가능한 이력(queryable history) 형태여야 합니다.

요구사항 3: 제안과 운영 환경(production) 사이에 검토 게이트(review gate)를 두는 것

이것은 대부분의 팀들이 건너뛰는 부분이며, 가장 중요한 부분입니다.

워크플로우는 다음과 같아야 합니다:

1. 누군가가 변경 사항을 제안합니다 (대시보드 접근 권한이 있는 누구라도 가능)
2. 지정된 검토자가 차이점(diff)을 확인합니다 — 이전 내용과 새 내용을 줄 단위로 비교하며 봅니다.
3. 검토자는 메모와 함께 승인하거나 거부합니다.
4. 승인 시: 새로운 내용이 실시간으로 적용되고, 이전 버전은 보관됩니다.

이 게이트 덕분에 비(非)엔지니어에게도 편집 접근 권한을 주는 것이 안전해집니다. 이것이 없으면 PM에게 프롬프트 저장소에 대한 접근 권한을 주는 것은 무섭습니다. 하지만 이 게이트가 있으면, 바로 원하는 방식입니다.

요구사항 4: 빌드 시점 번들링(build-time bundling)이 아닌 런타임 서빙(Runtime serving)

애플리케이션은 현재 승인된 프롬프트를 빌드 시점에 설정 파일에서 읽어오는 것이 아니라, 런타임에 가져와야 합니다.

# 이전 방식: 빌드 시점, 변경하려면 재배포 필요
SYSTEM_PROMPT = "You are a helpful assistant..."

...

프롬프트 변경이 승인되면, pm.serve()에 대한 바로 다음 호출에서 새로운 내용이 반환됩니다. 재시작이나 재배포가 필요 없습니다. 캐시 플러시도 필요하지 않습니다 (SDK가 내부적으로 TTL을 처리합니다).

요구사항 5: 디버깅 세션에서도 살아남는 감사 추적(audit trail)

무언가가 고장 났을 때,

개발 모드(development mode)에서는 빠른 승인(quick-approve) 단축 경로가 있습니다: 검토 대기열(review queue)을 건너뛰고 초안(draft)에서 승인(approved) 상태로 한 번에 넘어갑니다. 이 기능은 APP_ENV=development 환경에서만 허용되며, 운영(production) 환경에서는 403 에러를 반환합니다.

핫 패스(The Hot Path): 서브 엔드포인트(The Serve Endpoint)

이 부분은 실제 지연 시간(latency)이 중요한 구간입니다. LLM 호출 경로(call path)에 포함되어 있기 때문입니다.

GET /pm/serve/assistant.system
Authorization: Bearer pm_live_xxxxxxxxxxxxx

# 1. API 키 추출 및 해싱 (Extract and hash the API key)
raw_key = request.headers["Authorization"].split(" ")[1]
key_hash = sha256(raw_key)
...

캐시 히트(Cache hit) 경로: 약 5ms. 캐시 미스(Cache miss) 경로 (DB 쿼리): 약 50ms. 캐시 TTL은 기본적으로 30초이므로, "승인(approved)"과 "라이브(live)" 사이의 최대 지연 시간은 30초입니다.

로컬 모드에서 캐시는 순수 파이썬(pure-Python) LRU 딕셔너리(dict)로 구현됩니다. 클라우드 모드(Vercel serverless)에서는 REST API를 통한 Upstash Redis를 사용합니다. 이는 서버리스 콜드 스타트(cold starts) 시 인메모리 상태(in-memory state)가 유지되지 않기 때문입니다.

변수 치환 (Variable Substitution)

프롬프트는 {{double_curly}} 구문을 사용하여 동적 변수를 가질 수 있습니다:

{{company_name}}의 지원 에이전트입니다.
{{tone}} 톤으로 응답하세요. 결제 관련 문제는 {{escalation_tier}} 단계로 에스컬레이션(escalate)하세요.

이 변수들은 서브 타임(serve time)에 쿼리 파라미터(query params)를 통해 치환됩니다:

GET /pm/serve/support.agent?vars=company_name=Acme&vars=tone=professional&vars=escalation_tier=2

파서는 쉼표(comma)를 포함하는 값에서 오류가 발생하는 것을 방지하기 위해 (쉼표로 구분하는 대신) 반복적인 vars 파라미터를 사용합니다:

var_dict = {}
for v in request.query_params.getlist("vars"):
    if "=" in v:
...

채워지지 않은 변수(Unfilled variables)는 {{variable_name}} 형태로 남겨지며, JSON 응답의 unfilled_variables 필드에 보고됩니다. 이를 통해 에이전트 호출이 LLM에 빈 값을 조용히 전달하기 전에 설정 오류를 잡아낼 수 있습니다.

SDK 사용법 (SDK Usage)

# pip install promptmatrix-sdk

from promptmatrix import PromptMatrix
...

SDK는 로컬 TTL 캐싱을 처리하므로, 모든 LLM 요청마다 HTTP 호출을 수행하지 않습니다. TTL이 만료되면 캐시는 자동으로 무효화(invalidate)되며, 30초 이내에 승인된 모든 변경 사항을 반영하게 됩니다.

평가 엔진 (The Eval Engine)

별도로 언급할 가치가 있는 한 가지 사항은, 프롬프트 변경 사항이 승인되기 전에 평가 파이프라인 (evaluation pipeline)을 통해 실행해 볼 수 있다는 점입니다.

규칙 기반 평가 (Rule-based eval, 의존성 없음, <5ms):

8가지 차원에 걸쳐 프롬프트를 점수화합니다:

차원: 확인 항목. 역할 명확성 (Role clarity): 명확한 페르소나 정의로 시작하는가? 지시 품질 (Instruction quality): 명령어가 명령형이며 모호하지 않은가? 출력 형식 (Output format): 기대되는 출력 구조가 지정되었는가? 구체성 (Specificity): 구체적인 제약 조건이나 예시가 있는가? 변수 사용 (Variable usage): 동적 값이 {{vars}}와 같이 매개변수화되었는가? 컨텍스트 제공 (Context provision): 충분한 배경 정보가 제공되었는가? 길이 (Length): 50-800단어의 최적 범위 내에 있는가? 안전성 (Safety): 개인정보(PII) 패턴, 하드코딩된 비밀값(secrets), 인젝션 벡터(injection vectors)가 없는가?

LLM-as-judge 평가 (BYOK — 사용자의 API 키 사용, 절대 저장되지 않음):

구조화된 루브릭 (rubric)과 함께 심판 모델 (Claude, GPT-4o, Gemini, Groq 또는 Mistral)로 프롬프트를 전송합니다. 기준별 점수와 구체적인 제안을 반환합니다. 핵심 자료는 요청 페이로드 (request payload)에 주입된 후 Python 스코프에서 즉시 삭제되며, 데이터베이스나 로그에 절대 남지 않습니다.

승인이 진행되기 전 최소 평가 점수를 요구하도록 환경을 설정할 수 있습니다:

# environment config
eval_required = True
eval_pass_threshold = 7.0  # 10점 만점 기준
...

피해야 할 안티 패턴 (Anti-Patterns)

초기에 제가 실수하여 디버깅 시간을 낭비했던 몇 가지 사항입니다:

버전 목록에 joinedload를 사용하지 마세요

# 이는 모든 프롬프트에 대해 모든 버전의 콘텐츠를 로드합니다. 규모가 커지면 OOM(Out of Memory) 위험이 있습니다.
prompts = db.query(Prompt).options(joinedload(Prompt.versions)).all()

...

SQLAlchemy 컬럼 이름을 metadata로 지정하지 마세요

Metadata는 DeclarativeBase의 예약된 속성입니다. 이는 ORM 자체의 metadata 객체를 조용히 덮어쓰게 됩니다. extra, meta 또는 data와 같은 이름을 사용하세요.

SQLite에 pool_size를 전달하지 마세요

# SQLite에서는 TypeError가 발생합니다.
engine = create_engine(DATABASE_URL, pool_size=5)

...

LLM API 키를 데이터베이스에 저장하지 마세요

암호화된 상태라 하더라도 마찬가지입니다. 요청(request) 시에만 사용하고 즉시 스코프(scope)에서 삭제하세요. 팀 키(team keys)를 저장해야 한다면, 오직 환경 변수(env var)에서 가져온 키 재료를 사용하는 AES-256-GCM 방식을 사용해야 하며, 암호화할 때마다 새로운 12바이트 논스(nonce)를 생성하고 절대 재사용하지 마세요.

git clone https://github.com/PromptMatrix/promptmatrix.github.io
cd promptmatrix
./start.sh

start.sh는 가상 환경(venv)을 생성하고, 의존성(dependencies)을 설치하며, JWT_SECRET_KEY와 ENCRYPTION_KEY를 생성하고, Alembic 마이그레이션(migrations)을 실행하고, 로컬 관리자 사용자를 시드(seed)하며, 8000번 포트에서 uvicorn을 실행합니다.

http://localhost:8000/dashboard를 여세요 — 개발 모드(development mode)에서는 로그인 화면이 없습니다. 대시보드는 APP_ENV=development로 제한된 개발 바이패스(dev bypass)를 통해 직접 연결됩니다.

더 넓은 관점

프롬프트 관리(prompt management)에 관한 엔지니어링 규율은 애플리케이션 코드(application code)에 관한 엔지니어링 규율보다 약 2년 정도 뒤처져 있습니다. 우리는 여전히 "환경 변수(env var)에 넣기" 단계에 머물러 있으며, 이제 "버전 관리, 리뷰, 감사, 롤백 가능" 단계로 나아가야 합니다.

이것은 일차적으로 도구(tooling)의 문제가 아닙니다. 멘탈 모델(mental model)의 문제입니다. 프롬프트는 설정 값(config values)이 아니라, 행동 사양(behavioural specifications)입니다. 프롬프트는 그 위에서 실행되는 코드에 부여하는 것과 동일한 엄격함(rigour)을 누릴 자격이 있습니다.

제가 여기서 설명한 아키텍처 — 안정적인 키 레지스트리(key registry), 불변의 버전 히스토리(immutable version history), 리뷰 게이트(review gate), 런타임 서빙(runtime serving), 감사 추적(audit trail) — 는 주말 동안 직접 구축할 수도 있습니다. 또는 MIT 라이선스이며 로컬에서 무료로 실행되는 PromptMatrix를 사용할 수도 있습니다.

어떤 방식이든, 정답은 당신의 AI 행동(AI behaviour)을 파이썬 딕셔너리(Python dictionary) 안에 통제되지 않은 채로 방치하는 것이 아닙니다.

PromptMatrix는 오픈 소스입니다. GitHub: github.com/PromptMatrix/promptmatrix.github.io

팀 RBAC(역할 기반 액세스 제어) 및 LLM 평가 게이트(eval gating)를 갖춘 클라우드 버전: promptmatrix.github.io

아키텍처, SQLAlchemy 패턴, 또는 캐시 설계(cache design)에 대한 질문이 있다면 댓글로 남겨주세요. 모든 글을 읽고 있습니다.