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

섹션별 상세

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 호출에 권장되는 등 용도별 가이드를 포함한다.

용어 해설

클로드 코드(Claude Code): — Anthropic에서 개발한 CLI 기반의 AI 코딩 에이전트로, 전체 코드베이스를 이해하고 직접 코드를 작성, 실행, 수정하며 복잡한 개발 작업을 수행하는 도구이다.
서비스 객체(Service Object): — Rails 아키텍처에서 비즈니스 로직을 컨트롤러나 모델에서 분리하여 단일 목적을 수행하도록 캡슐화한 객체로, 코드의 재사용성과 테스트 용이성을 높이는 디자인 패턴이다.
ERB 템플릿(ERB Template): — Embedded Ruby의 약자로, 텍스트 파일 내에 Ruby 코드를 삽입하여 동적으로 내용을 생성하는 템플릿 엔진이다. 이 프로젝트에서는 프롬프트를 관리하는 데 사용된다.
검색 증강 생성(RAG): — 외부 데이터베이스에서 관련 정보를 검색하여 LLM의 입력 컨텍스트로 제공함으로써 모델이 학습하지 않은 최신 정보나 특정 도메인 지식에 기반해 답변하게 하는 기술이다.

기술

Ruby on Rails
Claude Code
ruby_llm
langchain-rb
OpenAI API
Anthropic API

활용 사례

AI 기반 제품 설명 자동 생성
고객 지원 티켓 자동 분류 서비스
Rails 기반 RAG 시스템 구축

언급된 리소스

GitHubRails LLM Integration GitHub Repository