Ruby on Rails Best Practices
Full-stack Rails 8.1 guide organized as modular rules. Covers MVC core patterns, Active Record, components (jobs, mailer, cable, storage), security, testing, performance, deployment, and debugging.
For core Ruby language topics (blocks/procs/lambdas, modules/mixins, metaprogramming, Bundler/gems, RSpec/Minitest, RuboCop) that aren't Rails-specific, load the sibling ruby skill instead.
ROUTING: Which rule file to load
IF working with models, database queries, associations, validations, or migrations:
→ Read rules/core-active-record.md
IF working with routes, controllers, params, sessions, cookies, or filters:
→ Read rules/core-routing-and-controllers.md
IF working with views, layouts, partials, ERB templates, or form helpers:
→ Read rules/core-views-and-forms.md
IF working with background jobs, emails, or WebSocket channels:
→ Read rules/component-jobs-mailer-cable.md
IF working with file uploads or cloud storage:
→ Read rules/component-active-storage.md
IF dealing with security concerns (auth, CSRF, XSS, SQL injection, secrets):
→ Read rules/security-best-practices.md
IF writing or fixing tests:
→ Read rules/testing-patterns.md
IF optimizing performance or configuring for production:
→ Read rules/perf-caching-and-deployment.md
IF debugging an error or unexpected behavior:
→ Read rules/debug-tools.md
IF building a Rails engine, a custom generator, or Rack middleware:
→ Read rules/extending-rails.md
IF new to the MVC request cycle or need a top-level orientation:
→ Read rules/core-mvc-request-lifecycle.md first
Rule index
| Topic |
Description |
File |
| Sections overview |
Categories and reading order |
rules/_sections.md |
| MVC lifecycle |
Request pipeline from router to response |
rules/core-mvc-request-lifecycle.md |
| Active Record |
Models, queries, associations, validations, migrations |
rules/core-active-record.md |
| Routing & Controllers |
RESTful routes, params, callbacks, sessions |
rules/core-routing-and-controllers.md |
| Views & Forms |
ERB, layouts, partials, form helpers |
rules/core-views-and-forms.md |
| Jobs / Mailer / Cable |
ActiveJob, ActionMailer, ActionCable |
rules/component-jobs-mailer-cable.md |
| Active Storage |
File uploads, cloud storage |
rules/component-active-storage.md |
| Security |
CSRF, XSS, SQL injection, secrets, auth |
rules/security-best-practices.md |
| Testing |
Unit, integration, system tests |
rules/testing-patterns.md |
| Performance & Deploy |
Caching strategies, Puma, Kamal, Thruster, concurrency |
rules/perf-caching-and-deployment.md |
| Debug |
byebug, web console, logging, common errors |
rules/debug-tools.md |
| Extending Rails |
Engines, custom generators, Rack middleware |
rules/extending-rails.md |
Rule categories by priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
MVC core patterns |
CRITICAL |
core- |
| 2 |
Components |
HIGH |
component- |
| 3 |
Security |
HIGH |
security- |
| 4 |
Testing |
HIGH |
testing- |
| 5 |
Performance & Deploy |
MEDIUM-HIGH |
perf- |
| 6 |
Debug |
MEDIUM |
debug- |
| 7 |
Extending Rails |
LOW-MEDIUM |
(none, see extending-rails.md) |
Coverage and maintenance
Rails CLI quick reference
rails new myapp # new full-stack app
rails new myapp --api # API-only mode
rails generate model Post title:string body:text
rails generate controller Posts index show
rails generate migration AddAuthorToPosts author:references
rails db:migrate
rails db:rollback
rails routes # list all routes
rails console # interactive REPL
rails test # run test suite
rails server # start dev server (localhost:3000)
1---2name: ruby-on-rails3description: Comprehensive Ruby on Rails 8.1 best-practices skill covering MVC, Active Record, routing, views, background jobs, storage, security, testing, performance, Kamal/Thruster deployment, and engines/generators. Use when the user mentions Rails, Ruby on Rails, ActiveRecord, ActiveJob, ActionMailer, ActionCable, Active Storage, rails generate, rails routes, Hotwire, Turbo, Stimulus, Kamal, or asks to build, review, debug, or migrate a Rails application or API. For plain Ruby language questions (blocks, modules, metaprogramming, gems, RSpec/Minitest) not specific to the framework, see the sibling `ruby` skill instead.4---56# Ruby on Rails Best Practices78Full-stack Rails 8.1 guide organized as modular rules. Covers MVC core patterns, Active Record, components (jobs, mailer, cable, storage), security, testing, performance, deployment, and debugging.910For core Ruby language topics (blocks/procs/lambdas, modules/mixins, metaprogramming, Bundler/gems, RSpec/Minitest, RuboCop) that aren't Rails-specific, load the sibling `ruby` skill instead.1112## ROUTING: Which rule file to load1314**IF working with models, database queries, associations, validations, or migrations:**15→ Read `rules/core-active-record.md`1617**IF working with routes, controllers, params, sessions, cookies, or filters:**18→ Read `rules/core-routing-and-controllers.md`1920**IF working with views, layouts, partials, ERB templates, or form helpers:**21→ Read `rules/core-views-and-forms.md`2223**IF working with background jobs, emails, or WebSocket channels:**24→ Read `rules/component-jobs-mailer-cable.md`2526**IF working with file uploads or cloud storage:**27→ Read `rules/component-active-storage.md`2829**IF dealing with security concerns (auth, CSRF, XSS, SQL injection, secrets):**30→ Read `rules/security-best-practices.md`3132**IF writing or fixing tests:**33→ Read `rules/testing-patterns.md`3435**IF optimizing performance or configuring for production:**36→ Read `rules/perf-caching-and-deployment.md`3738**IF debugging an error or unexpected behavior:**39→ Read `rules/debug-tools.md`4041**IF building a Rails engine, a custom generator, or Rack middleware:**42→ Read `rules/extending-rails.md`4344**IF new to the MVC request cycle or need a top-level orientation:**45→ Read `rules/core-mvc-request-lifecycle.md` first4647## Rule index4849| Topic | Description | File |50|-------|-------------|------|51| Sections overview | Categories and reading order | [rules/_sections.md](rules/_sections.md) |52| MVC lifecycle | Request pipeline from router to response | [rules/core-mvc-request-lifecycle.md](rules/core-mvc-request-lifecycle.md) |53| Active Record | Models, queries, associations, validations, migrations | [rules/core-active-record.md](rules/core-active-record.md) |54| Routing & Controllers | RESTful routes, params, callbacks, sessions | [rules/core-routing-and-controllers.md](rules/core-routing-and-controllers.md) |55| Views & Forms | ERB, layouts, partials, form helpers | [rules/core-views-and-forms.md](rules/core-views-and-forms.md) |56| Jobs / Mailer / Cable | ActiveJob, ActionMailer, ActionCable | [rules/component-jobs-mailer-cable.md](rules/component-jobs-mailer-cable.md) |57| Active Storage | File uploads, cloud storage | [rules/component-active-storage.md](rules/component-active-storage.md) |58| Security | CSRF, XSS, SQL injection, secrets, auth | [rules/security-best-practices.md](rules/security-best-practices.md) |59| Testing | Unit, integration, system tests | [rules/testing-patterns.md](rules/testing-patterns.md) |60| Performance & Deploy | Caching strategies, Puma, Kamal, Thruster, concurrency | [rules/perf-caching-and-deployment.md](rules/perf-caching-and-deployment.md) |61| Debug | byebug, web console, logging, common errors | [rules/debug-tools.md](rules/debug-tools.md) |62| Extending Rails | Engines, custom generators, Rack middleware | [rules/extending-rails.md](rules/extending-rails.md) |6364## Rule categories by priority6566| Priority | Category | Impact | Prefix |67|----------|----------|--------|--------|68| 1 | MVC core patterns | CRITICAL | `core-` |69| 2 | Components | HIGH | `component-` |70| 3 | Security | HIGH | `security-` |71| 4 | Testing | HIGH | `testing-` |72| 5 | Performance & Deploy | MEDIUM-HIGH | `perf-` |73| 6 | Debug | MEDIUM | `debug-` |74| 7 | Extending Rails | LOW-MEDIUM | (none, see `extending-rails.md`) |7576## Coverage and maintenance7778- Coverage map: `rules/_coverage-map.md`79- Source: https://guides.rubyonrails.org/ (Rails 8.1.3) and https://rubyonrails.org/docs80- Update this skill when Rails version changes or when new guides are published.8182## Rails CLI quick reference8384```bash85rails new myapp # new full-stack app86rails new myapp --api # API-only mode87rails generate model Post title:string body:text88rails generate controller Posts index show89rails generate migration AddAuthorToPosts author:references90rails db:migrate91rails db:rollback92rails routes # list all routes93rails console # interactive REPL94rails test # run test suite95rails server # start dev server (localhost:3000)96```
display-design-studio