도구: Zoom

등록: https://lu.ma/wav8tlek

github과 같이 hub에서 prompt를 관리할 수 있어서 수정을 해도 재배포 없이 바로 반영이 되고, tag로 관리가 돠어서 환경에 따라 다르게 설정할 수 있었거든요.

Mastra를 사용해서 vercel에 배포를 하며 겪게된 이슈는 prompt 관리가 편하지 않다는거였어요. 코딩을 어떻게 하느냐에에 따라 개발자 도구로 확인이 될 수 있다는 것도 있고요. 그래서 나만의 hub를 만들어서 prompt 관리를 하도록 구현을 해봤습니다.

실제로 서비스에 적용하기 위해서는 추가적인 edge case를 비롯하여 다듬어야 하는 부분이 많을 꺼라 생각합니다. 따라서 단지 참고용으로만 활용을 해주세요.

아울러 이 방법보다 더 효율적인 방법은 항상 있다고 생각을 합니다. 새로운 의견은 언제나 환영합니다!

핵심 아이디어

Prompt를 데이터베이스에 저장하고 버전별로 관리하는 시스템입니다. Prompt를 코드에서 분리해서 관리할 수 있어, 코드 배포 없이도 Prompt를 수정하고 실험할 수 있습니다.

주요 특징:

• Prompt를 데이터베이스에서 동적으로 load

• 버전별 관리로 안전한 rollback 가능

• Template 변수를 통한 동적 prompt 생성

데이터베이스 설정

PostgreSQL을 사용하는 경우 다음 스키마를 생성합니다:

-- Prompt Management System Schema
CREATE TABLE prompts (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(100) NOT NULL,
  content TEXT NOT NULL,
  version VARCHAR(20) DEFAULT '1.0.0',
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),

  -- Ensure unique name+version combinations
  CONSTRAINT prompts_name_version_unique UNIQUE (name, version)
);

-- Indexes for efficient querying
CREATE INDEX idx_prompts_name_created_at ON prompts (name, created_at DESC);
CREATE INDEX idx_prompts_active ON prompts (is_active) WHERE is_active = true;

PromptManager 구현

이제 prompt manager 클래스를 구현해보겠습니다:

export class PromptManager {
  private promptTemplate: string = '';
  private isLoaded: boolean = false;
  private templateVersion: string = '1.0.0';
  private templateId: string = '';
  private promptName: string = 'default_prompt';
  private db: any; // Database client

  constructor(dbClient: any, promptName?: string) {
    this.db = dbClient;
    this.promptName = promptName || process.env.PROMPT_NAME || 'default_prompt';
  }

  /**
   * Load prompt template from database
   * Supports: 'prompt_name' (latest) or 'prompt_name:uuid' (specific version)
   */
  async loadPromptTemplate(): Promise<void> {
    if (this.isLoaded) return;

    try {
      let query = this.db
        .from('prompts')
        .select('id, content, version, name')
        .eq('is_active', true);

      // Parse name:uuid format for specific version
      if (this.promptName.includes(':')) {
        const [name, uuid] = this.promptName.split(':');
        query = query.eq('name', name).eq('id', uuid);
      } else {
        // Get latest version
        query = query
          .eq('name', this.promptName)
          .order('created_at', { ascending: false })
          .limit(1);
      }

      const { data, error } = await query.single();

      if (error || !data) {
        throw new Error(`Prompt not found: ${this.promptName}`);
      }

      this.promptTemplate = data.content;
      this.templateVersion = data.version;
      this.templateId = data.id;
      this.promptName = data.name;
      this.isLoaded = true;

    } catch (error) {
      throw new Error(`Failed to load prompt: ${error}`);
    }
  }

  /**
   * Generate complete prompt with user input
   */
  async generatePrompt(userInput: any): Promise<string> {
    if (!this.isLoaded) {
      await this.loadPromptTemplate();
    }

    // Simple input processing
    const inputText = typeof userInput === 'string' 
      ? userInput 
      : JSON.stringify(userInput);

    return this.promptTemplate.replace('{user_input}', inputText);
  }

  /**
   * Get template information
   */
  getTemplateInfo() {
    return {
      name: this.promptName,
      version: this.templateVersion,
      id: this.templateId,
      isLoaded: this.isLoaded
    };
  }
}

버전 관리 방식

두 가지 방식으로 prompt를 load할 수 있습니다:

최신 버전 사용

// 'analysis_prompt'의 최신 버전을 자동으로 로드
const manager = new PromptManager(dbClient, 'analysis_prompt');

데이터베이스에서 created_at 기준으로 가장 최근에 생성된 버전을 가져옵니다.

특정 버전 고정

// 특정 UUID 버전을 고정해서 사용
const manager = new PromptManager(
  dbClient, 
  'analysis_prompt:550e8400-e29b-41d4-a716-446655440000'
);

