rails-ai-context

AI 코딩 어시스턴트에게 Rails 앱에 대한 정확한 정보를 제공하세요

:star: 이 젬이 수정 반복을 줄여줬다면 GitHub에서 스타를 눌러주세요!

왜 필요한가 • 기능 • 시작하기 • 사용법 • 도구 • 설정 • 문서

rails-ai-context는 Rails 앱을 AI 코딩 어시스턴트의 정보 원천으로 만들어주는 Ruby 젬입니다. 어시스턴트가 학습 데이터에서 스키마, 연관 관계, 라우트, 컨벤션을 추측하는 대신, 앱에 직접 묻습니다: MCP를 통해 제공되거나 CLI에서 실행되는 45개의 읽기 전용 도구, 그리고 Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI용으로 생성된 컨텍스트 파일까지 제공합니다.

[!TIP] 원하지 않으면 Gemfile에 추가할 필요가 없습니다. gem install rails-ai-context 후 Rails 앱 안에서 rails-ai-context init을 실행하세요. 부팅되지 않는 앱에서도 작동합니다: --no-boot를 전달하면 모든 도구가 소스 파일에서 답을 얻습니다.

왜 필요한가

어시스턴트가 이런 실수를 하는 것을 본 적이 있을 것입니다:

• 이미 존재하는 컬럼에 대한 마이그레이션을 작성한다.

• 연관 관계가 user.articles인데 user.posts를 호출한다.

• fixture 기반 테스트 스위트에서 FactoryBot으로 테스트를 스캐폴딩한다.

• 부모 컨트롤러에서 상속된 before_action을 놓치고, 인증이 왜 실패하는지 의아해한다.

• 이미 있는 젬을 추가하거나, 없는 젬의 API를 호출한다.

• 코드베이스에 없는 메서드를 지어낸다.

그걸 발견하고, 고치고, 다시 프롬프트를 주면, 그 옆에 있는 다른 것이 깨집니다. 토큰은 저렴하지만, 수정 반복이 오후를 통째로 잡아먹는 원인입니다. 이 젬은 추측의 원천을 제거합니다.

Related MCP server: Synapse

기능

• 45개의 읽기 전용 도구 — 스키마, 모델, 컨트롤러, 라우트, 뷰, Stimulus, Turbo, 잡, 서비스, 메일러, i18n, 젬, 설정, 테스트, 보안, 성능 등. 모든 답변은 앱에서 나옵니다.

• Prism AST 파싱 기반 모델 인트로스펙션. 각 결과에는 [VERIFIED] 또는 [INFERRED]가 표시되어 어시스턴트가 무엇이 확정 정보이고 무엇이 런타임 확인이 필요한지 알 수 있습니다.

• 세 가지 접근 방식: stdio 기반 MCP, Rails 앱 내부에 마운트된 HTTP 기반 MCP, 또는 어떤 터미널에서든 사용 가능한 일반 CLI.

• 생성된 컨텍스트 파일 — Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI용. 각 도구가 프로젝트를 열 때 자동 감지하는 MCP 설정이 포함됩니다.

• 라이브 리소스: rails:// 및 rails-ai-context:// URI — 읽을 때마다 새로 인트로스펙션합니다.

• 환각 방지 규칙 — 모든 생성된 컨텍스트 파일에 기본으로 포함됩니다.

• 정적 계층: 앱을 부팅할 수 없을 때 도구가 config/routes.rb, db/schema.rb, 마이그레이션, 소스 파일에서 답을 얻고 그 사실을 명시합니다.

• 실제 앱 구조 지원: packwerk 팩, 저장소 내 엔진, 멀티 데이터베이스 스키마 덤프, Mongoid, API 전용 앱.

• 커스텀 도구: 내장 도구 옆에 자신만의 MCP::Tool 클래스를 등록하고 번들된 TestHelper로 테스트할 수 있습니다.

시작하기

요구 사항

• Ruby 3.1 이상

• Rails 7.0 이상

• 선택 사항: security_scan용 brakeman, watch용 listen, 더 빠른 search_code용 ripgrep

Gemfile에 설치

bundle add rails-ai-context --group development
rails generate rails_ai_context:install

생성기는 어떤 AI 도구를 사용하는지, MCP 모드와 CLI 모드 중 무엇을 원하는지 묻고, 컨텍스트 파일, 각 도구의 MCP 설정, config/initializers/rails_ai_context.rb를 작성합니다. 다시 실행해도 안전합니다. 기존 설정은 유지하고 누락된 것만 추가합니다.

독립 설치

gem install rails-ai-context
cd your-rails-app
rails-ai-context init
rails-ai-context serve

