# Codex Ruby on Rails: A Practical Guide for Developers

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

Learn how to use Codex on a Ruby on Rails project: setup, AGENTS.md, prompts, testing, pitfalls, and running parallel agents with AgentVera.

**In short:**

- Codex works well with Rails conventions when you give it a focused AGENTS.md and explicit working loop.
- Use small, test-driven steps and review diffs carefully, especially around migrations, callbacks, and asset or Hotwire changes.
- Running parallel Codex agents in git worktrees with AgentVera speeds up independent Rails tasks without file conflicts.

Using [Codex](/en/agents/codex/) on a Ruby on Rails project is most effective when you treat it as a junior pair programmer that already knows Rails conventions but needs your project’s specific commands and boundaries. Start it by running `codex` in the project folder and make sure an AGENTS.md describes the build, test, lint, and migration rules. The rest of this guide gives practical setup, prompts, and review habits for Rails work.

## The Rails advantage for Codex

Rails rewards convention over configuration, so the files an agent needs are usually predictable: models in app/models, controllers in app/controllers, views in app/views, and migrations in db/migrate. Codex can read those paths and propose changes that match existing naming. It also handles Active Record migrations and associations well when the schema is visible in db/schema.rb, and it can run `bin/rails test` to verify a change. The main benefit is not that Codex knows Rails; it is that Rails gives enough structure for the agent to find the right file and the right test quickly. Hotwire adds another layer of convention with Turbo Frames and Turbo Streams, which Codex can follow if you point to existing examples.

## Preparing a Rails project for Codex

Codex reads project instructions from AGENTS.md in the project root. For Rails, that file should list the exact commands for installing dependencies, testing, linting, and checking the schema, plus the folder conventions the agent must respect. The setup described in [How to use Codex CLI: a step-by-step guide](/en/blog/how-to-use-codex-cli/) covers the basics; the example below shows the Rails-specific parts.

```markdown
# AGENTS.md

## Commands
- Install dependencies: bundle install
- Run the default test suite: bin/rails test
- Run one test file: bin/rails test test/models/user_test.rb
- Run RSpec if this project uses it: bundle exec rspec
- Lint: bundle exec rubocop
- Check schema drift: bin/rails db:migrate:status

## Conventions
- Rails 7.1, Ruby 3.2
- Models under app/models, concerns under app/models/concerns
- Controllers stay thin; business logic goes in app/services
- Use Active Record migrations; never edit an existing migration after it has been applied
- Use Hotwire Turbo Frames for partial updates; avoid custom JavaScript unless necessary
- Prefer scopes over class methods for query chains
- Do not add gems without asking; update Gemfile and run bundle install

## Rules
- Run the relevant test file after each change.
- Before creating a migration, read db/schema.rb to see the current state.
- Use reversible migrations when possible; if a migration cannot be reversed, say so.
- Never run rails db:drop, db:reset, or db:seed without explicit approval.
- Keep controller actions to standard REST actions unless asked.
- Do not modify config/credentials.yml.enc or config/master.key.
```

Keep AGENTS.md short enough that it is actually read; a long policy document is less useful than the handful of commands and rules that prevent the most common Rails mistakes. Update it when you change test framework or add a linter.

## A repeatable loop for Rails changes

Treat a session as a loop: ask for a small change, let Codex inspect the relevant files, have it run the focused test, then review `git diff` yourself before moving on. Do not ask for an entire feature at once. The table below gives prompts that map to typical Rails work.

| Task | Good prompt |
| --- | --- |
| Add a model with migration | Create a User model with name:string and email:string:uniq, generate a reversible migration, run the migration, and add a model test. |
| Build a controller action | Add a PostsController#index that lists published posts ordered by created_at desc, with a Turbo Frame for pagination; write a controller test. |
| Fix a failing test | Read the failing test in test/services/invoice_builder_test.rb, make the smallest change to InvoiceBuilder to pass it, and run that test file. |
| Refactor a callback | Replace the after_save callback on Order with a service object, update callers, and run the order and service tests. |
| Add a Hotwire feature | Use Turbo Streams to append a new comment to the comments list after create, following existing partial naming; test the create action. |

After each turn, ask Codex to summarize which files it changed and why. If a migration was created, open the migration and check db/schema.rb after it runs. Use the test command from AGENTS.md and do not continue if the suite is red.

## Strengths and pitfalls in Rails work

Codex handles the mechanical parts of Rails well: generating a model and migration, adding associations and scopes, writing controller actions with strong parameters, adding RSpec or Minitest tests, and creating simple Turbo Streams from existing examples. It is less reliable around hidden side effects and environment-specific behavior.

Watch it closely on:
- Migrations: data backfills, irreversible operations, changing columns on large tables, and adding indexes or foreign keys without a concurrent algorithm.
- Callbacks: after_save and after_create chains that hide business logic, trigger emails, or update other records.
- Zeitwerk autoloading: a file path that does not match the class or module name will work in development but fail in production or CI.
- Strong parameters: an agent may forget to permit nested attributes or may permit everything.
- JavaScript and importmap changes: small edits can break the asset pipeline or Hotwire wiring in ways tests do not catch.

If the agent uses `rails generate`, review the generated files; generators can create unused helpers, assets, or fixtures that you do not want in the diff.

## Verifying Rails changes with tests and lint

Always require the relevant test file to pass before accepting a change. After Codex makes a change, do not rely on its own claim that tests passed; look at the terminal output, then run the focused test yourself if the change touches data or schema. Run RuboCop and check for Rails-specific warnings such as unpermitted parameters, N+1 queries in new scopes, and missing inverse_of on associations. For larger diffs, a second model review can catch issues that the coding agent missed; see [AI code review: check what your agents write](/en/blog/ai-code-review/). Finally, use `git diff` to read every line that a prompt changes, especially in migrations and config files.

## Parallel Codex agents on a Rails project with AgentVera

When you have independent Rails tasks, such as one agent working on a billing service while another refactors a controller, AgentVera runs the real Codex CLI in separate terminal panels, and each agent can use its own git worktree so migrations and models do not overwrite each other. Automatic code review after each turn flags issues in migrations or callbacks with file:line links, which is useful before you apply anything. Checkpoints let you undo a turn and replay it, so a bad schema change is not permanent. That keeps parallel Rails work reviewable and reversible.

## Final recommendations for Codex on Rails

Codex on Rails is most useful when you treat it as an agent with a tight loop: explicit project instructions, small changes, tests after every step, and human review of the diff. Set up AGENTS.md, stick to Rails conventions, and use review and checkpointing when running several agents. That keeps the speed of an agent without giving up the safety Rails teams expect.

## Frequently asked questions

**How do I start Codex in a Ruby on Rails project?** Run codex in the project folder after making sure an AGENTS.md file exists with Rails-specific commands and rules. Start with a small, test-driven task such as adding a model or fixing a failing test. Review the diff before continuing.

**Can Codex create and run Rails migrations safely?** Yes, but do not let it run migrations without review. Ask for reversible migrations, check db/schema.rb before and after, and keep destructive commands like db:reset out of AGENTS.md except with explicit approval.

**Does Codex understand Rails MVC conventions?** Codex recognizes common Rails paths and generators, but it still needs project-specific rules in AGENTS.md. Point it to existing controllers, services, and views so it follows the conventions your team already uses.

**How do I use Codex with RSpec or Minitest?** Specify the test command in AGENTS.md, either bin/rails test for Minitest or bundle exec rspec for RSpec. Ask Codex to run the relevant test file after each change and show the terminal output.

---

**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/