rails-ai-context

Дайте вашему ИИ-ассистенту по коду достоверные данные о вашем Rails-приложении

:star: Если этот гем сэкономил вам цикл исправлений, поставьте звезду на GitHub!

Зачем • Возможности • Начало работы • Использование • Инструменты • Конфигурация • Документация

rails-ai-context — это Ruby-гем, который превращает ваше Rails-приложение в источник истины для ИИ-ассистентов по коду. Вместо того чтобы угадывать вашу схему, ассоциации, маршруты и соглашения по обучающим данным, ассистент спрашивает ваше приложение: 45 инструментов только для чтения, доступных через MCP или из CLI, плюс сгенерированные контекстные файлы для Claude Code, Cursor, GitHub Copilot, OpenCode и Codex CLI.

[!TIP] Ничего не нужно добавлять в Gemfile, если не хотите. gem install rails-ai-context, затем rails-ai-context init внутри любого Rails-приложения. Он также работает с приложением, которое не запускается: передайте --no-boot, и каждый инструмент будет отвечать на основе исходных файлов.

Зачем

Вы видели, как ваш ассистент делает следующее:

• Пишет миграцию для колонки, которая уже существует.

• Вызывает user.posts, когда ассоциация — user.articles.

• Генерирует тесты с FactoryBot в наборе, основанном на фикстурах.

• Пропускает before_action, унаследованный от родительского контроллера, а затем удивляется, почему не работает аутентификация.

• Добавляет гем, который у вас уже есть, или вызывает API из того, которого нет.

• Выдумывает метод, которого нет в кодовой базе.

Вы замечаете это, исправляете, повторяете запрос, и что-то рядом ломается. Токены дёшевы; цикл исправлений — вот что стоит вам полдня. Этот гем устраняет догадки в самом источнике.

Related MCP server: Synapse

Возможности

• 45 инструментов только для чтения для схемы, моделей, контроллеров, маршрутов, представлений, Stimulus, Turbo, задач, сервисов, почтовиков, i18n, гемов, конфигурации, тестов, безопасности, производительности и многого другого. Каждый ответ исходит из вашего приложения.

• Разбор Prism AST для интроспекции моделей. Каждый результат несёт [VERIFIED] или [INFERRED], чтобы ассистент знал, что является достоверным фактом, а что требует проверки в рантайме.

• Три способа подключения: MCP через stdio, MCP, встроенный в ваше Rails-приложение через HTTP, или обычный CLI в любом терминале.

• Сгенерированные контекстные файлы для Claude Code, Cursor, GitHub Copilot, OpenCode и Codex CLI, с конфигурацией MCP, которую каждый инструмент автоматически определяет при открытии проекта.

• Живые ресурсы: URI rails:// и rails-ai-context://, которые выполняют интроспекцию заново при каждом чтении.

• Правила против галлюцинаций, включённые в каждый сгенерированный контекстный файл, по умолчанию активны.

• Статический уровень: когда приложение не может запуститься, инструменты отвечают на основе config/routes.rb, db/schema.rb, миграций и исходных файлов и сообщают об этом.

• Работает с реальными структурами приложений: пакеты packwerk, движки внутри репозитория, дампы схем нескольких баз данных, Mongoid, API-only приложения.

• Пользовательские инструменты: регистрируйте собственные классы MCP::Tool рядом со встроенными и тестируйте их с помощью встроенного TestHelper.

Начало работы

Требования

• Ruby 3.1 или новее

• Rails 7.0 или новее

• Необязательно: brakeman для security_scan, listen для watch, ripgrep для более быстрого search_code

Установка в Gemfile

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

Генератор спрашивает, какие ИИ-инструменты вы используете и нужен ли режим 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. См. Standalone.

Проверка работы

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

Затем откройте проект в вашем ИИ-инструменте. Записанная конфигурация MCP подхватывается при открытии, и ассистент начинает вызывать rails_get_model_details вместо угадывания.

[!NOTE] Команды CLI выше — для вас. Когда MCP подключён, ассистент сам вызывает те же инструменты; вам не нужно их вводить.

Использование

MCP через stdio

По умолчанию. Каждый ИИ-инструмент получает собственный конфигурационный файл (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml), указывающий на:

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

MCP через HTTP

Смонтируйте сервер внутри вашего приложения. Он наследует ваши маршруты, аутентификацию и middleware и не требует второго процесса.

# 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.

Инструменты

Каждый инструмент только для чтения и отвечает на основе вашего приложения.

Несколько полезных в первый же день:

• search_code с match_type=trace возвращает определение, исходный код, всех вызывающих, сгруппированных по типу, и тесты — одним вызовом. Это заменяет 4–5 чтений файлов.

• get_controllers возвращает исходный код действий с унаследованными фильтрами, strong params и картой рендеринга.

• get_model_details возвращает ассоциации, валидации, области видимости, перечисления и макросы из AST, каждый помечен как [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. Проверяй перед тем, как писать. Никогда не ссылайся на столбец, ассоциацию, маршрут, хелпер, метод, класс, партиал или гем, которые не были подтверждены вызовом инструмента в этом ходе.

2. Помечай каждое предположение как [ASSUMPTION]. «Мне нужно сначала проверить X» — хороший ответ.

3. Обучающие данные описывают средний Rails. Это приложение не среднее. Когда что-то кажется очевидно стандартным, всё равно запрашивай.

4. Проверяй цепочку наследования перед каждым изменением: унаследованные фильтры, concerns, includes, STI-родители.

5. Пустой вывод инструмента — это информация. «0 вызывающих найдено» означает «расследуй», а не «продолжай».

6. Устаревший контекст лжёт. Перезапрашивай после записи.

Включено по умолчанию. Отключи с помощью config.anti_hallucination_rules = false, если предпочитаешь свои правила.

Когда приложение не может загрузиться

rails-ai-context пытается выполнить полную загрузку для живой рефлексии. Когда загрузка не удаётся (отсутствуют переменные окружения, недоступный сервис, сломанный инициализатор), команды чтения приложения переключаются на статический уровень вместо того, чтобы умереть: маршруты из config/routes.rb, схема из db/schema.rb, db/structure.sql или миграций, модели и контроллеры из их исходных файлов. Каждый ответ несёт баннер с указанием деградации, статические данные помечены [STATIC], а разделы, которым нужна загруженная загрузка, сообщают [UNAVAILABLE] с причиной.

--no-boot полностью пропускает попытку, что быстро и невосприимчиво к побочным эффектам загрузки. doctor всё ещё требует загружаемое приложение; диагностика загрузки — его работа.

Код находится в стандартной структуре, в пакетах packwerk (packs/*/app/*), в движках внутри репозитория (engines/*/app/*) и в любых extra_app_paths из .rails-ai-context.yml. Дампы схемы для нескольких баз данных (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-движок — в Архитектура и Интроспекторы.

Документация

Создано Rails-разработчиком с 10+ годами опыта в продакшене. Если это экономит твоё время, рассмотри спонсирование проекта.