# GitHub Copilot CLI Ruby on Rails: A Practical Guide

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

Learn how to use GitHub Copilot CLI on a Ruby on Rails project: setup, instruction files, migration safety, Hotwire patterns, and test-driven verification.

**In short:**

- Define Rails-specific commands and rules in .github/copilot-instructions.md or AGENTS.md before starting the agent.
- Keep Rails changes small and test-backed: write migrations, run specs, and review schema.rb after every turn.
- For parallel Rails work, use isolated git worktrees and automated code review with AgentVera.

[GitHub Copilot CLI](/en/agents/copilot-cli/) is a terminal coding agent you start by running `copilot` in a Ruby on Rails project folder. It reads the repository context and works through small changes, which fits the convention-driven nature of Rails. This guide covers setup, instruction files, a working loop, testing, pitfalls, and how to run several agents safely.

## Why Copilot CLI fits Rails development

Rails gives you a predictable file layout, strict naming rules, and generators that create standard code. GitHub Copilot CLI can use those conventions instead of guessing: it can propose models, migrations, controllers, request specs, and Hotwire views in the right places. Active Record migrations and strong parameters are explicit enough that the agent can suggest safe, test-backed changes. The same predictability makes review easy, because you know exactly which files should change for a given feature. When you combine that with RSpec or Minitest, the agent can run the test suite, see failures, and adjust without losing the Rails context. Hotwire projects benefit too, because the agent can keep Turbo Frame IDs, partials, and Stimulus targets consistent, which is often where hand-written Rails views drift.

## Preparing your Rails repo for Copilot CLI

Create `.github/copilot-instructions.md` or `AGENTS.md` at the repository root. The agent reads these files at startup, so put your Rails-specific commands, folder conventions, and rules there. A short, concrete file is better than a long general one. This example covers build, test, lint, and Rails-specific constraints:

```markdown
# Ruby on Rails project instructions

## Commands
- Setup: bin/setup
- Test: bundle exec rspec   # or bin/rails test for Minitest
- Lint: bin/rubocop
- Run the app: bin/dev

## Folder conventions
- Models in app/models, controllers in app/controllers, views in app/views.
- Jobs in app/jobs, mailers in app/mailers, services in app/services.
- Frontend assets in app/assets, Hotwire Stimulus controllers in app/javascript/controllers.

## Rails rules
- Always use Active Record migrations under db/migrate; never edit db/schema.rb by hand.
- Use reversible migrations when possible; always include a down method or use change.
- Keep controllers thin: move business logic into models or service objects.
- Prefer Hotwire Turbo Frames and Stimulus for interactivity; avoid custom JavaScript unless necessary.
- Use Zeitwerk naming: class User::Registration corresponds to app/models/user/registration.rb.
- Never run db:drop, db:reset, or db:rollback unless explicitly requested.
- Do not change config/credentials.yml.enc or config/master.key; ask for secrets.
- After generating a migration or model, run the relevant test file and then the full suite before finishing.
```

If you use Minitest, change the test command and note it. If you rely on importmap, esbuild, or Propshaft, add one line about where frontend files live. Version this file with the repo so every teammate and every agent session gets the same rules. The agent will still ask for clarification when the instruction file is ambiguous, but a focused file prevents the most common Rails mistakes. The key is to prevent the agent from reaching for destructive data commands or hand-editing generated files. For teams, commit this file early so agent behavior is reproducible across branches.

## Working in small, test-backed steps

Work in small, reviewable steps. Start by asking the agent to inspect the relevant controller, model, routes, and specs. Then request one test-backed change. For a fuller step-by-step flow, see [How to use GitHub Copilot CLI: a step-by-step guide](/en/blog/how-to-use-copilot-cli/). After each task, review `git diff`, run the specific test file, then run the complete suite. If the change touches a migration, check `db/schema.rb` and run both `up` and `down` before you consider it done. Before writing code, ask the agent to summarize the files it will touch and why. That summary forces it to map routes, controller actions, and model associations before editing. Example prompts for typical Rails work:

- Add a unique index to the users table, write a migration with `add_index unique: true`, add a model validation, and add a test for duplicate emails.
- Create a Turbo Stream broadcast for new comments on the post show page using the existing Comment partial; update the request spec.
- Fix the N+1 query in PostsController#index by using `includes(:user)`; add a regression spec that checks the number of SQL queries.
- Generate an Order model with `amount:decimal` and `status:integer` using Rails generators, then update the schema and write request specs for the checkout flow.
- Refactor the order confirmation logic from the controller into a `CheckoutService` object, keep the existing route behavior, and update the request specs.

