10장: 프로덕션 프롬프트 관리 - 버전 관리와 CI/CD

prompts/
  customer-support/
    system.txt              # 시스템 프롬프트
    classify-intent.txt     # 의도 분류 프롬프트
    generate-response.txt   # 응답 생성 프롬프트
    tests/
      classify-intent.yaml  # 테스트 케이스
      generate-response.yaml
    CHANGELOG.md
  code-review/
    system.txt
    analyze.txt
    tests/
      analyze.yaml
    CHANGELOG.md
  config/
    models.yaml             # 모델 설정
    environments.yaml       # 환경별 설정
  scripts/
    evaluate.py             # 평가 스크립트
    deploy.py               # 배포 스크립트

MAJOR.MINOR.PATCH
 
MAJOR: 출력 형식 변경, 호환되지 않는 변경
  예: JSON 스키마 필드 추가/삭제, 분류 카테고리 변경
 
MINOR: 기능 추가, 하위 호환 유지
  예: 새로운 엣지 케이스 처리, 성능 개선
 
PATCH: 버그 수정, 미세 조정
  예: 오타 수정, 표현 개선

# prompts/loader.py
from pathlib import Path
from typing import Optional
 
class PromptManager:
    """Git 저장소에서 프롬프트를 로드하고 관리합니다."""
    
    def __init__(self, prompts_dir: str = "prompts"):
        self.base_path = Path(prompts_dir)
    
    def load(
        self,
        domain: str,
        name: str,
        variables: Optional[dict] = None
    ) -> str:
        """프롬프트를 로드하고 변수를 치환합니다."""
        path = self.base_path / domain / (name + ".txt")
        
        if not path.exists():
            raise FileNotFoundError(
                "프롬프트를 찾을 수 없습니다: " + str(path)
            )
        
        template = path.read_text(encoding="utf-8")
        
        if variables:
            for key, value in variables.items():
                template = template.replace(
                    "{{" + key + "}}", str(value)
                )
        
        return template
    
    def list_prompts(self, domain: str) -> list[str]:
        """특정 도메인의 모든 프롬프트를 나열합니다."""
        domain_path = self.base_path / domain
        return [
            p.stem for p in domain_path.glob("*.txt")
        ]
 
# 사용 예시
manager = PromptManager()
system_prompt = manager.load("customer-support", "system")
classify_prompt = manager.load(
    "customer-support",
    "classify-intent",
    variables={"user_message": "배송이 언제 오나요?"}
)

# prompts/customer-support/CHANGELOG.md
 
## [2.1.0] - 2026-04-04
### 추가
- classify-intent: "계정 문의" 카테고리 신규 추가
- generate-response: 다국어 응답 지원 (한국어, 영어)
 
### 변경
- system: 응답 길이 가이드라인 200단어에서 150단어로 축소
- classify-intent: 경계 사례 처리 규칙 보강
 
### 수정
- generate-response: 인사말 누락 버그 수정
 
## [2.0.0] - 2026-03-20
### BREAKING
- classify-intent: 출력 형식이 텍스트에서 JSON으로 변경
- 기존 파싱 로직 업데이트 필요

# .github/workflows/prompt-ci.yml
name: Prompt CI/CD
 
on:
  pull_request:
    paths:
      - 'prompts/**'
  push:
    branches: [main]
    paths:
      - 'prompts/**'
 
