Cursor Agent is the terminal coding agent from Cursor. Start it with cursor-agent inside a Ruby on Rails project, and it reads project instructions from AGENTS.md or .cursor/rules before editing code. With the right setup, it handles common Rails work such as models, migrations, controllers, specs, and Hotwire updates in a reviewable, test-driven loop. For more on the tool itself, see Cursor Agent.
Rails conventions make Cursor Agent predictable
Rails is convention-heavy, and that works in the agent’s favor. Once the agent knows your app is a standard Rails application, it can infer file locations: models in app/models, controllers in app/controllers, views in app/views, specs in spec, and migrations in db/migrate. It can follow the MVC flow, update routes, add strong parameters, and keep controller actions thin. Unlike a generic coding assistant, Cursor Agent can operate directly in the terminal with the same tools you use: bundle exec, rails, rspec, and rubocop. It can read error output from the test suite and iterate without you copying stack traces.
The agent also fits Rails workflows that rely on generators and conventions. You can ask it to generate a model with the proper attributes and associations, then write the migration and the RSpec or Minitest coverage. For Hotwire projects, it can add Turbo Stream broadcasts, update partials, and keep the DOM updates consistent with existing naming. The key is giving it project-specific rules so it does not invent conventions that conflict with your app.
Give the agent a short Rails rulebook
Cursor Agent looks for instructions in AGENTS.md at the project root or in .cursor/rules. For Ruby on Rails, keep the file short and concrete: commands, folder conventions, and rules that prevent common Rails mistakes. Do not paste the entire Rails guide; the agent already knows Rails. Focus on what is unusual about your project and what you want enforced on every change.
A realistic AGENTS.md for a Rails application looks like this:
# AGENTS.md
# Ruby on Rails project instructions for Cursor Agent
## Commands
- Install dependencies: `bundle install`
- Run the test suite: `bundle exec rspec`
- Run a single test: `bundle exec rspec spec/models/user_spec.rb:42`
- Lint: `bundle exec rubocop`
- Prepare test database: `bundle exec rails db:test:prepare`
## Project layout
- Standard Rails 7.1 app with Hotwire.
- Models in `app/models`, controllers in `app/controllers`, views in `app/views`.
- Service objects live in `app/services` and are plain Ruby classes.
- RSpec tests in `spec`, factories in `spec/factories` using FactoryBot.
## Rules
- Do not run `rails generate` unless the task explicitly asks for it.
- Never edit `db/schema.rb` by hand; always use migrations and run them.
- When adding a migration, make it reversible and keep the schema version in sync.
- Use strong parameters in controllers; do not bypass them.
- Prefer scopes over class methods for query chains.
- Keep controllers thin; put business logic in models or service objects.
- Use Turbo Streams for partial DOM updates; avoid full page reloads where Hotwire is already in use.
- In RSpec, use `let` for setup and avoid `before(:all)` with database state.You can place similar rules in .cursor/rules if your team prefers that location. The important part is that the agent sees these before it edits, so it does not need to guess about your test runner, lint command, or migration policy. If you are still learning the terminal flow, the step-by-step guide at How to use Cursor CLI: a step-by-step guide covers the basics of running the agent in a project.
A test-driven loop with focused prompts
Treat Cursor Agent like a junior pair programmer who works fast but needs verification. Use a loop:
- Plan the change in one or two sentences.
- Ask the agent to make one small, testable change.
- Let it run the relevant tests, or run them yourself.
- Review
git difffor unintended edits, especially to routes, schema, and callbacks. - Commit only after tests and review pass.
This loop matters more in Rails than in many stacks because a small change can touch models, migrations, controllers, views, and specs at the same time. Prompts should name the files or the Rails layer, the desired behavior, and the tests you expect.
| Task | Prompt |
|---|---|
| Add a model with validation | “Generate a Post model with title, body, published_at and belongs_to :user. Include presence validations and a unique slug. Write the migration and RSpec model specs.” |
| Build a controller action | “Add a PostsController#create action that accepts strong parameters, saves the post for current_user, and redirects with a flash notice. Write request specs for valid and invalid input.” |
| Hotwire update | “When a post is created, broadcast a Turbo Stream that prepends the post partial to #posts and updates the counter. Keep the existing partial conventions.” |
| Fix N+1 query | “The posts index loads author names inefficiently. Add includes(:user) to the controller and add a test to prevent regression.” |
| Refactor service object | “Extract the post publishing logic from the controller into a PostPublisher service object. Move the transaction, callback, and error handling. Update the controller and specs.” |
If the agent proposes a change larger than about 150 lines, stop it and split the task. Rails changes are easier to review when they stay within one feature area, such as a single model plus its spec, or a controller action plus its request spec.
Strengths and Rails-specific pitfalls
Cursor Agent is strong on repetitive, convention-driven Rails work: generating models and migrations, adding controller actions with strong parameters, writing RSpec or Minitest specs, updating routes, creating service objects, and adding Hotwire Turbo Stream updates. It can also help with query optimization, such as adding includes to fix N+1 queries, and with refactoring fat controllers into service objects.
The areas to watch closely are the ones where Rails has hidden behavior. Migrations are the biggest risk: the agent may generate a migration with an irreversible change or forget to update the schema version. Always review db/migrate before running it, and never let the agent edit db/schema.rb by hand. Callbacks and validations are another pitfall: a new validation can break existing tests or production data, and callbacks can hide side effects that are hard to trace. Routes order matters, so check config/routes.rb for a new route shadowing an existing one. Zeitwerk autoloading expects file names to match constant names, so a service object in app/services/post_publisher.rb must define PostPublisher, not Postpublisher. Strong parameters must be explicit; if the agent uses params.require(:post).permit!, reject that and ask for an explicit list. Finally, test pollution from shared database state can cause flaky specs, so keep the agent away from before(:all) with database writes and prefer transactional tests or DatabaseCleaner as your project already uses.
Test and verify agent changes
Make the agent run the same commands you would run. For RSpec, use bundle exec rspec or bundle exec rspec spec/models/post_spec.rb for a focused change. For Minitest, use bundle exec rails test or bundle exec rails test test/models/post_test.rb. After any migration, run bundle exec rails db:migrate and bundle exec rails db:test:prepare before the test suite. For linting, run bundle exec rubocop and fix style violations before review. If you use Brakeman or standard, add those commands to AGENTS.md and require them for security-sensitive changes.
Review the diff with git diff --stat first, then git diff for the actual code. Check that the agent did not change routes, schema.rb, or Gemfile unless the task required it. If it touched a callback or validation, run the full model spec, not just the new one. For migrations, inspect the up and down methods manually and make sure the change can be rolled back. Use bundle exec rails db:rollback after migrating in development to confirm reversibility before committing. A good final check is to run the complete test suite once, because Rails tests can share state through fixtures, factories, or Active Record connections.
Parallel agents with AgentVera for Rails
When a Rails project has several independent workstreams, AgentVera lets you run multiple Cursor Agent sessions side by side, each in its own terminal panel and git worktree. That isolation is the key benefit for Rails: one agent can add a migration and update models while another works on a separate controller or Hotwire change without overwriting the other’s schema or route files. Automatic code review after each turn catches issues like missing strong parameters or an irreversible migration before you merge, and checkpoints let you undo a bad refactor. Token budgets keep long-running work from consuming the day’s quota. See Best tools to run AI coding agents in parallel (2026) for more on parallel coding agents.
Stick to the loop and review every diff
Cursor Agent is most useful on a Ruby on Rails project when you feed it the commands and conventions that already exist in your codebase. Keep your AGENTS.md short and Rails-specific, work in small testable steps, and review migrations and schema changes as if a junior developer wrote them. With that discipline, the agent can take on a large share of repetitive Rails work without turning your app into an unmaintainable patchwork.