Gemini CLI Ruby on Rails: practical setup and workflow

Gemini CLI can handle day-to-day Ruby on Rails work when you run gemini in the project root and give it project context through a GEMINI.md file. It understands Rails MVC conventions, Active Record migrations, generators, and test suites well enough to make real changes without leaving the terminal. This guide explains how to set it up and use it safely on a Rails codebase.

Why Gemini CLI fits Rails codebases

Rails gives the agent a predictable structure: models in app/models, controllers in app/controllers, views in app/views, and schema changes in db/migrate. That reduces the guessing a general-purpose coding agent would otherwise do. Active Record associations, scopes, validations, and callbacks are plain Ruby, so Gemini CLI can reason about them directly. The migration workflow is also well suited to an agent because each schema change is a discrete file with a clear up and down. Hotwire makes view updates declarative with turbo_frame_tag and turbo_stream, which are easier for an agent to edit than imperative JavaScript. When your GEMINI.md names the test and lint commands, the agent can run the same checks you would run and adjust its changes accordingly.

Prepare GEMINI.md for Rails commands and conventions

Place a GEMINI.md file in the project root and commit it. Gemini CLI reads it on each session, so keep it short and factual. Include the exact build, test, and lint commands you use, plus Rails-specific rules that prevent common mistakes. If you use RSpec instead of Minitest, swap the test commands for bundle exec rspec and bundle exec rspec spec/models/user_spec.rb:42.

# GEMINI.md

## Project overview
Rails 7.2 application using Hotwire and Minitest. Standard Rails MVC conventions.

## Commands
- Install dependencies: `bundle install`
- Run migrations: `bin/rails db:migrate`
- Run the test suite: `bin/rails test`
- Run a single test: `bin/rails test test/models/user_test.rb:42`
- Lint Ruby: `bundle exec rubocop`
- Run system tests: `bin/rails test:system`

## Conventions
- Models, controllers, views, jobs, and mailers follow Rails defaults under `app/`.
- Use Active Record migrations for schema changes; never edit `db/schema.rb` by hand.
- Prefer `has_many :through` over `has_and_belongs_to_many` unless there are no join attributes.
- Use `turbo_stream` and `turbo_frame_tag` for Hotwire updates; avoid full-page JavaScript.
- Business logic belongs in models or service objects under `app/services`; keep controllers thin.
- Use strong parameters in controllers; no direct `params` in model calls.

## Rules
- Do not run `rails generate` unless explicitly asked because it can overwrite files.
- Do not delete or regenerate migrations after they are committed; add new migrations.
- Always run the relevant tests before proposing a change as complete.
- Keep the diff focused on the requested task; do not refactor unrelated code.

A tight feedback loop: plan, change, test, review

Use short, specific prompts and keep the agent on a small step. The loop that works best is: state the change, let the agent inspect the relevant files, ask it to make the change, run the targeted test, review the diff, then run the broader test suite. Do not ask for a large feature in one turn. For more on this style, see How to use Gemini CLI: a step-by-step guide.

Example prompts for typical Rails tasks:

• Add a published_at datetime column to the posts table, add a published scope, and update the index action to show only published posts. Create the migration but do not run it yet.
• Write a Minitest model test for User#full_name in test/models/user_test.rb. Follow the existing test style and use fixtures already defined.
• In app/controllers/comments_controller.rb, change the create action to return a Hotwire turbo_stream response that appends the new comment to #comments and resets the form.
• Run bin/rails test test/models/post_test.rb, fix any failures you introduced, and show me the diff before you stop.

After each turn, review the diff with git diff. Look for accidental changes to db/schema.rb, unrelated tests, or controller logic that bypasses strong parameters.

Rails tasks the agent handles well and common pitfalls

The agent is strongest on tasks that follow existing patterns in the codebase. It can add a model with its migration, associations, validations, and tests. It can update controllers, create Hotwire turbo frames, write service objects, and fix N+1 queries with includes or preload. It is also good at writing RSpec or Minitest tests that match the existing style.

Watch it closely on Rails-specific pitfalls:

• Schema and migration drift: the agent may edit db/schema.rb directly or forget to run the migration after creating it. Always check that db/schema.rb matches the migration and your local database.
• Migration reversibility and data migrations: avoid mixing data changes into schema migrations. Ask the agent to make migrations reversible or separate data backfills.
• Zeitwerk autoloading: a new service object or concern must live in the right folder and match its class name, or Rails will not load it. Check app/services and app/models/concerns.
• Unintended callback and scope changes: Active Record callbacks affect many test cases. Ask the agent to run the full model test file before finishing.
• Hotwire partial naming and dom_id: generated turbo stream responses often break when the partial path or DOM id is wrong. Verify with a system test or manual browser check.
• Secrets and environment config: the agent should not read or write credentials, config/master.key, or production environment values. Keep those out of prompts and out of GEMINI.md.

Verify your changes with tests and schema checks

Make the agent run tests before it says a task is done, but do not trust the output alone. Use this as a baseline:

| Check | Command | | Model or unit test | bin/rails test test/models/user_test.rb | | Controller test | bin/rails test test/controllers/users_controller_test.rb | | System test | bin/rails test:system | | Lint and style | bundle exec rubocop | | Schema consistency | bin/rails db:migrate:status and review git diff db/schema.rb |

For RSpec, replace the first three with bundle exec rspec spec/models/user_spec.rb, bundle exec rspec spec/requests, and bundle exec rspec spec/system. After the agent has made a change, run the focused test, then the full suite before opening a pull request. For Hotwire changes, a system test is worth more than a controller test because it exercises the turbo response in a real session. Treat the agent’s output as a proposed patch, not a finished PR. This is the same review discipline described in AI pair programming: how to work with a coding agent.

Parallel agents on a Rails project with AgentVera

AgentVera runs multiple Gemini CLI agents side by side in real terminal panels. For Rails, the most useful pieces are separate git worktrees for each agent, so parallel work on models, migrations, and Hotwire views does not overwrite files; automatic code review when a turn ends, with findings linked to file:line, catches Ruby- and Rails-specific issues like missing strong parameters or broken associations; checkpoints let you undo a turn with one click and replay it. Token budgets per agent, turn and day also keep exploratory refactors from burning through your API limit.

Keep Rails changes small and reviewed

Gemini CLI becomes a practical Rails tool once you commit a small GEMINI.md and keep the agent in a test-driven loop. Use it for focused model, controller, migration, and Hotwire changes, but always review the diff and verify tests locally. Once that workflow is stable, running several Gemini CLI agents in AgentVera lets you parallelize feature work without collisions.