Using opencode with Ruby on Rails: A Practical Guide

opencode is a terminal coding agent that runs with opencode in a Rails project and reads instructions from AGENTS.md. This guide covers setup, a day-to-day loop, Rails-specific pitfalls, testing, and parallel work. For a broader walkthrough, see How to use opencode: a step-by-step guide.

Why opencode suits Ruby on Rails work

Rails gives opencode a strong, predictable structure: models, views, controllers, migrations, routes, and tests all have standard locations and naming. The agent can read app/, db/, config/routes.rb, and test/ or spec/ to understand the app, then run bin/rails test or bundle exec rspec to verify changes. Because Rails changes usually span multiple files, a coding agent that can edit a migration, model, controller, view, and test in one pass saves real time. Hotwire adds another fit: Turbo Streams and Stimulus controllers are mostly server-rendered or small JavaScript, so opencode can build interactive features without a separate frontend toolchain. The main condition is that the project’s commands and rules are written down, because opencode uses AGENTS.md as the source of truth.

Setting up the project for opencode

Add an AGENTS.md file at the repository root. It should contain the exact build, test, and lint commands, the folder conventions, and any Rails-specific guardrails. Keep it short enough that the agent actually follows it; 30–60 lines is usually right.

# AGENTS.md

## Project commands
- Install dependencies: `bundle install`
- Run the Rails server: `bin/rails server`
- Run tests: `bin/rails test` (Minitest) or `bundle exec rspec` (RSpec)
- Lint Ruby: `bundle exec rubocop`
- Run migrations: `bin/rails db:migrate`
- Roll back one migration: `bin/rails db:rollback`

## Conventions
- Use Rails MVC: models in `app/models`, controllers in `app/controllers`, views in `app/views`.
- Use Active Record migrations; never edit `db/schema.rb` by hand.
- Prefer scopes, associations, and Active Record methods over raw SQL.
- Use strong parameters in controllers.
- Keep controllers thin; put business logic in models or service objects.
- Use RSpec with `spec/` or Minitest with `test/`, whichever is already configured.
- For Hotwire, use Turbo Streams and Stimulus controllers; avoid inline JavaScript.

## Rules
- Run the relevant test suite before finishing a task. Do not leave failing tests.
- Do not run destructive commands such as `db:drop`, `db:reset`, or `git push` without asking.
- After changing migrations, run `bin/rails db:migrate` and let Rails update `db/schema.rb`.
- Respect the existing style; run `bundle exec rubocop` on only the files you changed.

The agent reads this file automatically when you start opencode in the project folder. Keep the commands current; if you change test runners or add a linter, update AGENTS.md.

A working loop for Rails tasks

Use a plan–execute–verify loop. Tell opencode what to change and ask it to update the tests at the same time. After it finishes, inspect git diff, run the tests yourself, and only then ask for the next small step. Avoid giving a huge spec in one prompt; Rails changes are easier to review as small, test-covered commits.

Example prompts:

• “Add a validation to the User model that prevents duplicate email addresses, and write a model test for it.”
• “Generate a migration that adds a published_at timestamp to articles, then update the Article model and controller to use it in the index action.”
• “Create a Hotwire Turbo Stream for creating a Comment on an Article so the new comment appears without a full page reload. Add a system test.”
• “Refactor OrdersController#create to move order total calculation into a service object, and update the existing request specs.”
• “Identify slow queries in ReportsController#show and add database indexes and scopes to fix them; run the relevant tests.”

After each prompt, review the diff for unintended changes, especially in db/schema.rb, config/routes.rb, and any generated files.

What opencode handles well and where to watch closely

opencode is reliable for generating Rails models, migrations, controllers, routes, and the matching RSpec or Minitest tests. It writes validations, scopes, associations, and service objects quickly, and it can add Hotwire Turbo Streams and Stimulus controllers without much hand-holding. Refactoring a fat controller into smaller objects is also a good fit because the test suite can confirm behavior.

Watch it closely in these Rails-specific areas:

• Migrations and schema: it may edit db/schema.rb by hand or create a migration that is hard to roll back. Always review the migration file, run bin/rails db:migrate:status, and verify db/schema.rb changed only through db:migrate.
• Autoloading and naming: Rails uses Zeitwerk, so a new class must live in the right file with the right name. opencode may define a constant in the wrong path or use the wrong pluralization; the resulting NameError may appear only later.
• Strong parameters: it can forget to permit required fields or permit too much. Check controller params before merging.
• Callbacks and associations: a new after_save can cause recursive saves or an N+1. Prefer explicit service calls and test with fixtures or factories.
• Hotwire: it may add inline JavaScript or plain fetch when the existing app uses Turbo Streams and Stimulus. Point it to the existing pattern and ask for a system test.
• Generators: when a task involves a new model or migration, tell it to use bin/rails generate rather than hand-writing every file, so timestamps and test stubs are correct.

Testing and verification with opencode

The agent should run tests as part of its work, but you still verify before merging. Use the table below as a checklist for Rails pull requests produced by opencode.

If opencode changes a migration, run bin/rails db:migrate in a clean development database, then roll back with bin/rails db:rollback to make sure the migration is reversible. For RSpec, ensure the agent runs the specific spec file first, then the full suite only when the change is complete.

Running several agents on one Rails project with AgentVera

AgentVera is a desktop app that runs opencode and other coding agents side by side in real terminal panels. For Rails work, the most useful pieces are parallel agents in separate git worktrees, automatic code review with file:line findings, and checkpoints that can undo a turn and replay it. Separate worktrees let one agent work on a migration while another updates tests without overwriting files. Code review catches the Rails-specific mistakes above before they merge, and checkpoints make it safe to try a risky refactor. For parallel agent setups, see Best tools to run AI coding agents in parallel (2026).

Wrap-up

opencode works well on Ruby on Rails when you document the project’s commands and conventions in AGENTS.md, keep prompts small and test-covered, and review migrations and schema diffs carefully. Use the test suite as the final gate, and when you need more throughput, run several agents in parallel with AgentVera and review their work before merging.