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

• Coverage map: rules/_coverage-map.md
• Source: https://guides.rubyonrails.org/ (Rails 8.1.3) and https://rubyonrails.org/docs
• Update this skill when Rails version changes or when new guides are published.

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)