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, and debugging.
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 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, concurrency | rules/perf-caching-and-deployment.md |
| Debug | byebug, web console, logging, common errors | rules/debug-tools.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- |
Coverage and maintenance
- Coverage map:
rules/_coverage-map.md - Source: https://guides.rubyonrails.org/ (Rails 8.1.2)
- 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)