# Using Claude Code for Ruby on Rails Development

URL: https://agentvera.dev/en/blog/claude-code-for-rails/ · Published: 2026-11-01

Learn how to set up Claude Code for a Rails project, write effective CLAUDE.md, run migrations and tests, and avoid common Active Record pitfalls.

**In short:**

- Use CLAUDE.md to hold Rails commands, test runner, and conventions so Claude Code has project-specific context.
- Keep a tight loop: ask for a plan, make one small change, run the affected spec, and review git diff.
- Generate migrations, RSpec/Minitest examples, and Hotwire updates, but review schema files and data safety carefully.

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](/en/agents/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.

```markdown
# 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](/en/blog/claude-code-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.

| Task | Good prompt | Watch closely |
|---|---|---|
| Active Record migration | "Add a `published_at` datetime column to `posts`." | Data backfills, defaults, `null: false` on existing large tables, and `change` vs `up/down`. |
| Model spec | "Write an RSpec model spec for `Order#total` with discounts." | Factory or fixture names, callbacks that run during tests, and time zones. |
| Controller change | "Add a `destroy` action to `Api::V1::ArticlesController` with authorization." | Strong parameters, rescue order, and existing routes. |
| Hotwire update | "Make `create.turbo_stream.erb` append the new task to `#task-list`." | DOM IDs, partial locals, and broadcast targets. |

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](/en/blog/claude-code-best-practices/) 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.

## Frequently asked questions

**Can Claude Code write and run Ruby on Rails migrations?** Yes, it can generate migration files and run bundle exec rails db:migrate. Review the migration carefully because changing schema and data together can be risky.

**How do I give Claude Code Ruby on Rails project context?** Create a CLAUDE.md in the project root with build, test, and lint commands, folder conventions, and Rails-specific rules like using Active Record and not bypassing validations. Include your test runner and any Hotwire setup.

**Does Claude Code work with RSpec and Minitest?** Yes. Use your normal test command such as bundle exec rspec or bundle exec rails test. Tell the agent in CLAUDE.md which suite you use and to run only the affected test file first.

**How do I keep Claude Code from making risky changes to a Rails app?** Ask for a plan before code, keep changes small, and review git diff. Use the agent’s plan mode if available and make it run the test suite after each change.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/