Gemfile 변경 없음. 설정은 .rails-ai-context.yml에 저장됩니다. rbenv, rvm, asdf, mise, chruby, 시스템 Ruby와 호환됩니다. 독립 설치 참조.

작동 확인

rails ai:doctor                                  # in-Gemfile: readiness score + diagnostics
rails-ai-context doctor                          # standalone

rails 'ai:tool[schema]' table=users
rails 'ai:tool[model_details]' model=User
rails 'ai:tool[search_code]' pattern=publishable? match_type=trace

그런 다음 프로젝트를 AI 도구에서 엽니다. 작성된 MCP 설정은 열 때 자동으로 인식되며, 어시스턴트는 추측하는 대신 rails_get_model_details 호출을 시작합니다.

[!NOTE] 위 CLI 명령은 사용자를 위한 것입니다. MCP가 연결되면 어시스턴트가 동일한 도구를 직접 호출하므로 직접 입력할 필요가 없습니다.

사용법

stdio 기반 MCP

기본값입니다. 각 AI 도구는 자체 설정 파일(.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml)을 가지며 다음을 가리킵니다:

rails ai:serve             # in-Gemfile
rails-ai-context serve     # standalone

HTTP 기반 MCP

앱 내부에 서버를 마운트합니다. 라우팅, 인증, 미들웨어를 상속하며 별도 프로세스가 필요 없습니다.

# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp"

클라이언트를 http://localhost:3000/mcp로 지정하세요. 독립 HTTP 프로세스도 있습니다: rails-ai-context serve --transport http --port 6029.

[!WARNING] SSE 채널을 여는 각 연결 클라이언트는 연결 수명 동안 서버 스레드 하나를 점유합니다. 개발 환경에서는 문제없지만, 여러 클라이언트가 앱을 공유한다면 Puma의 스레드 수를 늘리거나 독립 HTTP 프로세스를 사용하세요.

CLI

동일한 45개 도구, 서버 없이, 어떤 터미널에서든 사용 가능.

rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
rails-ai-context tool schema --table users --detail full

도구 이름은 유연하게 해석됩니다: schema, get_schema, rails_get_schema 모두 작동합니다. 대부분의 도구는 detail=summary|standard|full을 받습니다.

명령어

앱 읽기 명령어의 공통 플래그: --app-path PATH로 다른 디렉터리 지정, --environment ENV로 RAILS_ENV 설정, --no-boot로 부팅 시도를 건너뛰고 소스에서 답을 얻습니다. 전체 목록은 CLI 참조에 있습니다.

도구

모든 도구는 읽기 전용이며 앱에서 답을 얻습니다.

첫날 알아두면 좋은 몇 가지:

• match_type=trace와 함께 search_code를 사용하면 정의, 소스, 유형별로 그룹화된 모든 호출자, 그리고 테스트를 한 번의 호출로 반환합니다. 이는 파일 읽기 4~5회를 대체합니다.

• get_controllers는 상속된 필터, strong params, 렌더 맵을 포함한 액션 소스를 반환합니다.

• get_model_details는 AST에서 연관, 검증, 스코프, enum, 매크로를 반환하며, 각각은 [VERIFIED] 또는 [INFERRED]로 태그됩니다.

• query는 타임아웃, 행 제한, 열 마스킹을 적용한 읽기 전용 SQL을 실행합니다. read_logs는 민감한 데이터가 프로세스를 벗어나기 전에 마스킹합니다.

45개 도구 전체의 매개변수는 도구 참조에, 실제 작업 예제는 레시피에 있습니다.

실시간 리소스

MCP 클라이언트는 리소스 형태로 구조화된 데이터도 읽을 수 있습니다. 템플릿은 매 요청마다 최신 상태로 인트로스펙션합니다.

추가로 9개의 정적 리소스가 있습니다: rails://schema, routes, conventions, gems, controllers, config, tests, migrations, engines.

환각 방지 규칙

생성되는 모든 컨텍스트 파일(CLAUDE.md, .cursor/rules/, .github/instructions/, AGENTS.md)에는 코드를 작성하기 전에 어시스턴트가 읽는 여섯 가지 규칙이 포함됩니다.

1. 쓰기 전에 검증하세요. 이번 턴에서 호출한 도구가 확인하지 않은 열, 연관, 라우트, 헬퍼, 메서드, 클래스, 파셜, gem을 참조하지 마세요.

2. 모든 가정은 [ASSUMPTION]으로 표시하세요. "X를 먼저 확인해야 한다"는 좋은 답입니다.

