Rails LLM 통합: Claude Code를 위한 LLM 호출 컨벤션

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Ruby on Rails 애플리케이션에서 LLM 기능을 통합할 때 발생하는 일관성 부족과 관리의 어려움을 해결하기 위한 새로운 컨벤션이 공개됐다. 기존의 Active Storage나 Action Mailer처럼 LLM 호출도 표준화된 패턴이 필요하다는 문제의식에서 출발하여, 서비스 객체, 비동기 작업, 프롬프트 템플릿 관리 등을 구조화했다. 특히 Claude Code가 이 컨벤션을 학습하여 코드를 생성할 수 있도록 돕는 'Claude Skill'을 통해 개발자는 비용 추적과 재시도 로직이 내장된 견고한 AI 기능을 일관되게 구현할 수 있다. 이 시스템은 ruby_llm, langchain-rb 등 주요 Ruby 라이브러리와 호환되며 프로덕션 환경에서의 실무 패턴을 반영한다.

배경

Ruby on Rails 프레임워크에 대한 숙련도, LLM API(OpenAI, Anthropic 등) 사용 경험, Claude Code CLI 도구에 대한 기본 지식

대상 독자

프로덕션 환경에서 AI 기능을 구현하고 유지보수하는 Ruby on Rails 개발자

의미 / 영향

Rails 커뮤니티에 LLM 통합을 위한 표준화된 아키텍처를 제시함으로써, AI 기능 개발의 진입 장벽을 낮추고 대규모 프로젝트에서의 유지보수성을 크게 향상시킬 것으로 기대된다.

섹션별 상세

Rails의 기존 컨벤션과 달리 LLM 호출에는 표준화된 방식이 없어 개발자마다 구현이 파편화되는 문제가 존재한다. 컨트롤러 내부에서 직접 API를 호출하는 방식은 재시도 로직 부재, 비용 추적 불가, 프롬프트 관리의 어려움 등 확장성 측면에서 한계를 드러낸다.

ruby

def create
  client = OpenAI::Client.new(access_token: ENV["OPENAI_API_KEY"])
  response = client.chat(parameters: {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Describe #{@product.name}" }]
  })
  @product.update!(description: response.dig("choices", 0, "message", "content"))
end

재시도 로직이나 비용 추적이 없는 기존의 비효율적인 LLM 호출 방식

제안된 컨벤션은 app/services/llm, app/jobs/llm, app/prompts와 같은 전용 디렉토리 구조를 사용하여 LLM 로직을 체계적으로 분리한다. config/llm.yml 파일을 통해 모델 라우팅과 예산 한도를 설정하며, 이는 Rails의 database.yml과 유사한 관리 방식을 제공한다.

ruby

LLM::GenerateDescriptionJob.perform_later(product_id: @product.id)

새로운 컨벤션을 적용하여 비동기 작업으로 LLM 처리를 위임하는 방식

text

app/
  services/llm/
    product_description_service.rb
    base_service.rb
  jobs/llm/
    generate_description_job.rb
  prompts/
    product_descriptions/
      generate.system.erb
      generate.text.erb
config/
  llm.yml

LLM 통합을 위해 제안된 Rails 프로젝트 디렉토리 구조

Claude Code를 위한 전용 Skill을 제공하여 AI 에이전트가 Rails의 베스트 프랙티스를 준수하는 코드를 자동 생성하도록 유도한다. 이를 통해 서비스 객체 생성, 비동기 처리, ERB 기반의 프롬프트 템플릿 버전 관리 등이 모든 개발자에게 일관되게 적용된다.

비즈니스 로직과 LLM 호출 로직을 분리하는 BaseService 패턴을 사용한다. BaseService는 추적(Tracing), 재시도(Retries), 비용 추적 기능을 상속하며, 실제 서비스 객체는 검증과 파싱 등 비즈니스 로직에만 집중할 수 있는 구조를 가진다.

다양한 Ruby LLM 라이브러리와의 호환성을 지원한다. ruby_llm은 RAG 및 ActiveRecord 통합에, langchain-rb는 벡터 검색 및 에이전트 구현에, ruby-openai와 anthropic-rb는 직접적인 API 호출에 권장되는 등 용도별 가이드를 포함한다.

실무 Takeaway

LLM 호출 로직을 컨트롤러에서 분리하여 전용 서비스 객체와 비동기 Job으로 구조화하면 시스템의 안정성과 확장성을 확보할 수 있다.
프롬프트를 코드 내 인라인 문자열이 아닌 app/prompts 폴더의 ERB 템플릿으로 관리하여 버전 제어와 테스트 용이성을 높여야 한다.
Claude Code와 같은 AI 코딩 에이전트 사용 시 프로젝트 고유의 컨벤션을 담은 Skill을 제공함으로써 생성되는 코드의 품질과 일관성을 보장할 수 있다.

언급된 리소스

GitHubRails LLM Integration GitHub Repository