프롬프트 버전 관리 시스템 도입기

문제 상황

최근 프로젝트에 Claude API를 활용한 기능이 10개 이상 추가되었다. 초기엔 코드 내에 프롬프트를 하드코딩했는데, 문제가 생겼다.

• 프롬프트 수정 시 배포 필요
• A/B 테스트 불가능
• 변경 이력 추적 어려움
• 팀원 간 프롬프트 공유 비효율

해결 방안

프롬프트를 별도 저장소로 분리하고 버전 관리 시스템을 만들었다.

1. 파일 기반 구조

// prompts/summarize/v1.md
system: 다음 텍스트를 3문장으로 요약해주세요.
temperature: 0.3
max_tokens: 500

2. 로더 구현

class PromptLoader {
  private cache = new Map();
  
  async load(name: string, version = 'latest') {
    const key = `${name}:${version}`;
    if (this.cache.has(key)) return this.cache.get(key);
    
    const path = version === 'latest' 
      ? await this.getLatestVersion(name)
      : `prompts/${name}/${version}.md`;
    
    const content = await fs.readFile(path, 'utf-8');
    const parsed = this.parse(content);
    this.cache.set(key, parsed);
    return parsed;
  }
}

3. 사용 예시

const promptLoader = new PromptLoader();
const prompt = await promptLoader.load('summarize', 'v2');

const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20250219',
  ...prompt.config,
  messages: [{ role: 'user', content: userInput }]
});

추가 개선

• Git으로 변경 이력 관리
• Notion에 프롬프트 문서화
• 환경별(dev/prod) 프롬프트 분리
• 성능 메트릭 수집 (응답 시간, 토큰 사용량)

배포 없이 프롬프트만 수정 가능해져서 실험 속도가 빨라졌다. 다만 캐싱 전략은 더 고민이 필요하다.