rails-ai-context

Предоставьте своему ИИ-помощнику по кодированию достоверную информацию о вашем Rails-приложении

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

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

rails-ai-context — это Ruby-гем, который превращает ваше Rails-приложение в источник истины для ИИ-помощников по кодированию. Вместо того чтобы угадывать схему, ассоциации, маршруты и соглашения на основе обучающих данных, помощник запрашивает информацию у вашего приложения: 45 инструментов только для чтения, доступных через MCP или запускаемых из командной строки, а также сгенерированные контекстные файлы для 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 из гема, которого нет.
• Придумывает метод, которого нет в кодовой базе.

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

Вы просите ИИ...	Без гема	С гемом
Добавить столбец subscription_tier в таблицу пользователей	Пишет миграцию, дублирует существующий столбец	Считывает актуальную схему, видит subscription_status, уточняет перед миграцией
Вызвать user.posts в контроллере	Угадывает; ошибка NoMethodError во время выполнения	Определяет реальную ассоциацию из модели
Написать тесты для новой модели	Создаёт шаблон с FactoryBot	Определяет, что у вас фикстурный набор тестов, и подстраивается под него
Исправить неработающий экшен создания	Пропускает унаследованный authenticate_user!	Получает фильтры родительского контроллера вместе с исходным кодом экшена
Создать страницу панели управления	Придумывает классы Tailwind из памяти	Получает реальные шаблоны кнопок/карточек/оповещений
Найти, где используется publishable?	Последовательно просматривает 6 файлов, всё равно пропускает вызовы	Один запрос: определение + исходный код + все вызовы + тесты
---

Возможности

• 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.
• Пользовательские инструменты: регистрируйте собственные классы 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 возвращает исходный код действия с унаследованными фильтрами, строгими параметрами и картой рендеринга.
• 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. Проверяйте цепочку наследования перед каждым изменением: унаследованные фильтры, консерны, инклюды, родительские классы STI.
5. Пустой вывод инструмента — это информация. «Не найдено вызывающих» означает, что нужно исследовать, а не продолжать.
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 и подобные) отображаются в разделе Вторичные базы данных. Приложения на Mongoid получают сигнал [НЕДОСТУПНО] для схемы и статические данные моделей вместо пустой таблицы, а API-only приложения получают "неприменимо" от инструментов представления и фронтенда вместо тихого пропуска. Подробности в разделе Совместимость.

Конфигурация

# 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+ годами опыта в продакшене. Если инструмент экономит ваше время, рассмотрите возможность поддержки проекта.