Each prompt gives the agent enough Rails context to find the right file and enough scope to make a complete, testable change. Avoid open-ended prompts like "improve the app" because Rails apps often have many entry points.

## Strengths and Rails-specific pitfalls

Rails tasks with clear conventions and test coverage are the agent’s sweet spot. It handles Active Record migrations with indexes and validations, generator-based scaffolding, request specs, N+1 query fixes, and Hotwire partials well. The table below pairs common tasks with prompts and the specific Rails pitfalls to watch.

| Task | Good prompt | Pitfall to watch |
|------|-------------|------------------|
| Migration + validation | Add a `unique` index to `users.email` and a model validation with a test. | The agent may edit `schema.rb` by hand or forget the migration rollback path. |
| N+1 query fix | Remove N+1 in `index` and add a query-count regression test. | It might change controller logic and hide necessary preloads. |
| Hotwire interaction | Create a Stimulus controller to toggle a form inside a Turbo Frame. | It can add custom JS outside the asset pipeline or break existing Stimulus imports. |
| Generator use | Run the Rails generator for a `products` scaffold, then adjust the views to use Hotwire. | Generated files may conflict with custom partials or routing constraints. |

Beyond these, watch any change to `config/routes.rb`, `app/controllers/application_controller.rb`, or `app/helpers`. The agent can sometimes rewrite a route set or add a `before_action` that affects every request. Always inspect the diff instead of accepting the whole change. If you see a migration that alters a table with existing data, ask the agent to explain the data backfill and rollback plan before applying it.

## Verifying changes with Rails tests

Make the agent write or update specs before implementation when possible. [Spec-driven development with AI agents: a practical guide](/en/blog/spec-driven-development-with-ai/) works well in Rails because request specs and model specs map to routes and Active Record. After each change, run `bundle exec rspec` or `bin/rails test`, then check that `db/schema.rb` matches the migration and that both `up` and `down` work. For Hotwire or JavaScript changes, use system tests or let the agent check the app in a browser with [AI agent browser testing: let the agent check your app](/en/blog/ai-agent-browser-testing/). If you use Factory Bot, keep factories in `spec/factories` and ask the agent to update them with new associations. If a test passes but the behavior looks wrong in the browser, add a system spec that drives the full path before asking for another fix. Also ask the agent to run `bin/rails db:migrate:status` after migration work and to check that no pending migrations remain.

## Parallel Rails work with AgentVera

AgentVera runs GitHub Copilot CLI and other coding agents side by side in real terminal panels. For Rails work, the most useful features are parallel git worktrees, so several agents can work on separate features without overwriting migrations or views, automatic code review that catches Ruby-specific mistakes like a missing strong parameter or a drift between a migration and schema.rb, and checkpoints that snapshot each turn so you can undo a bad data or schema change in one click and replay the session. These controls reduce the risk of shipping broken Rails changes.

## Wrapping up

GitHub Copilot CLI becomes a reliable Rails pair programmer when you give it a focused instruction file, keep changes small and test-backed, and treat migrations and Hotwire code as review hotspots. Use the loop above, inspect every diff, and when you need more throughput, isolate parallel work in separate worktrees. With those habits, the agent handles the repetitive parts of Rails development without turning your app into a black box.

## Frequently asked questions

**How do I start GitHub Copilot CLI in a Ruby on Rails project?** Run copilot from the project folder after installing the CLI. The agent reads your repository files and any instructions in .github/copilot-instructions.md or AGENTS.md. Start with a small, well-scoped request such as adding a model validation or fixing an N+1 query.

**Can GitHub Copilot CLI run Rails generators and migrations safely?** Yes, if you instruct it to use generators and never edit db/schema.rb by hand. Ask for migration changes with a down path and require it to run the relevant test before finishing. Review the generated diff before applying changes.

**Does GitHub Copilot CLI understand Rails conventions like MVC and Hotwire?** It follows the file layout and naming conventions when you describe them in the project instructions. It can create controllers, models, views, and Stimulus controllers in standard directories. Providing explicit Hotwire patterns in AGENTS.md improves consistency.

**How do I give GitHub Copilot CLI project-specific Ruby on Rails instructions?** Create a .github/copilot-instructions.md or AGENTS.md file at the repository root. Include build, test, and lint commands, folder conventions, and Rails-specific rules like never editing schema.rb manually. The agent reads these instructions at startup.

---

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