본문으로 건너뛰기

프롬프트 정본을 코드 상수에서 Langfuse로 옮긴다

  • 상태: 채택됨
  • 작성일: 2026-07-23
  • 관련 문서: ADR-0009, APP-129, APP-130, APP-132, APP-292

맥락​

프롬프트 지시문 6개(chat/meeting·chat/note·chat/workspace·analysis/overview· analysis/action_items·analysis/insights)가 코드에 상수로 박혀 있었다. 프롬프트를 고치려면 배포가 필요했다. 버전별 품질 비교도 안 된다.

결정​

  • 6개를 Langfuse 프롬프트로 올리고 런타임에 당겨 쓴다.
  • 게이트는 로더 하나다. resolve_prompt(name, fallback, settings)가 Langfuse 키가 있으면 get_prompt(..., fallback=<코드상수>)를 주고, 없으면 코드 상수 그대로를 준다. 관측 도구가 살아 있어야 서비스가 뜨는 구조는 만들지 않는다.
  • 등록 스크립트가 같은 코드 상수를 Langfuse로 밀어 두 곳이 안 갈리게 한다.
  • langfuse import는 infrastructure에만 두고 domain·application에서는 import-linter forbidden 계약으로 금지한다.

대안​

대안 1 — 코드 상수만 유지. 정본이 한 곳이고 배포와 함께 버전이 고정된다. 기각한 이유: 프롬프트를 고칠 때마다 배포가 따라붙는다. 버전 델타도 못 본다.

대안 2 — Langfuse만 정본으로 (fallback 없음). 정본이 한 곳이라 드리프트가 없다. 기각한 이유: Langfuse가 죽거나 키가 없는 환경(개발·테스트)에서 서비스가 아예 안 뜬다.

결과​

  • 프롬프트를 고치는 데 배포가 필요 없다. 버전별 품질 비교도 열렸다.
  • Langfuse가 죽어도, 키가 없는 개발·테스트 환경에서도 서비스가 뜬다.
  • 프롬프트 지시문에 변수가 없어(전사·목록은 CachedPrompt.prefix로 이미 분리) get_langchain_prompt() 변환은 하지 않아도 됐다. trace ↔ 프롬프트 버전 링크는 APP-132에서 붙었다.
  • 프롬프트 정본이 두 곳(코드 상수·Langfuse production 라벨)에 존재한다. 등록 스크립트로 밀어도 UI에서 고치는 순간 갈라진다. 그 드리프트가 새 문제로 남아 APP-292로 따로 팠다.
  • 실행 프롬프트가 런타임 외부 조회에 의존하게 됐다.