SKILL.md
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](rules/sections.md) |
| MVC lifecycle | Request pipeline from router to response | [rules/core-mvc-request-lifecycle.md](rules/core-mvc-request-lifecycle.md) |
| Active Record | Models, queries, associations, validations, migrations | [rules/core-active-record.md](rules/core-active-record.md) |
| Routing & Controllers | RESTful routes, params, callbacks, sessions | [rules/core-routing-and-controllers.md](rules/core-routing-and-controllers.md) |
| Views & Forms | ERB, layouts, partials, form helpers | [rules/core-views-and-forms.md](rules/core-views-and-forms.md) |
| Jobs / Mailer / Cable | ActiveJob, ActionMailer, ActionCable | [rules/component-jobs-mailer-cable.md](rules/component-jobs-mailer-cable.md) |
| Active Storage | File uploads, cloud storage | [rules/component-active-storage.md](rules/component-active-storage.md) |
| Security | CSRF, XSS, SQL injection, secrets, auth | [rules/security-best-practices.md](rules/security-best-practices.md) |
| Testing | Unit, integration, system tests | [rules/testing-patterns.md](rules/testing-patterns.md) |
| Performance & Deploy | Caching strategies, Puma, Kamal, Thruster, concurrency | [rules/perf-caching-and-deployment.md](rules/perf-caching-and-deployment.md) |
| Debug | byebug, web console, logging, common errors | [rules/debug-tools.md](rules/debug-tools.md) |
| Extending Rails | Engines, custom generators, Rack middleware | [rules/extending-rails.md](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)