Using Claude Code for Ruby on Rails Development

Claude Code can fit a Ruby on Rails workflow well because Rails uses strong conventions that the agent can follow. If you are already running Claude Code with claude in your Rails project, set up a project-level CLAUDE.md, keep changes small, run tests after each step, and review the diff. This guide shows a practical loop for Active Record, RSpec/Minitest, and Hotwire work.

Why Rails conventions fit Claude Code

Rails’ MVC structure, explicit generators, config files, and Active Record patterns give the agent predictable landmarks. A model, migration, controller, and spec usually have known locations and naming. Claude Code can generate Rails-specific code that respects strong_parameters, callbacks, scopes, and RESTful routes. It also works well when you tell it to run the existing test suite and linter, so it gets fast feedback instead of guessing. Because Rails relies on convention over configuration, a concise CLAUDE.md often gives the agent enough context to avoid common mistakes such as editing schema.rb or inventing JavaScript packages.

Create a CLAUDE.md that tells Claude Code your Rails rules

Start with claude in the project root. The most important file is CLAUDE.md. Keep it short and project-specific. Include commands, test runner, lint, folder conventions, and rules that are easy to violate.

# CLAUDE.md

## Commands
- Bundle: bundle install
- Server: bin/rails server
- Test suite: bundle exec rspec
- One test: bundle exec rspec spec/models/user_spec.rb
- Lint: bundle exec rubocop

## Conventions
- Ruby on Rails 7.x, Active Record, RSpec, Hotwire.
- Models live in app/models, service objects in app/services.
- Migrations go in db/migrate; never edit db/schema.rb by hand.
- Use `strong_parameters` in controllers.
- Default to `has_many :through` for many-to-many associations.

## Rules
- Run only the affected spec file first, then the full suite when asked.
- Do not skip validations with `save(validate: false)` unless explicitly requested.
- Use `reload` after updating associated records in specs.
- Keep migrations reversible where possible.

If you use Minitest, replace the test commands with bin/rails test and bin/rails test test/models/user_test.rb. The same rules apply: put the exact command in CLAUDE.md so the agent does not switch to RSpec or invent a different runner.

Plan, change, test, review: a practical loop

For each task, ask for a plan if it touches schema or multiple files. You can have Claude Code work in plan mode so it proposes changes before writing. Then let it implement one small change, run the targeted test, and review git diff before continuing. Avoid batch refactors.

Example prompts for typical Rails tasks:

• “Create a migration to add a status string column to orders, defaulting to 'pending', and add an enum in the model with the same values.”
• “Add a Minitest model test for User#full_name that covers first and last names, and a blank first name case.”
• “Refactor the create action in CommentsController to use a service object under app/services and keep the existing request specs passing.”
• “Update app/views/comments/create.turbo_stream.erb to append the new comment to #comments and reset the form partial.”
• “Run bundle exec rubocop on the changed files and fix only style offenses, not business logic.”

What Claude Code does well in Rails, and where to double-check

The agent is reliable for generating migrations, model scopes and validations, RSpec or Minitest examples, RESTful controller actions, and Hotwire Turbo Streams. Treat its output like a capable junior Rails developer: exact syntax is usually correct, but domain logic and data safety need review.

Pitfalls specific to Rails after that table:

• Editing db/schema.rb or db/structure.sql by hand instead of generating migrations.
• Running rails db:migrate without checking whether the migration can run on a large table or needs a data migration separated from schema change.
• Changing model callbacks (before_save, after_commit) without considering tests that rely on side effects.
• Calling save(validate: false) or update_all while bypassing validations and callbacks when not needed.
• Relying on generated test data that does not match ApplicationRecord defaults or Time.zone.

Test with RSpec, Minitest, and RuboCop, then review the diff

Claude Code should run the test suite through your normal commands: bundle exec rspec or bin/rails test. Before trusting code, run the affected spec file, review the diff, and then run the full suite. Ask it to run the linter with bundle exec rubocop. For Rails, also check that migrations roll back cleanly with bundle exec rails db:rollback STEP=1 and that the schema file matches the migration. A practical checklist helps keep these steps consistent. If you use continuous integration, keep the same commands in the agent context so it does not invent a different test runner.

Parallel agents on a Rails codebase with AgentVera

For larger Rails apps, AgentVera helps by running several Claude Code agents in parallel, each in its own git worktree so a migration, controller change, and Hotwire patch do not overwrite each other’s files. After an agent finishes, automatic code review from a second model flags Active Record or routing problems with file:line links. Checkpoints let you undo a dangerous migration or broad refactor in one click, and token budgets keep long test runs from exhausting the account. These are the parts that matter most for Rails work.

Make Claude Code a safe pair for your Rails codebase

Claude Code can be a productive pair for Rails projects when given clear project instructions and kept on a small step, test, review loop. Put Rails commands and conventions in CLAUDE.md, use plan mode for schema changes, and verify every change through RSpec or Minitest and RuboCop. The result is safer migrations, cleaner controllers, and less time spent on repetitive Rails code.