jobs:
  test:
    name: 프롬프트 테스트
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Node.js 설치
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Promptfoo 설치
        run: npm install -g promptfoo
      
      - name: 변경된 프롬프트 감지
        id: changes
        run: |
          CHANGED=$(git diff --name-only origin/main -- prompts/)
          echo "changed=$CHANGED" >> $GITHUB_OUTPUT
      
      - name: 테스트 실행
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 변경된 프롬프트에 대해서만 테스트 실행
          for dir in prompts/*/; do
            if [ -f "$dir/tests/"*.yaml ]; then
              echo "테스트 실행: $dir"
              cd "$dir" && promptfoo eval && cd -
            fi
          done
      
      - name: 테스트 결과 업로드
        uses: actions/upload-artifact@v4
        with:
          name: prompt-test-results
          path: prompts/**/output/
 
  compare:
    name: 프롬프트 비교
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    needs: test
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: 이전 버전과 비교
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 현재 버전과 main 브랜치 버전을 비교
          python scripts/compare_versions.py
      
      - name: PR에 비교 결과 코멘트
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('comparison-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });
 
  deploy:
    name: 프롬프트 배포
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      
      - name: 프로덕션 배포
        run: python scripts/deploy.py --env production

# scripts/deploy.py
import json
import sys
from pathlib import Path
 
def check_test_results(prompts_dir: str) -> bool:
    """모든 테스트가 통과했는지 확인합니다."""
    results_dir = Path(prompts_dir)
    all_passed = True
    
    for result_file in results_dir.rglob("output/*.json"):
        results = json.loads(result_file.read_text())
        pass_rate = results.get("stats", {}).get("passRate", 0)
        
        if pass_rate < 0.95:  # 95% 이상 통과 필수
            print(
                "테스트 실패: " + str(result_file)
                + " (통과율: " + str(round(pass_rate * 100, 1)) + "%)"
            )
            all_passed = False
    
    return all_passed
 
def deploy(env: str):
    """프롬프트를 지정된 환경에 배포합니다."""
    if not check_test_results("prompts"):
        print("테스트 미통과. 배포를 중단합니다.")
        sys.exit(1)
    
    print("환경: " + env + " 배포를 시작합니다.")
    # 실제 배포 로직 (S3 업로드, 설정 서버 업데이트 등)
 
if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("--env", default="staging")
    args = parser.parse_args()
    deploy(args.env)

# prompts/config/environments.yaml
development:
  model: claude-haiku-4-5-20250514
  temperature: 0.3
  max_tokens: 1024
  debug: true
  log_prompts: true
 
staging:
  model: claude-sonnet-4-5-20250514
  temperature: 0.1
  max_tokens: 2048
  debug: false
  log_prompts: true
 
production:
  model: claude-sonnet-4-5-20250514
  temperature: 0.0
  max_tokens: 2048
  debug: false
  log_prompts: false  # 개인정보 보호

import yaml
import os
 
class EnvironmentAwarePromptManager(PromptManager):
    """환경에 따라 다른 설정으로 프롬프트를 로드합니다."""
    
    def __init__(self, prompts_dir: str = "prompts"):
        super().__init__(prompts_dir)
        self.env = os.getenv("PROMPT_ENV", "development")
        self.config = self._load_env_config()
    
    def _load_env_config(self) -> dict:
        config_path = self.base_path / "config" / "environments.yaml"
        with open(config_path) as f:
            all_config = yaml.safe_load(f)
        return all_config.get(self.env, all_config["development"])
    
    def get_model_config(self) -> dict:
        """현재 환경의 모델 설정을 반환합니다."""
        return {
            "model": self.config["model"],
            "temperature": self.config["temperature"],
            "max_tokens": self.config["max_tokens"],
        }

import hashlib
 
class CanaryDeployer:
    """프롬프트의 카나리 배포를 관리합니다."""
    
    def __init__(self):
        self.rollout_percentage = 0  # 0-100
        self.canary_prompt = None
        self.stable_prompt = None
    
    def set_canary(
        self,
        stable_prompt: str,
        canary_prompt: str,
        percentage: int
    ):
        """카나리 배포를 설정합니다."""
        self.stable_prompt = stable_prompt
        self.canary_prompt = canary_prompt
        self.rollout_percentage = percentage
    
    def get_prompt(self, user_id: str) -> tuple[str, str]:
        """사용자에 대한 프롬프트와 그룹을 반환합니다."""
        # 결정적 할당: 같은 사용자는 항상 같은 그룹
        hash_value = int(
            hashlib.md5(user_id.encode()).hexdigest(), 16
        ) % 100
        
        if hash_value < self.rollout_percentage and self.canary_prompt:
            return self.canary_prompt, "canary"
        return self.stable_prompt, "stable"
 
# 사용 예시
deployer = CanaryDeployer()
deployer.set_canary(
    stable_prompt=load_prompt("v1.0"),
    canary_prompt=load_prompt("v2.0"),
    percentage=5  # 5%에게만 새 프롬프트 적용
)
 
prompt, group = deployer.get_prompt(user_id="user123")
# 메트릭에 group 정보를 기록하여 비교 분석

class CostTracker:
    """프롬프트별 비용을 추적합니다."""
    
    # 모델별 토큰당 비용 (USD, 2026년 기준 예시)
    PRICING = {
        "claude-sonnet-4-5-20250514": {
            "input": 3.0 / 1_000_000,
            "output": 15.0 / 1_000_000,
            "cache_read": 0.3 / 1_000_000,
        },
        "claude-haiku-4-5-20250514": {
            "input": 0.8 / 1_000_000,
            "output": 4.0 / 1_000_000,
            "cache_read": 0.08 / 1_000_000,
        },
    }
    
    def estimate_cost(
        self,
        prompt: str,
        model: str,
        expected_output_tokens: int = 500,
        cached_tokens: int = 0
    ) -> dict:
        """프롬프트의 예상 비용을 계산합니다."""
        pricing = self.PRICING.get(model, {})
        
        # 대략적 토큰 추정 (한국어: 글자당 약 1.5 토큰)
        input_tokens = len(prompt) * 1.5
        non_cached = max(0, input_tokens - cached_tokens)
        
        input_cost = non_cached * pricing.get("input", 0)
        cache_cost = cached_tokens * pricing.get("cache_read", 0)
        output_cost = expected_output_tokens * pricing.get("output", 0)
        
        total = input_cost + cache_cost + output_cost
        
        return {
            "input_tokens": int(input_tokens),
            "cached_tokens": cached_tokens,
            "output_tokens": expected_output_tokens,
            "input_cost_usd": round(input_cost, 6),
            "cache_cost_usd": round(cache_cost, 6),
            "output_cost_usd": round(output_cost, 6),
            "total_cost_usd": round(total, 6),
        }
    
    def compare_prompts(
        self,
        prompt_a: str,
        prompt_b: str,
        model: str,
        daily_calls: int = 10000
    ) -> dict:
        """두 프롬프트의 일일 비용을 비교합니다."""
        cost_a = self.estimate_cost(prompt_a, model)
        cost_b = self.estimate_cost(prompt_b, model)
        
        daily_a = cost_a["total_cost_usd"] * daily_calls
        daily_b = cost_b["total_cost_usd"] * daily_calls
        
        return {
            "prompt_a_daily": round(daily_a, 2),
            "prompt_b_daily": round(daily_b, 2),
            "difference": round(daily_b - daily_a, 2),
            "percentage_change": round(
                (daily_b - daily_a) / daily_a * 100, 1
            ) if daily_a > 0 else 0
        }