name:uuid 형태로 지정하면 특정 버전을 고정해서 사용할 수 있습니다. 이는 Production 환경에서 안정성을 보장할 때 유용합니다.

동작 과정

1. 지연 로딩 (Lazy Loading)

PromptManager는 생성 시점에는 데이터베이스 연결만 설정하고, 실제 프롬프트 로딩은 generatePrompt() 호출 시까지 지연합니다. 이를 통해 불필요한 데이터베이스 호출을 방지합니다.

2. 템플릿 변수 치환

Load된 prompt에서 {user_input} 같은 template 변수를 실제 사용자 입력으로 치환합니다:

// 데이터베이스의 템플릿
"다음 데이터를 분석해주세요: {user_input}"

// 치환 후 결과  
"다음 데이터를 분석해주세요: 2024년 매출 데이터"

3. 캐싱

한 번 load된 prompt는 isLoaded flag로 관리되어 중복 loading을 방지합니다.

사용 예시

기본 사용법

const manager = new PromptManager(dbClient, 'analysis_prompt');

// 프롬프트 생성 (자동으로 DB에서 로드)
const completedPrompt = await manager.generatePrompt({
  query: "분기별 매출 분석",
  context: "전년 대비 성장률 포함"
});

버전 정보 확인

await manager.loadPromptTemplate();
const info = manager.getTemplateInfo();

console.log(`Using ${info.name} v${info.version} (${info.id})`);
// Output: Using analysis_prompt v2.1.0 (550e8400-e29b-41d4-a716-446655440000)

..

왜 Mastra.ai인가요?

LangChain에서 LangGraph로 넘어오면서 매번 Python으로 개발해야 하는 불편함을 겪어보셨나요? 저도 마찬가지였습니다. 그러던 중 TypeScript 기반의 Mastra.ai를 발견하게 되었고, 이는 정말 게임 체인저였습니다.

Mastra.ai는 LangGraph의 모든 기능을 대체하지는 못하지만, 실제 서비스 개발에 필요한 핵심 기능들을 우아하게 제공합니다:

• 🔄 워크플로우: 그래프 기반의 직관적인 LLM 호출 체인

• 🤖 에이전트: 메모리와 도구 호출이 가능한 스마트 AI 에이전트

• 📚 RAG: 문서 처리부터 벡터 검색까지 완벽한 RAG 파이프라인

• 🔧 개발 환경: 로컬에서 에이전트와 실시간 채팅하며 디버깅

• ☁️ 배포: Vercel, Cloudflare Workers 등 서버리스 플랫폼 완벽 지원

• 📊 평가: 내장된 Evals로 AI 결과물의 품질 자동 측정

MKUG를 시작하는 이유

현재 Mastra에 대한 한국어 자료는 매우 제한적입니다. 공식 문서는 영어와 일본어만 제공되고, 한국 개발자 커뮤니티에서 관련 정보를 찾기가 어려운 실정입니다.

하지만 이 혁신적인 프레임워크가 가진 잠재력은 너무나 매력적입니다. TypeScript로 AI 애플리케이션을 빠르고 안정적으로 개발할 수 있다는 것, 복잡한 Python 환경 설정 없이도 강력한 AI 기능을 구현할 수 있다는 것은 분명 많은 한국 개발자들에게도 큰 도움이 될 것입니다.

계획하고 있는 것들

MKUG를 통해 다음과 같은 가치 있는 콘텐츠를 지속적으로 제공하려고 합니다:

• 📖 완전한 한글 문서화: Mastra 공식 문서의 한글화

• 💡 실전 사용법: 단계별 tutorial과 best practice

• 📰 최신 소식: Mastra 업데이트와 생태계 동향

• 🎯 Use case: 실제 프로젝트에 적용 가능한 구체적인 예시들

함께 성장하는 공간을 꿈꾸며

지금은 작게 시작하는 프로젝트이지만 언젠가는 Mastra에 관심 있는 한국 개발자들이 모여 함께 배우고 성장하는 커뮤니티로 발전하기를 희망합니다.

여러분의 관심과 참여가 이 작은 시작을 의미 있는 공간으로 만들어갈 것입니다.

Mastra와 함께 새로운 AI 개발의 여정을 시작해보세요! 🌟

우선 단순 번역을 시작으로 한국 개발자들의 개발 환경과 니즈에 맞는 실용적인 가이드로 재탄생시킬 생각입니다.

비정기적인 활동을 통해 점진적으로 번역이 진행될 예정입니다만 지속적인 관심과 피드백 부탁드립니다.

한글화 프로젝트

• 번역 시작일: 2025년 7월 26일

• 진행 방식: 비정기적 개인 활동을 통한 점진적 번역

Mastra.ai Docs 한글

• Docs 보러가기