3. 학습 데이터는 평범한 Rails를 설명합니다. 이 앱은 평범하지 않습니다. 뭔가 명백히 표준적으로 느껴도 어쨌든 쿼리하세요.

4. 편집할 때마다 상속 체인을 확인하세요: 상속 필터, concerns, includes, STI 부모.

5. 빈 도구 출력은 정보입니다. "0 callers found"는 조사하라는 의미이지 진행하라는 의미가 아닙니다.

6. 오래된 컨텍스트는 거짓말입니다. 쓰기 후에는 다시 쿼리하세요.

기본으로 활성화되어 있습니다. 자체 규칙을 선호한다면 config.anti_hallucination_rules = false로 끄면 됩니다.

앱을 부팅할 수 없을 때

rails-ai-context는 실시간 반영을 위해 전체 부팅을 시도합니다. 부팅이 실패하면(ENV 변수 누락, 연결할 수 없는 서비스, 손상된 초기화자) 앱 읽기 명령은 종료하는 대신 정적 계층으로 대체됩니다: 라우트는 config/routes.rb, 스키마는 db/schema.rb, db/structure.sql 또는 마이그레이션, 모델과 컨트롤러는 해당 소스 파일에서 읽습니다. 모든 응답에는 저하 사항을 알리는 배너가 포함되고, 정적 데이터는 [STATIC]으로 태그되며, 부팅된 앱이 필요한 섹션은 사유와 함께 [UNAVAILABLE]을 보고합니다.

--no-boot는 부팅 시도를 완전히 건너뛰어 빠르고 부팅 시 부작용이 없습니다. doctor는 여전히 부팅 가능한 앱이 필요합니다. 부팅 상태 진단이 그것의 역할입니다.

코드는 일반적인 레이아웃, packwerk 팩(packs/*/app/*), 저장소 내 엔진(engines/*/app/*), 그리고 .rails-ai-context.yml의 extra_app_paths에서 찾습니다. 멀티 데이터베이스 스키마 덤프(db/queue_schema.rb 등)는 Secondary databases 섹션 아래에 표시됩니다. Mongoid 앱은 빈 테이블 대신 [UNAVAILABLE] 스키마 신호와 정적 모델 데이터를 받으며, API 전용 앱은 조용한 내부 대신 뷰 및 프론트엔드 도구에서 "해당 사항 없음"을 받습니다. 자세한 내용은 호필성에서 확인하세요.

구성

# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext)
  RailsAiContext.configure do |config|
    config.ai_tools  = %i[claude cursor]   # which AI tools to generate for
    config.tool_mode = :mcp                # :mcp (default) or :cli
    config.preset    = :full               # :full (40 introspectors) or :standard (17)
  end
end

독립 실행 설치는 .rails-ai-context.yml에 동일한 키를 사용합니다. 기본값이 있는 모든 옵션은 구성에 있습니다.

사용자 지정 도구

내장 도구와 함께 자신만의 도구를 등록하세요.

# app/mcp_tools/rails_get_business_metrics.rb
class RailsGetBusinessMetrics < MCP::Tool
  tool_name "rails_get_business_metrics"
  description "Key business metrics for this app"

  def call(period: "week")
    MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
  end
end

# config/initializers/rails_ai_context.rb
config.custom_tools = ["RailsGetBusinessMetrics"]

번들된 헬퍼(RSpec 또는 Minitest)로 테스트하세요.

include RailsAiContext::TestHelper

response = execute_tool("business_metrics", period: "month")
assert_tool_response_includes(response, "Users")

사용자 지정 도구 문서를 참고하세요.

관측 가능성

모든 MCP 호출은 ActiveSupport::Notifications 이벤트를 발생시킵니다.

ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
  ms = (event.payload[:duration].to_f * 1000).round
  Rails.logger.info "[MCP] #{event.payload[:tool_name]} #{ms}ms"
end

작동 방식

graph TD
    A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
    B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
    B --> C["MCP server\nstdio / HTTP\n45 tools · 5 templates · 9 resources"]
    B --> D["CLI\nrake / Thor\nsame 45 tools"]
    B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]

    style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
    style B fill:#2d2d2d,stroke:#555,color:#fff
    style C fill:#0984e3,stroke:#0770c2,color:#fff
    style D fill:#00cec9,stroke:#00b5b0,color:#fff
    style E fill:#a29bfe,stroke:#8c83f0,color:#fff

내부 구조, 인트로스펙터 목록 및 AST 엔진은 아키텍처와 인트로스펙터에 있습니다.

문서

프로덕션에서 10년 이상의 경험을 가진 Rails 개발자가 만들었습니다. 시간을 절약해 준다면 프로젝트 후원을 고려해 보세요.